From 006466e02f04344a88a4ec628c7b8a82c9e89993 Mon Sep 17 00:00:00 2001 From: Laurens Debackere Date: Tue, 30 Jun 2026 15:54:50 +0200 Subject: [PATCH 1/2] Integrate core notification data model into lws10-core Move the general notification concepts (discovery, envelope data model, activity types, subscription model) from lws10-notifications into lws10-core/Notifications.html, following the same pattern used for authentication (core data model in lws10-core, channel-specific suites in separate specs). lws10-notifications is restructured to contain only the Webhook notification suite, analogous to lws10-authn-openid for authentication. Changes: - Add lws10-core/Notifications.html with core notification data model - Add notification terms to lws10-core terminology section - Add Notifications section to lws10-core/index.html - Add notification security/privacy considerations to core - Rewrite lws10-notifications as Webhook notification suite referencing core definitions via LWS10-CORE Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- lws10-core/Notifications.html | 355 ++++++++++ lws10-core/Privacy-Considerations.html | 22 + lws10-core/Security-Considerations.html | 17 + lws10-core/index.html | 9 + lws10-notifications/index.html | 883 +++++------------------- 5 files changed, 583 insertions(+), 703 deletions(-) create mode 100644 lws10-core/Notifications.html diff --git a/lws10-core/Notifications.html b/lws10-core/Notifications.html new file mode 100644 index 0000000..e315188 --- /dev/null +++ b/lws10-core/Notifications.html @@ -0,0 +1,355 @@ +

+ This section defines a mechanism for clients to receive timely updates about changes to + resources managed by a linked web storage server. This specification defines a common + notification data model and a subscription mechanism; specific delivery channels are + described in separate notification suite specifications. +

+ +
+

Notification Discovery

+ +

+ A storage MAY support notifications. A storage that supports notifications MUST + advertise a service object in the service array of its storage description + resource with type equal to NotificationService. +

+ +

+ The service object MUST include a serviceEndpoint property whose value + is the URI of the subscription endpoint. The service object MUST include a + subscriptionType property whose value is an array of strings, each + identifying a supported subscription type. +

+ +

+ Additional properties MAY be present on the service object. +

+ + 
+{
+  "@context": ["https://www.w3.org/ns/lws/v1"],
+  "id": "https://storage.example/",
+  "type": "Storage",
+  "service": [{
+    "type": "NotificationService",
+    "serviceEndpoint": "https://notification.example/subscriptions",
+    "subscriptionType": [
+      "WebhookSubscription"
+    ]
+  }]
+}
+
+ +

+ A server is not required to support all subscription types. The + subscriptionType array advertises exactly which types are available. +

+
+ +
+

Notification Data Model

+ +

+ A notification is represented as a JSON-LD document with a + Notification type. The envelope carries metadata about the delivery + context and wraps an Activity Streams 2.0 [[ACTIVITYSTREAMS-CORE]] [[ACTIVITYSTREAMS-VOCABULARY]] + activity describing the event. +

+ +
+

Envelope Properties

+ +

+ A notification envelope has the following properties: +

+ +
    +
  • + type — REQUIRED. The value MUST be the string + Notification. +
    • +
  • + storage — REQUIRED. A URI identifying the LWS storage with + which the notification is associated. +
    • +
  • + activity — REQUIRED. A JSON object or an array of JSON objects, + each conforming to the Activity Streams 2.0 data model, describing the event or + events that occurred. See . +
    • +
+ + 
+{
+  "@context": [
+    "https://www.w3.org/ns/lws/v1",
+    "https://www.w3.org/ns/activitystreams"
+  ],
+  "type": "Notification",
+  "storage": "https://storage.example/",
+  "activity": {
+    "id": "ec4dcc48-6581-4232-81c9-584525a98693",
+    "type": ["Delete"],
+    "object": {
+      "id": "https://storage.example/alice/notes/shopping.txt",
+      "type": ["DataResource"]
+    },
+    "origin": "https://storage.example/alice/notes/",
+    "published": "2026-03-26T10:30:00Z"
+  }
+}
+
+
+ +
+

Activity Properties

+ +

+ Each activity object within the activity property MUST conform to the + Activity Streams 2.0 data model and MUST include the following properties: +

+ +
    +
  • + id — REQUIRED. A string uniquely identifying the activity. +
    • +
  • + type — REQUIRED. An array of strings containing at least one + Activity Streams 2.0 activity type. +
    • +
  • + object — REQUIRED. A JSON object identifying the resource + that the notification is about. The object MUST include the + following properties: +
      +
    • + id — REQUIRED. The URI of the resource. +
      • +
    • + type — REQUIRED. An array of strings containing at least + one resource type. Values defined by this specification include + Container and DataResource. Additional type values + MAY be included. +
      • +
    +
    • +
  • + published — REQUIRED. A datetime value conforming to + [[!RFC3339]] indicating when the activity occurred. +
    • +
+ +

+ The following properties are OPTIONAL: +

+ +
    +
  • + actor — a URI identifying the agent that performed the action. +
    • +
  • + target — a URI identifying the container into which the + resource was added. Used with Create activities. +
    • +
  • + origin — a URI identifying the container from which the + resource was removed. Used with Delete activities. +
    • +
+
+ +
+

Activity Types

+ +

+ A server MUST support the following Activity Streams 2.0 activity types to + indicate LWS resource changes: +

+ +
    +
  • + Create — a new resource was created in a container. The + target field indicates the container to which the resource was added. +
    • +
  • + Update — an existing resource's content or metadata was modified. +
    • +
  • + Delete — a resource was removed. The origin field + indicates the container from which the resource was removed. +
    • +
+ +

+ Other activity types MAY also be supported. +

+
+ +
+

Batching Notifications

+ +

+ A server MAY combine multiple activities into a single notification envelope by + providing an array of activity objects as the value of the activity + property. +

+ + 
+{
+  "@context": [
+    "https://www.w3.org/ns/lws/v1",
+    "https://www.w3.org/ns/activitystreams"
+  ],
+  "type": "Notification",
+  "storage": "https://storage.example/",
+  "activity": [
+    {
+      "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
+      "type": ["Create"],
+      "object": {
+        "id": "https://storage.example/alice/notes/meeting.txt",
+        "type": ["DataResource"]
+      },
+      "target": "https://storage.example/alice/notes/",
+      "published": "2026-03-26T10:30:00Z"
+    },
+    {
+      "id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
+      "type": ["Update"],
+      "object": {
+        "id": "https://storage.example/alice/profile",
+        "type": ["DataResource"]
+      },
+      "published": "2026-03-26T10:30:01Z"
+    }
+  ]
+}
+
+
+
+ +
+

Subscriptions

+ +

+ To receive notifications, a subscriber creates a subscription by sending + an authenticated POST request to the serviceEndpoint of the + NotificationService. The request body MUST conform to the + application/lws+json media type. +

+ +
+

Subscription Request

+ +

+ A subscription request MUST contain the following fields: +

+ +
    +
  • + type — REQUIRED. A string identifying the subscription type. + The value MUST be one of the types listed in the subscriptionType + array of the NotificationService. +
    • +
  • + topic — REQUIRED. An array of URIs identifying the resources + included in the subscription. +
    • +
+ +

+ A subscription request MAY contain additional fields as required by the specific + subscription type. +

+ + 
+POST /subscriptions HTTP/2
+Host: notification.example
+Authorization: Bearer <access-token>
+Content-Type: application/lws+json
+
+{
+  "@context": ["https://www.w3.org/ns/lws/v1"],
+  "type": "WebhookSubscription",
+  "topic": [
+    "https://storage.example/alice/notes/",
+    "https://storage.example/alice/profile"
+  ],
+  "inbox": "https://receiver.example/hooks/lws"
+}
+
+
+ +
+

Subscription Scope

+ +

+ A subscription to a container is recursive: the subscriber receives + notifications for the container itself and for all resources transitively contained + in that container. A subscription to a data resource applies only to that + individual resource. +

+
+ +
+

Subscription Authorization

+ +

+ A server MUST enforce resource authorization when creating a subscription. + If a subscriber does not have the equivalent of read access to all resources + listed in the topic array, the server MUST reject the subscription + request. +

+ +

+ Authorization MUST also be enforced at notification delivery time. A server MUST + NOT deliver a notification about a resource that the subscriber is + not authorized to read at the time the event occurs. This applies to all resources + within the scope of a subscription, including resources in subcontainers. +

+ +

+ If the subscriber's access to a resource or container within the scope of a + subscription is revoked after the subscription is created, the server + MUST stop delivering notifications for the affected resources. The server SHOULD + NOT terminate the entire subscription unless the subscriber has lost + access to all resources in the topic array. +

+ +

+ Subscription-time authorization verifies that a subscriber has a legitimate + basis for receiving notifications. Delivery-time authorization ensures that + notifications remain consistent with the subscriber's current permissions, + accounting for authorization changes that may occur after the subscription + was created. +

+
+ +
+

Subscription Response

+ +

+ The response to a successful subscription creation request MUST conform to the + application/lws+json media type and MUST contain the following fields: +

+ +
    +
  • + type — REQUIRED. A string equal to the subscription type from + the request. +
    • +
  • + subscription — REQUIRED. A URL representing the subscription. +
    • +
+
+ +
+

Subscription Type Identifiers

+

+ Each notification suite MUST be associated with a subscription type string. + The subscription type string is used in the subscriptionType array of a + NotificationService and in the type field of a subscription request. +

+
+
diff --git a/lws10-core/Privacy-Considerations.html b/lws10-core/Privacy-Considerations.html index b7b6445..bf13873 100644 --- a/lws10-core/Privacy-Considerations.html +++ b/lws10-core/Privacy-Considerations.html @@ -41,3 +41,25 @@

Access Requests and Grants

+
+

Notifications

+ + +
+ diff --git a/lws10-core/Security-Considerations.html b/lws10-core/Security-Considerations.html index 21a1f0f..2b90b2a 100644 --- a/lws10-core/Security-Considerations.html +++ b/lws10-core/Security-Considerations.html @@ -56,3 +56,20 @@

Access Requests and Grants

+
+

Notifications

+ + +
+ diff --git a/lws10-core/index.html b/lws10-core/index.html index 01c7427..1c3dead 100644 --- a/lws10-core/index.html +++ b/lws10-core/index.html @@ -199,6 +199,10 @@

Terminology

  • storage controller — an agent that controls all resources in a storage.
  • storage description — an LWS resource that enumerates and describes the storage root along with services and capabilities of a storage. Its representation conforms to the storage description data model.
  • storage root — a container at the root of a containment hierarchy of a storage. The storage root is the only LWS resource that does not have a parent in the LWS containment hierarchy nor a primary resource.
    • +
  • notification — a message describing an event that has occurred on a resource.
    • +
  • subscription — a registration expressing interest in receiving notifications for a given resource or set of resources.
    • +
  • subscriber — the agent that creates a subscription and receives the resulting notifications.
    • +
  • notification suite — a defined delivery mechanism for a concrete channel through which notifications are sent to a subscriber.
    • @@ -279,6 +283,11 @@

    Delete resource

    +
    +

    Notifications

    +
    +
    +

    Access Requests and Grants

    diff --git a/lws10-notifications/index.html b/lws10-notifications/index.html index 0b83a96..4855b8d 100644 --- a/lws10-notifications/index.html +++ b/lws10-notifications/index.html @@ -2,13 +2,14 @@ - LWS Notifications + LWS 1.0 Notification Suite: Webhooks +