@pdsjs/spaces 1.0.0

package/src/handlers/manage.js

@@ -0,0 +1,508 @@
+// @pdsjs/spaces/handlers/manage - com.atproto.simplespace and notifications.
+//
+// simplespace is the baseline space-management implementation every PDS must
+// support: spaces anchored on the user's own DID, governed by an explicit member
+// list or a policy.
+//
+// Notifications are best-effort and are not required for eventual consistency.
+// A dropped one is recovered by a later write's notification or by a syncer's
+// periodic sweep, because sync correctness rests on comparing set hashes rather
+// than on receiving every event.
+
+import { createTid } from '@pdsjs/core/repo';
+import { ScopePermissions } from '@pdsjs/core/scope';
+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';
+
+const POLICIES = ['public', 'member-list', 'managing-app'];
+
+/**
+ * @param {string} error
+ * @param {string} message
+ * @param {number} [status]
+ * @returns {Response}
+ */
+function errorResponse(error, message, status = 400) {
+  return Response.json({ error, message }, { status });
+}
+
+/**
+ * @param {Request} request
+ * @returns {Promise<any>}
+ */
+async function readJson(request) {
+  try {
+    return JSON.parse(await request.text());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {typeof fetch} [ctx.fetch]
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export function createManageRoutes(ctx) {
+  const { spaceStorage, getDid, resolveDid, verifier } = ctx;
+
+  /**
+   * Management verbs are governed by the `manage=` scope param and are not
+   * implied by any record action.
+   * @param {{did: string, scope?: string}|null} auth
+   * @param {string} space
+   * @param {string} op
+   * @returns {Response|null}
+   */
+  function checkManageScope(auth, space, op) {
+    const { spaceDid, spaceType, skey } = parseSpaceUri(space);
+    const permissions = new ScopePermissions(auth?.scope);
+    const allowed = permissions.allowsSpaceManage({
+      spaceType,
+      authority: spaceDid,
+      skey,
+      op,
+      userDid: auth?.did,
+    });
+    if (!allowed) {
+      return errorResponse(
+        'InvalidToken',
+        `Scope does not permit ${op} on ${space}`,
+        403,
+      );
+    }
+    return null;
+  }
+
+  /**
+   * Load a space this server owns, or the Response explaining why not.
+   * @param {string} space
+   * @param {{did: string}|null} auth
+   * @returns {Promise<import('@pdsjs/core/ports').SpaceRow|Response>}
+   */
+  async function ownedSpace(space, auth) {
+    const row = await spaceStorage.getSpace(space);
+    if (!row) return errorResponse('SpaceNotFound', 'Space not found', 404);
+    if (!row.isOwner) {
+      return errorResponse(
+        'NotSpaceOwner',
+        'This server is not the authority for that space',
+        403,
+      );
+    }
+    const hosted = await getDid();
+    if (auth && auth.did !== hosted) {
+      return errorResponse('NotSpaceOwner', 'Not the space owner', 403);
+    }
+    return row;
+  }
+
+  return {
+    '/xrpc/com.atproto.simplespace.createSpace': {
+      method: 'POST',
+      auth: 'required',
+      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');
+        }
+        if (!type.includes('.')) {
+          return errorResponse('InvalidType', `Not an NSID: ${type}`);
+        }
+
+        const hosted = await getDid();
+        const caller = /** @type {{did: string}} */ (auth).did;
+        if (did !== hosted || caller !== hosted) {
+          return errorResponse(
+            'NotSpaceOwner',
+            'Can only create spaces anchored on the hosted account',
+            403,
+          );
+        }
+        if (typeof skey === 'string' && skey.length > 512) {
+          return errorResponse('InvalidRequest', 'skey is too long');
+        }
+
+        const uri = formatSpaceUri({
+          spaceDid: did,
+          spaceType: type,
+          skey: skey || createTid(),
+        });
+
+        const scopeError = checkManageScope(auth, uri, 'create');
+        if (scopeError) return scopeError;
+
+        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 ?? [],
+          }),
+        );
+        return Response.json({ uri });
+      },
+    },
+
+    '/xrpc/com.atproto.simplespace.updateSpace': {
+      method: 'POST',
+      auth: 'required',
+      handler: async (request, _url, auth) => {
+        const body = await readJson(request);
+        if (!body?.space) {
+          return errorResponse('InvalidRequest', 'space is required');
+        }
+        const scopeError = checkManageScope(auth, body.space, 'update');
+        if (scopeError) return scopeError;
+
+        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,
+        });
+        return Response.json({});
+      },
+    },
+
+    '/xrpc/com.atproto.simplespace.deleteSpace': {
+      method: 'POST',
+      auth: 'required',
+      handler: async (request, _url, auth) => {
+        const body = await readJson(request);
+        if (!body?.space) {
+          return errorResponse('InvalidRequest', 'space is required');
+        }
+        const scopeError = checkManageScope(auth, body.space, 'delete');
+        if (scopeError) return scopeError;
+
+        const row = await ownedSpace(body.space, auth);
+        if (row instanceof Response) return row;
+
+        await spaceStorage.deleteSpace(body.space, new Date().toISOString());
+        // Best-effort fan-out; a syncer that misses it finds out on its next
+        // credential request, which the authority will refuse.
+        await notifyDeleted(ctx, body.space);
+        return Response.json({});
+      },
+    },
+
+    '/xrpc/com.atproto.simplespace.addMember': {
+      method: 'POST',
+      auth: 'required',
+      handler: async (request, _url, auth) => {
+        const body = await readJson(request);
+        if (!body?.space || !body?.did) {
+          return errorResponse('InvalidRequest', 'space and did are required');
+        }
+        const scopeError = checkManageScope(auth, body.space, 'update');
+        if (scopeError) return scopeError;
+        const row = await ownedSpace(body.space, auth);
+        if (row instanceof Response) return row;
+        await spaceStorage.addMember(body.space, body.did);
+        return Response.json({});
+      },
+    },
+
+    '/xrpc/com.atproto.simplespace.removeMember': {
+      method: 'POST',
+      auth: 'required',
+      handler: async (request, _url, auth) => {
+        const body = await readJson(request);
+        if (!body?.space || !body?.did) {
+          return errorResponse('InvalidRequest', 'space and did are required');
+        }
+        const scopeError = checkManageScope(auth, body.space, 'update');
+        if (scopeError) return scopeError;
+        const row = await ownedSpace(body.space, auth);
+        if (row instanceof Response) return row;
+        // Removing a member does not revoke credentials already issued; those
+        // stay valid until they expire.
+        await spaceStorage.removeMember(body.space, body.did);
+        return Response.json({});
+      },
+    },
+
+    '/xrpc/com.atproto.simplespace.listMembers': {
+      auth: 'required',
+      handler: async (_request, url, auth) => {
+        const space = url.searchParams.get('space');
+        if (!space) return errorResponse('InvalidRequest', 'space is required');
+
+        const raw = url.searchParams.get('limit');
+        const limit = raw === null ? 100 : Number(raw);
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+          return errorResponse(
+            'InvalidRequest',
+            'limit must be an integer between 1 and 1000',
+          );
+        }
+
+        const row = await ownedSpace(space, auth);
+        if (row instanceof Response) return row;
+
+        const { dids, cursor } = await spaceStorage.listMembers(
+          space,
+          url.searchParams.get('cursor'),
+          limit,
+        );
+        return Response.json({
+          ...(cursor ? { cursor } : {}),
+          members: dids.map((did) => ({ did })),
+        });
+      },
+    },
+
+    // A repo host telling this authority that one of its users wrote. Maintains
+    // the writer set, which is what listRepos enumerates as the sync boundary.
+    '/xrpc/com.atproto.space.notifyWrite': {
+      method: 'POST',
+      handler: async (request) => {
+        const body = await readJson(request);
+        if (!body?.space || !body?.repo || !body?.rev) {
+          return errorResponse(
+            'InvalidRequest',
+            'space, repo and rev are required',
+          );
+        }
+
+        const hosted = await getDid();
+        if (!hosted) {
+          return errorResponse('SpaceNotFound', 'Server not initialised', 404);
+        }
+
+        /** @type {{iss: string}} */
+        let caller;
+        try {
+          caller = await verifyServiceAuth({
+            jwt: (request.headers.get('authorization') ?? '').replace(
+              /^Bearer\s+/i,
+              '',
+            ),
+            aud: hosted,
+            lxm: 'com.atproto.space.notifyWrite',
+            resolveDid,
+            verifier,
+          });
+        } catch (err) {
+          if (err instanceof SpaceTokenError) {
+            return errorResponse(err.code, err.message, 401);
+          }
+          throw err;
+        }
+
+        // A repo host may only report its own account's writes.
+        if (caller.iss !== body.repo) {
+          return errorResponse(
+            'Forbidden',
+            'Can only report writes for the calling account',
+            403,
+          );
+        }
+
+        const row = await spaceStorage.getSpace(body.space);
+        if (!row || !row.isOwner) {
+          return errorResponse('SpaceNotFound', 'Space not found', 404);
+        }
+
+        const hash = body.hash?.$bytes
+          ? Uint8Array.from(atob(body.hash.$bytes), (c) => c.charCodeAt(0))
+          : new Uint8Array(0);
+        await spaceStorage.putSpaceWriter(
+          body.space,
+          body.repo,
+          body.rev,
+          hash,
+        );
+        return Response.json({});
+      },
+    },
+
+    // A syncer subscribing to write notifications. Authenticated with a space
+    // credential, so only someone the authority already admitted can subscribe.
+    '/xrpc/com.atproto.space.registerNotify': {
+      method: 'POST',
+      handler: async (request) => {
+        const body = await readJson(request);
+        if (!body?.space || !body?.endpoint) {
+          return errorResponse(
+            'InvalidRequest',
+            'space and endpoint are required',
+          );
+        }
+
+        const match = (request.headers.get('authorization') ?? '').match(
+          /^Bearer\s+(.+)$/i,
+        );
+        if (!match) {
+          return errorResponse(
+            'AuthenticationRequired',
+            'A space credential is required',
+            401,
+          );
+        }
+        /** @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;
+        }
+
+        await spaceStorage.putCredentialRecipient(
+          body.space,
+          credential.iss,
+          body.endpoint,
+          new Date().toISOString(),
+        );
+        return Response.json({});
+      },
+    },
+
+    // An authority telling us one of its spaces is gone.
+    '/xrpc/com.atproto.space.notifySpaceDeleted': {
+      method: 'POST',
+      handler: async (request) => {
+        const body = await readJson(request);
+        if (!body?.space) {
+          return errorResponse('InvalidRequest', 'space is required');
+        }
+
+        const hosted = await getDid();
+        if (!hosted) {
+          return errorResponse('SpaceNotFound', 'Server not initialised', 404);
+        }
+
+        /** @type {{iss: string}} */
+        let caller;
+        try {
+          caller = await verifyServiceAuth({
+            jwt: (request.headers.get('authorization') ?? '').replace(
+              /^Bearer\s+/i,
+              '',
+            ),
+            aud: hosted,
+            lxm: 'com.atproto.space.notifySpaceDeleted',
+            resolveDid,
+            verifier,
+          });
+        } catch (err) {
+          if (err instanceof SpaceTokenError) {
+            return errorResponse(err.code, err.message, 401);
+          }
+          throw err;
+        }
+
+        // Only the space's own authority may declare it deleted.
+        const { spaceDid } = parseSpaceUri(body.space);
+        if (caller.iss !== spaceDid) {
+          return errorResponse(
+            'Forbidden',
+            'Only the space authority may delete a space',
+            403,
+          );
+        }
+
+        const row = await spaceStorage.getSpace(body.space);
+        if (row) {
+          // Flag the member's repo rather than erasing it: the records are the
+          // member's own, and the proposal has repo hosts keep them.
+          await spaceStorage.deleteSpace(body.space, new Date().toISOString());
+        }
+        return Response.json({});
+      },
+    },
+  };
+}
+
+/**
+ * Tell every registered syncer that a space is gone. Best-effort: failures are
+ * swallowed, since a syncer that misses this finds out when its next credential
+ * request is refused.
+ *
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {typeof fetch} [ctx.fetch]
+ * @param {string} space
+ * @returns {Promise<void>}
+ */
+async function notifyDeleted(ctx, space) {
+  const { spaceStorage } = ctx;
+  let recipients;
+  try {
+    recipients = await spaceStorage.listCredentialRecipients(space);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    recipients.map(async (r) => {
+      try {
+        const iss = await ctx.getDid();
+        if (!iss) return;
+        const token = await createServiceAuth({
+          iss,
+          aud: r.serviceDid,
+          lxm: 'com.atproto.space.notifySpaceDeleted',
+          signer: await ctx.getSigner(),
+        });
+        const doFetch = ctx.fetch ?? fetch;
+        await doFetch(
+          `${r.serviceEndpoint}/xrpc/com.atproto.space.notifySpaceDeleted`,
+          {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+              authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({ space }),
+          },
+        );
+      } catch {
+        // Best effort.
+      }
+    }),
+  );
+}

package/src/handlers/read.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export declare function createReadRoutes(ctx: {
+    spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    getDid: () => Promise<string | null>;
+    getSigner: () => Promise<{
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    }>;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+}): import('@pdsjs/core/pds').Routes;