@pdsjs/spaces 2.0.1 → 2.0.2

package/src/handlers/manage.js

@@ -11,13 +11,180 @@
 
 import { createTid } from '@pdsjs/core/repo';
 import { ScopePermissions } from '@pdsjs/core/scope';
+import { namedServiceEndpoint } from '../authority.js';
+import { forwardToSyncers } from '../notify.js';
 import { createServiceAuth, verifyServiceAuth } from '../service-auth.js';
 import { makeSpaceRow } from '../space-row.js';
 import { SpaceTokenError } from '../token.js';
 import { formatSpaceUri, parseSpaceUri } from '../uri.js';
-import { verifySpaceCredential } from './auth.js';
+import {
+  createReadAuthorizer,
+  credentialFromRequest,
+  verifyPresentedCredential,
+} from './auth.js';
+
+// How long a write-notification registration lasts before a syncer has to
+// renew it.
+const REGISTRATION_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** @type {Record<string, string>} */
+const POLICY_TYPES = {
+  'com.atproto.simplespace.defs#publicPolicy': 'public',
+  'com.atproto.simplespace.defs#memberListPolicy': 'member-list',
+  'com.atproto.simplespace.defs#managingAppPolicy': 'managing-app',
+};
+const POLICY_VARIANTS = Object.fromEntries(
+  Object.entries(POLICY_TYPES).map(([type, policy]) => [policy, type]),
+);
+
+/** @type {Record<string, string>} */
+const APP_ACCESS_TYPES = {
+  'com.atproto.simplespace.defs#open': 'open',
+  'com.atproto.simplespace.defs#allowList': 'allowList',
+};
+const APP_ACCESS_VARIANTS = Object.fromEntries(
+  Object.entries(APP_ACCESS_TYPES).map(([type, kind]) => [kind, type]),
+);
+
+// The host defaults, which the older `#spaceConfig` documents and a request
+// carrying no config at all gets.
+const DEFAULT_POLICY = 'member-list';
 
-const POLICIES = ['public', 'member-list', 'managing-app'];
+/**
+ * Read a user policy in either spelling.
+ *
+ * The proposal turned this field from a string into a union while
+ * implementations were shipping. A union arrives as `{$type: '…#publicPolicy'}`
+ * with any managing app inside it; the earlier form is the bare string
+ * `'public'` with `managingApp` beside it, under the key `policy` or the older
+ * `mintPolicy`. Absent, the host default applies rather than a refusal: the
+ * earlier lexicon makes the field optional, and a client written against it
+ * sends nothing.
+ *
+ * @param {unknown} value
+ * @param {unknown} managingApp - the sibling field the string form uses
+ * @returns {{policy: string, managingApp: string|null}|Response}
+ */
+function readPolicy(value, managingApp) {
+  if (value === undefined || value === null) {
+    return { policy: DEFAULT_POLICY, managingApp: null };
+  }
+
+  const asString = typeof value === 'string' ? value : null;
+  const variant = /** @type {{$type?: string, managingApp?: unknown}} */ (
+    asString === null ? value : {}
+  );
+  const named = asString ?? POLICY_TYPES[variant.$type ?? ''];
+
+  if (!named || !POLICY_VARIANTS[named]) {
+    return errorResponse(
+      'UnsupportedPolicy',
+      `Not a policy this host implements: ${asString ?? variant.$type ?? '(none)'}`,
+    );
+  }
+  if (named !== 'managing-app') return { policy: named, managingApp: null };
+
+  // The union carries the managing app inside it; the string form beside it.
+  const app = asString === null ? variant.managingApp : managingApp;
+  if (typeof app !== 'string' || !app) {
+    return errorResponse(
+      'UnsupportedPolicy',
+      'A managing-app policy requires a managingApp',
+    );
+  }
+  return { policy: named, managingApp: app };
+}
+
+/**
+ * Read an appAccess union into the two columns that hold it. Absent, access is
+ * open, which is the default the earlier lexicon documents.
+ *
+ * @param {unknown} value
+ * @returns {{appAccessType: string, appAllowed: string[]}|Response}
+ */
+function readAppAccess(value) {
+  if (value === undefined || value === null) {
+    return { appAccessType: 'open', appAllowed: [] };
+  }
+  const variant = /** @type {{$type?: string, allowed?: unknown}} */ (value);
+  const kind = APP_ACCESS_TYPES[variant.$type ?? ''];
+  if (!kind) {
+    return errorResponse(
+      'UnsupportedAppAccess',
+      `Not an app access policy this host implements: ${variant.$type ?? '(none)'}`,
+    );
+  }
+  if (kind === 'open') return { appAccessType: 'open', appAllowed: [] };
+  if (
+    !Array.isArray(variant.allowed) ||
+    variant.allowed.some((c) => typeof c !== 'string')
+  ) {
+    return errorResponse(
+      'UnsupportedAppAccess',
+      'allowList requires a list of client IDs',
+    );
+  }
+  return { appAccessType: 'allowList', appAllowed: variant.allowed };
+}
+
+/**
+ * Where a request carries its config. The union form puts the fields at the top
+ * level; the earlier form nests them under `config`.
+ *
+ * @param {any} body
+ * @returns {any}
+ */
+function configSource(body) {
+  if (body?.policy !== undefined || body?.appAccess !== undefined) return body;
+  return body?.config ?? {};
+}
+
+/**
+ * Read both policies out of a request in either shape.
+ * @param {any} body
+ * @returns {{policy: string, managingApp: string|null, appAccessType: string, appAllowed: string[]}|Response}
+ */
+function readConfig(body) {
+  const source = configSource(body);
+  const policy = readPolicy(
+    source.policy ?? source.mintPolicy,
+    source.managingApp,
+  );
+  if (policy instanceof Response) return policy;
+  const appAccess = readAppAccess(source.appAccess);
+  if (appAccess instanceof Response) return appAccess;
+  return { ...policy, ...appAccess };
+}
+
+/**
+ * Both spellings of the config on the way out: the union fields at the top
+ * level, and the `#spaceConfig` object beside them. A client reads whichever it
+ * knows, and neither has to guess which server it is talking to.
+ *
+ * @param {import('@pdsjs/core/ports').SpaceRow} row
+ * @returns {Record<string, unknown>}
+ */
+function writeConfig(row) {
+  const appAccess = {
+    $type: APP_ACCESS_VARIANTS[row.appAccessType],
+    ...(row.appAccessType === 'allowList' ? { allowed: row.appAllowed } : {}),
+  };
+  return {
+    policy: {
+      $type: POLICY_VARIANTS[row.policy],
+      ...(row.policy === 'managing-app'
+        ? { managingApp: row.managingApp }
+        : {}),
+    },
+    appAccess,
+    config: {
+      $type: 'com.atproto.simplespace.defs#spaceConfig',
+      policy: row.policy,
+      ...(row.managingApp ? { managingApp: row.managingApp } : {}),
+      appAccess,
+    },
+  };
+}
 
 /**
  * @param {string} error
@@ -53,6 +220,7 @@ async function readJson(request) {
  */
 export function createManageRoutes(ctx) {
   const { spaceStorage, getDid, resolveDid, verifier } = ctx;
+  const authorizeRead = createReadAuthorizer({ getDid, resolveDid, verifier });
 
   /**
    * Management verbs are governed by the `manage=` scope param and are not
@@ -82,6 +250,53 @@ export function createManageRoutes(ctx) {
     return null;
   }
 
+  /**
+   * Check the space credential a subscriber presents, or the Response
+   * explaining why not.
+   * @param {Request} request
+   * @param {string} space
+   * @returns {Promise<Response|null>}
+   */
+  async function requireSpaceCredential(request, space) {
+    const credential = credentialFromRequest(request);
+    if (!credential) {
+      return errorResponse(
+        'AuthenticationRequired',
+        'A space credential is required',
+        401,
+      );
+    }
+    try {
+      await verifyPresentedCredential({
+        request,
+        credential,
+        space,
+        resolveDid,
+        verifier,
+      });
+      return null;
+    } catch (err) {
+      if (err instanceof SpaceTokenError) {
+        return errorResponse(err.code, err.message, 401);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Registrations are the authority's to hold, so this server must govern the
+   * space.
+   * @param {string} space
+   * @returns {Promise<import('@pdsjs/core/ports').SpaceRow|Response>}
+   */
+  async function hostedSpace(space) {
+    const row = await spaceStorage.getSpace(space);
+    if (!row?.isOwner || row.deletedAt) {
+      return errorResponse('SpaceNotFound', 'Space not found', 404);
+    }
+    return row;
+  }
+
   /**
    * Load a space this server owns, or the Response explaining why not.
    * @param {string} space
@@ -105,6 +320,22 @@ export function createManageRoutes(ctx) {
     return row;
   }
 
+  /** @type {import('@pdsjs/core/pds').Route} */
+  const getSpaceRoute = {
+    auth: 'optional',
+    handler: async (request, url, auth) => {
+      const space = url.searchParams.get('space');
+      if (!space) return errorResponse('InvalidRequest', 'space is required');
+      const denied = await authorizeRead(request, space, auth);
+      if (denied) return denied;
+      const row = await spaceStorage.getSpace(space);
+      if (!row?.isOwner) {
+        return errorResponse('SpaceNotFound', 'Space not found', 404);
+      }
+      return Response.json({ uri: row.uri, ...writeConfig(row) });
+    },
+  };
+
   return {
     '/xrpc/com.atproto.simplespace.createSpace': {
       method: 'POST',
@@ -112,17 +343,21 @@ export function createManageRoutes(ctx) {
       handler: async (request, _url, auth) => {
         const body = await readJson(request);
         if (!body) return errorResponse('InvalidRequest', 'Invalid JSON body');
-        const { did, type, skey, config } = body;
-        if (typeof did !== 'string' || typeof type !== 'string') {
-          return errorResponse('InvalidRequest', 'did and type are required');
+        const { type, skey } = body;
+        if (typeof type !== 'string') {
+          return errorResponse('InvalidRequest', 'type is required');
         }
         if (!type.includes('.')) {
           return errorResponse('InvalidType', `Not an NSID: ${type}`);
         }
 
+        // The space is anchored on the authenticated user, who becomes its
+        // owner. This server hosts one account, so any other caller is a miss.
+        // `did` is optional and older clients still send it; it has to name the
+        // caller, since nobody creates a space under another account.
         const hosted = await getDid();
         const caller = /** @type {{did: string}} */ (auth).did;
-        if (did !== hosted || caller !== hosted) {
+        if (caller !== hosted || (body.did && body.did !== caller)) {
           return errorResponse(
             'NotSpaceOwner',
             'Can only create spaces anchored on the hosted account',
@@ -134,7 +369,7 @@ export function createManageRoutes(ctx) {
         }
 
         const uri = formatSpaceUri({
-          spaceDid: did,
+          spaceDid: caller,
           spaceType: type,
           skey: skey || createTid(),
         });
@@ -142,25 +377,21 @@ export function createManageRoutes(ctx) {
         const scopeError = checkManageScope(auth, uri, 'create');
         if (scopeError) return scopeError;
 
+        const config = readConfig(body);
+        if (config instanceof Response) return config;
+
         if (await spaceStorage.getSpace(uri)) {
           return errorResponse('SpaceAlreadyExists', `Exists: ${uri}`);
         }
 
-        const appAccess = config?.appAccess;
         await spaceStorage.putSpace(
-          makeSpaceRow(uri, {
-            isOwner: true,
-            policy: POLICIES.includes(config?.policy)
-              ? config.policy
-              : 'member-list',
-            managingApp: config?.managingApp ?? null,
-            appAccessType:
-              appAccess?.$type === 'com.atproto.simplespace.defs#allowList'
-                ? 'allowList'
-                : 'open',
-            appAllowed: appAccess?.allowed ?? [],
-          }),
+          makeSpaceRow(uri, { isOwner: true, ...config }),
         );
+        // The owner joins their own space. Membership is what a member-list
+        // space checks before it issues a credential, and that is the default
+        // policy, so without this the account that created a space cannot read
+        // it. addMember is a set insert, so re-creating a space is harmless.
+        await spaceStorage.addMember(uri, caller);
         return Response.json({ uri });
       },
     },
@@ -179,21 +410,29 @@ export function createManageRoutes(ctx) {
         const row = await ownedSpace(body.space, auth);
         if (row instanceof Response) return row;
 
-        // Only fields actually present are changed, so a partial update cannot
-        // silently reset the rest of the config.
-        const appAccess = body.appAccess;
-        await spaceStorage.putSpace({
-          ...row,
-          policy: POLICIES.includes(body.policy) ? body.policy : row.policy,
-          managingApp:
-            body.managingApp !== undefined ? body.managingApp : row.managingApp,
-          appAccessType: appAccess
-            ? appAccess.$type === 'com.atproto.simplespace.defs#allowList'
-              ? 'allowList'
-              : 'open'
-            : row.appAccessType,
-          appAllowed: appAccess ? (appAccess.allowed ?? []) : row.appAllowed,
-        });
+        // Both fields are optional, so a partial update cannot silently reset
+        // the rest of the config. Absence has to be read from the request
+        // rather than from readConfig, which fills a missing field with the
+        // host default.
+        const source = configSource(body);
+        let policy = { policy: row.policy, managingApp: row.managingApp };
+        const sent = source.policy ?? source.mintPolicy;
+        if (sent !== undefined) {
+          const read = readPolicy(sent, source.managingApp);
+          if (read instanceof Response) return read;
+          policy = read;
+        }
+        let appAccess = {
+          appAccessType: row.appAccessType,
+          appAllowed: row.appAllowed,
+        };
+        if (source.appAccess !== undefined) {
+          const read = readAppAccess(source.appAccess);
+          if (read instanceof Response) return read;
+          appAccess = read;
+        }
+
+        await spaceStorage.putSpace({ ...row, ...policy, ...appAccess });
         return Response.json({});
       },
     },
@@ -220,6 +459,18 @@ export function createManageRoutes(ctx) {
       },
     },
 
+    // Authority role: describe a space. The config names the member policy and
+    // the clients allowed to reach it, so a caller outside the space perimeter
+    // does not get to read it.
+    '/xrpc/com.atproto.simplespace.getSpace': getSpaceRoute,
+
+    // The proposal moved this method from com.atproto.space to
+    // com.atproto.simplespace while implementations were already shipping, and
+    // both names are in use: the atproto reference PR serves the second,
+    // ngerakines.me/atproto-crates the first. Both answer here until the draft
+    // settles, since a client that guesses wrong reads the feature as absent.
+    '/xrpc/com.atproto.space.getSpace': getSpaceRoute,
+
     '/xrpc/com.atproto.simplespace.addMember': {
       method: 'POST',
       auth: 'required',
@@ -347,6 +598,16 @@ export function createManageRoutes(ctx) {
           body.rev,
           hash,
         );
+        // The authority is the only party that knows who is following this
+        // space, so forwarding is its job. A writer's own host cannot do it: the
+        // registrations are held here.
+        await forwardToSyncers(ctx, {
+          authorityDid: hosted,
+          space: body.space,
+          repo: body.repo,
+          rev: body.rev,
+          hash,
+        });
         return Response.json({});
       },
     },
@@ -357,45 +618,65 @@ export function createManageRoutes(ctx) {
       method: 'POST',
       handler: async (request) => {
         const body = await readJson(request);
-        if (!body?.space || !body?.endpoint) {
+        if (!body?.space || !body?.service) {
           return errorResponse(
             'InvalidRequest',
-            'space and endpoint are required',
+            'space and service are required',
           );
         }
 
-        const match = (request.headers.get('authorization') ?? '').match(
-          /^Bearer\s+(.+)$/i,
-        );
-        if (!match) {
+        const denied = await requireSpaceCredential(request, body.space);
+        if (denied) return denied;
+
+        const owned = await hostedSpace(body.space);
+        if (owned instanceof Response) return owned;
+
+        // The delivery URL comes from the subscriber's own DID document, so a
+        // registration can only ever point at an endpoint that service
+        // published for itself.
+        const didDoc = await resolveDid(body.service.split('#')[0]);
+        const endpoint = didDoc && namedServiceEndpoint(didDoc, body.service);
+        if (!endpoint) {
           return errorResponse(
-            'AuthenticationRequired',
-            'A space credential is required',
-            401,
+            'ServiceNotResolvable',
+            `Could not resolve a service endpoint for ${body.service}`,
           );
         }
-        /** @type {{iss: string}} */
-        let credential;
-        try {
-          credential = await verifySpaceCredential({
-            credential: match[1],
-            space: body.space,
-            resolveDid,
-            verifier,
-          });
-        } catch (err) {
-          if (err instanceof SpaceTokenError) {
-            return errorResponse(err.code, err.message, 401);
-          }
-          throw err;
-        }
 
+        const expiresAt = new Date(Date.now() + REGISTRATION_TTL_MS)
+          .toISOString()
+          .replace(/\.\d{3}Z$/, '.000Z');
         await spaceStorage.putCredentialRecipient(
           body.space,
-          credential.iss,
-          body.endpoint,
-          new Date().toISOString(),
+          body.service,
+          endpoint,
+          expiresAt,
         );
+        return Response.json({ expiresAt });
+      },
+    },
+
+    // Withdrawing a registration. The service identifier is not resolved here:
+    // a subscriber whose DID document has changed must still be able to leave.
+    '/xrpc/com.atproto.space.unregisterNotify': {
+      method: 'POST',
+      handler: async (request) => {
+        const body = await readJson(request);
+        if (!body?.space || !body?.service) {
+          return errorResponse(
+            'InvalidRequest',
+            'space and service are required',
+          );
+        }
+
+        const denied = await requireSpaceCredential(request, body.space);
+        if (denied) return denied;
+
+        const owned = await hostedSpace(body.space);
+        if (owned instanceof Response) return owned;
+
+        // Idempotent: succeeds whether or not a registration existed.
+        await spaceStorage.deleteCredentialRecipient(body.space, body.service);
         return Response.json({});
       },
     },

package/src/handlers/read.d.ts

@@ -1,6 +1,7 @@
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs
  * @param {() => Promise<string|null>} ctx.getDid
  * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
  * @param {(did: string) => Promise<any>} ctx.resolveDid
@@ -9,6 +10,7 @@
  */
 export declare function createReadRoutes(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    blobs: import('@pdsjs/core/ports').BlobPort;
     getDid: () => Promise<string | null>;
     getSigner: () => Promise<{
         sign: (bytes: Uint8Array) => Promise<Uint8Array>;