[WIP] Feat/notification gw handler and webhook

config/file.json

@@ -20,6 +20,7 @@
     "files-scs:config/ldp/metadata-parser/default.json",
     "files-scs:config/ldp/metadata-writer/default.json",
     "files-scs:config/ldp/modes/default.json",
+    "files-scs:config/notification/default.json",
     "files-scs:config/storage/backend/file.json",
     "files-scs:config/storage/key-value/resource-store.json",
     "files-scs:config/storage/middleware/default.json",

config/http/README.md

@@ -22,3 +22,6 @@ The factory used to create the actual server object.
 Support for static files that should be found at a specific path.
 * *default*: The default handler with a favicon and css for the IDP.
   New entries can easily be added for new files.
+
+## Well-Known
+Supports the /.well-known/solid route

config/http/handler/notification.json

@@ -0,0 +1,29 @@
+{
+  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^2.0.0/components/context.jsonld",
+  "import": [
+    "files-scs:config/app/init/initializers/root.json",
+    "files-scs:config/http/well-known/default.json"
+  ],
+  "@graph": [
+    {
+      "comment": "These are all the handlers a request will go through until it is handled.",
+      "@id": "urn:solid-server:default:HttpHandler",
+      "@type": "SequenceHandler",
+      "handlers": [
+        { "@id": "urn:solid-server:default:Middleware" },
+        {
+          "@type": "WaterfallHandler",
+          "handlers": [
+            { "@id": "urn:solid-server:default:StaticAssetHandler" },
+            { "@id": "urn:solid-server:default:SetupHandler" },
+            { "@id": "urn:solid-server:default:WellKnownHandler" },
+            { "@id": "urn:solid-server:default:NotificationHandler" },
+            { "@id": "urn:solid-server:default:AuthResourceHttpHandler" },
+            { "@id": "urn:solid-server:default:IdentityProviderHandler" },
+            { "@id": "urn:solid-server:default:LdpHandler" }
+          ]
+        }
+      ]
+    }
+  ]
+}

config/http/well-known/default.json

@@ -0,0 +1,25 @@
+{
+  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^2.0.0/components/context.jsonld",
+  "@graph": [
+    {
+      "comment": "Selects the /.well-known/solid route.",
+      "@id": "urn:solid-server:default:WellKnownHandler",
+      "@type": "RouterHandler",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
+      "args_allowedMethods": [ "GET" ],
+      "args_allowedPathNames": [ "^/\\.well-known/solid" ],
+      "args_handler": {
+        "comment": "The well-known route.",
+        "@type": "WellKnownHandler",
+        "wellKnownBuilder": {
+          "comment": "Aggregate Well-Known Builder",
+          "@type": "AggregateWellKnownBuilder",
+          "wellKnownBuilders": [
+            { "@id": "urn:solid-server:default:NotificationWellKnownBuilder" }
+          ]
+        }
+      }
+    }
+  ]
+}

config/identity/handler/provider-factory/identity.json

@@ -14,6 +14,7 @@
       "args_storage": { "@id": "urn:solid-server:default:IdpKeyStorage" },
       "args_errorHandler": { "@id": "urn:solid-server:default:ErrorHandler" },
       "args_responseWriter": { "@id": "urn:solid-server:default:ResponseWriter" },
+      "args_jwksKeyGenerator": { "@id": "urn:solid-server:default:JwksKeyGenerator" },
       "config": {
         "claims": {
           "openid": [ "webid", "client_id" ]
@@ -46,6 +47,12 @@
           "RefreshToken": 86400
         }
       }
+    },
+    {
+      "comment": "Generates JWKS",
+      "@id": "urn:solid-server:default:JwksKeyGenerator",
+      "@type": "BasicJwksKeyGenerator",
+      "args_storage": { "@id": "urn:solid-server:default:IdpKeyStorage" }
     }
   ]
 }

config/notification.json

@@ -0,0 +1,40 @@
+{
+  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^2.0.0/components/context.jsonld",
+  "import": [
+    "files-scs:config/app/main/default.json",
+    "files-scs:config/app/init/initialize-prefilled-root.json",
+    "files-scs:config/app/setup/optional.json",
+    "files-scs:config/http/handler/notification.json",
+    "files-scs:config/http/middleware/websockets.json",
+    "files-scs:config/http/server-factory/websockets.json",
+    "files-scs:config/http/static/default.json",
+    "files-scs:config/identity/access/public.json",
+    "files-scs:config/identity/email/default.json",
+    "files-scs:config/identity/handler/default.json",
+    "files-scs:config/identity/ownership/token.json",
+    "files-scs:config/identity/pod/static.json",
+    "files-scs:config/identity/registration/enabled.json",
+    "files-scs:config/ldp/authentication/dpop-bearer.json",
+    "files-scs:config/ldp/authorization/webacl.json",
+    "files-scs:config/ldp/handler/default.json",
+    "files-scs:config/ldp/metadata-parser/default.json",
+    "files-scs:config/ldp/metadata-writer/default.json",
+    "files-scs:config/ldp/modes/default.json",
+    "files-scs:config/notification/default.json",
+    "files-scs:config/storage/backend/file.json",
+    "files-scs:config/storage/key-value/resource-store.json",
+    "files-scs:config/storage/middleware/default.json",
+    "files-scs:config/util/auxiliary/acl.json",
+    "files-scs:config/util/identifiers/suffix.json",
+    "files-scs:config/util/index/default.json",
+    "files-scs:config/util/logging/winston.json",
+    "files-scs:config/util/representation-conversion/default.json",
+    "files-scs:config/util/resource-locker/memory.json",
+    "files-scs:config/util/variables/default.json"
+  ],
+  "@graph": [
+    {
+      "comment": "A single-pod server that uses notifications."
+    }
+  ]
+}

config/notification/default.json

@@ -0,0 +1,145 @@
+{
+  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^2.0.0/components/context.jsonld",
+  "@graph": [
+    {
+      "@id": "urn:solid-server:default:NotificationHandler",
+      "@type": "WaterfallHandler",
+      "handlers": [
+        { "@id": "urn:solid-server:default:NotificationGatewayHandler" },
+        { "@id": "urn:solid-server:default:NotificationSubscriptionHandler" },
+        { "@id": "urn:solid-server:default:WebHookSubscription2021UnsubscribeHandler" },
+        { "@id": "urn:solid-server:default:PodJwksHttpHandler" }
+      ]
+    },
+    {
+      "comment": "The well known builder for all things pertaining to notifications",
+      "@id": "urn:solid-server:default:NotificationWellKnownBuilder",
+      "@type": "AggregateWellKnownBuilder",
+      "wellKnownBuilders": [
+        { "@id": "urn:solid-server:default:BaseNotificationWellKnownBuilder" },
+        { "@id": "urn:solid-server:default:WebHook2021AuthWellKnownBuilder" }
+      ]
+    },
+    {
+      "comment": "The WellKnown Builder for base notifications",
+      "@id": "urn:solid-server:default:BaseNotificationWellKnownBuilder",
+      "@type": "NotificationWellKnownBuilder",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_notificationEndpointPath": "gateway"
+    },
+    {
+      "comment": "The WellKnown Builder for base notifications",
+      "@id": "urn:solid-server:default:WebHook2021AuthWellKnownBuilder",
+      "@type": "WebHook2021AuthWellKnownBuilder",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_jwksEndpointPath": ".well-known/podjwks"
+    },
+    {
+      "comment": "Http Handler for the Pod Jwks route",
+      "@id": "urn:solid-server:default:PodJwksHttpHandler",
+      "@type": "RouterHandler",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
+      "args_allowedMethods": [ "GET" ],
+      "args_allowedPathNames": [ "^/.well-known/podjwks"],
+      "args_handler": {
+        "@type": "PodJwksHttpHandler",
+        "args_jwksKeyGenerator": { "@id": "urn:solid-server:default:JwksKeyGenerator" }
+      }
+    },
+    {
+      "comment": "Handles the notification gateway endpoint.",
+      "@id": "urn:solid-server:default:NotificationGatewayHandler",
+      "@type": "RouterHandler",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
+      "args_allowedMethods": [ "POST" ],
+      "args_allowedPathNames": [ "^/gateway"],
+      "args_handler": { "@id": "urn:solid-server:default:NotificationGatewayParsingHandler" }
+    },
+    {
+      "comment": "Handles notification gateway input parsing.",
+      "@id": "urn:solid-server:default:NotificationGatewayParsingHandler",
+      "@type": "ParsingHttpHandler",
+      "args_requestParser": { "@id": "urn:solid-server:default:RequestParser" },
+      "args_metadataCollector": { "@id": "urn:solid-server:default:OperationMetadataCollector" },
+      "args_errorHandler": { "@id": "urn:solid-server:default:ErrorHandler" },
+      "args_responseWriter": { "@id": "urn:solid-server:default:ResponseWriter" },
+      "args_operationHandler": {
+        "comment": "Handles notification handler behaviour.",
+        "@id": "urn:solid-server:default:NotificationGatewayHttpHandler",
+        "@type": "NotificationGatewayHttpHandler",
+        "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+        "args_subscriptionPath": "subscription",
+        "args_subscriptionHandler": { "@id": "urn:solid-server:default:NotificationSubscriptionHttpHandler"}
+      }
+    },
+    {
+      "comment": "Handles the notification subscription endpoint.",
+      "@id": "urn:solid-server:default:NotificationSubscriptionHandler",
+      "@type": "RouterHandler",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
+      "args_allowedMethods": [ "POST" ],
+      "args_allowedPathNames": [ "^/subscription" ],
+      "args_handler": { "@id": "urn:solid-server:default:NotificationSubscriptionParsingHandler" }
+    },
+    {
+      "comment": "Handles notification subscription input parsing.",
+      "@id": "urn:solid-server:default:NotificationSubscriptionParsingHandler",
+      "@type": "ParsingHttpHandler",
+      "args_requestParser": { "@id": "urn:solid-server:default:RequestParser" },
+      "args_metadataCollector": { "@id": "urn:solid-server:default:OperationMetadataCollector" },
+      "args_errorHandler": { "@id": "urn:solid-server:default:ErrorHandler" },
+      "args_responseWriter": { "@id": "urn:solid-server:default:ResponseWriter" },
+      "args_operationHandler": {
+        "comment": "Handles notification subscription behaviour.",
+        "@id": "urn:solid-server:default:NotificationSubscriptionHttpHandler",
+        "@type": "NotificationSubscriptionHttpHandler",
+        "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+        "args_wsEndpoint": { "@id": "urn:solid-server:default:variable:baseUrl" },
+        "args_credentialsExtractor": { "@id": "urn:solid-server:default:CredentialsExtractor" },
+        "args_permissionReader": { "@id": "urn:solid-server:default:PermissionReader" },
+        "args_notificationStorage": { "@id": "urn:solid-server:default:NotificationStorage"},
+        "args_handlers": [{ "@id": "urn:solid-server:default:WebHookSubscription2021Handler"}],
+        "args_source": { "@id": "urn:solid-server:default:ResourceStore"}
+      }
+    },
+    {
+      "comment": "Handles WebHookSubscription2021 subscriptions",
+      "@id": "urn:solid-server:default:WebHookSubscription2021Handler",
+      "@type": "WebHookSubscription2021Handler",
+      "args_httpClient": {
+        "@id": "urn:solid-server:default:WebHook2021HttpClient",
+        "@type": "WebHookAuthHttpClient",
+        "args_httpClient": { "@id": "urn:solid-server:default:BaseHttpClient" },
+        "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+        "args_jwksKeyGenerator": { "@id": "urn:solid-server:default:JwksKeyGenerator" }
+      },
+      "args_webhookUnsubscribePath": "webhook",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" }
+    },
+    {
+      "comment": "Handles WebHookSubscription2021 unsubscribe route.",
+      "@id": "urn:solid-server:default:WebHookSubscription2021UnsubscribeHandler",
+      "@type": "RouterHandler",
+      "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "args_targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
+      "args_allowedMethods": [ "DELETE" ],
+      "args_allowedPathNames": [ "^/webhook/.*" ],
+      "args_handler": { 
+        "comment": "Handles notification webhook unsubscribe behaviour.",
+        "@id": "urn:solid-server:default:WebHookSubscription2021UnsubscribeHttpHandler",
+        "@type": "WebHookSubscription2021UnsubscribeHttpHandler",
+        "args_baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+        "args_credentialsExtractor": { "@id": "urn:solid-server:default:CredentialsExtractor" },
+        "args_notificationStorage": { "@id": "urn:solid-server:default:NotificationStorage"}
+       }
+    },
+    {
+      "comment": "Handles http calls",
+      "@id": "urn:solid-server:default:BaseHttpClient",
+      "@type": "BaseHttpClient"
+    }
+  ]
+}

config/storage/key-value/memory.json

@@ -33,6 +33,11 @@
       "comment": "Storage used by setup components.",
       "@id": "urn:solid-server:default:SetupStorage",
       "@type": "MemoryMapStorage"
+    },
+    {
+      "comment": "Storage used for notification management.",
+      "@id": "urn:solid-server:default:NotificationStorage",
+      "@type": "MemoryMapStorage"
     }
   ]
 }

config/storage/key-value/resource-store.json

@@ -55,6 +55,14 @@
       "baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
       "container": "/.internal/setup/"
     },
+    {
+      "comment": "Storage used for notification management.",
+      "@id": "urn:solid-server:default:NotificationStorage",
+      "@type": "JsonResourceStorage",
+      "source": { "@id": "urn:solid-server:default:ResourceStore" },
+      "baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
+      "container": "/.internal/notification/"
+    },
     {
       "comment": "Block external access to the storage containers to avoid exposing internal data.",
       "@id": "urn:solid-server:default:PathBasedReader",

package.json

@@ -53,6 +53,7 @@
     "prepare": "npm run build",
     "start": "node ./bin/server.js",
     "start:file": "node ./bin/server.js -c config/file.json -f ./data",
+    "start:notification": "node ./bin/server.js -c config/notification.json -f ./data",
     "test": "npm run test:ts && npm run jest",
     "test:deploy": "test/deploy/validate-package.sh",
     "test:ts": "tsc -p test --noEmit",

src/http/NotificationGatewayHttpHandler.ts

@@ -0,0 +1,72 @@
+import { Readable } from 'stream';
+import type { ResponseDescription } from '../http/output/response/ResponseDescription';
+import { getLoggerFor } from '../logging/LogUtil';
+import { OperationHttpHandler } from '../server/OperationHttpHandler';
+import type { OperationHttpHandlerInput } from '../server/OperationHttpHandler';
+import { NotImplementedHttpError } from '../util/errors/NotImplementedHttpError';
+import { guardStream } from '../util/GuardedStream';
+import { joinUrl, trimTrailingSlashes } from '../util/PathUtil';
+import type { OperationHandlerInput } from './ldp/OperationHandler';
+import type { NotificationSubscriptionHttpHandler } from './NotificationSubscriptionHttpHandler';
+import { OkResponseDescription } from './output/response/OkResponseDescription';
+import { RepresentationMetadata } from './representation/RepresentationMetadata';
+
+export interface NotificationGatewayHttpHandlerArgs {
+  /**
+   * Base URL of the gateway.
+   */
+  baseUrl: string;
+  /**
+   * Relative path of the IDP entry point.
+   */
+  subscriptionPath: string;
+  /**
+    * The notification handler.
+    */
+  subscriptionHandler: NotificationSubscriptionHttpHandler;
+}
+
+/**
+ * Handles the negotiation of notification channels
+ */
+export class NotificationGatewayHttpHandler extends OperationHttpHandler {
+  protected readonly logger = getLoggerFor(this);
+
+  private readonly subscriptionHandler: NotificationSubscriptionHttpHandler;
+  private readonly subscriptionEndpoint: string;
+  private readonly supportedTypes: string[];
+
+  public constructor(args: NotificationGatewayHttpHandlerArgs) {
+    super();
+    // Trimming trailing slashes so the relative URL starts with a slash after slicing this off
+    this.subscriptionEndpoint = trimTrailingSlashes(joinUrl(args.baseUrl, args.subscriptionPath));
+    this.subscriptionHandler = args.subscriptionHandler;
+    this.supportedTypes = this.subscriptionHandler.getSupportedTypes();
+  }
+
+  public async canHandle({ operation }: OperationHandlerInput): Promise<void> {
+    if (operation.method !== 'POST') {
+      throw new NotImplementedHttpError('This handler only supports POST operations');
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public async handle({ operation, request }: OperationHttpHandlerInput): Promise<ResponseDescription | undefined> {
+    const body = await request.read();
+    const json = JSON.parse(body.toString());
+    const requestedTypes: string[] = json.type;
+    const matches = requestedTypes.filter((type): boolean => this.supportedTypes.includes(type));
+    if (matches.length === 0) {
+      throw new NotImplementedHttpError(`This gateway only supports ${this.supportedTypes} notifications`);
+    }
+    const responseJson = {
+      '@context': [ 'https://www.w3.org/ns/solid/notification/v1' ],
+      type: matches[0],
+      endpoint: this.subscriptionEndpoint,
+      features: [],
+    };
+    const representationMetadata = new RepresentationMetadata('application/ld+json');
+    const data = guardStream(Readable.from(JSON.stringify(responseJson)));
+    return new OkResponseDescription(representationMetadata, data);
+  }
+}