@pdsjs/spaces 1.0.0

package/src/handlers/auth.js

@@ -0,0 +1,436 @@
+// @pdsjs/spaces/handlers/auth - the space auth chain.
+//
+//   app -> PDS.getDelegationToken        (OAuth) proves the user delegated
+//   app -> authority.getSpaceCredential  exchanges it for a credential
+//   app -> repo host.<read endpoints>    presents the credential
+//
+// The delegation token says only that the user delegated to *someone*; which
+// app is acting is established separately by a client attestation, which the
+// authority verifies itself.
+
+import { ScopePermissions } from '@pdsjs/core/scope';
+import {
+  didKeyResolver,
+  spaceHostAudience,
+  spaceHostEndpoint,
+  spaceSigningKey,
+} from '../authority.js';
+import { createServiceAuth } from '../service-auth.js';
+import {
+  createSpaceToken,
+  parseSpaceToken,
+  SpaceTokenError,
+  verifySpaceToken,
+} from '../token.js';
+import { parseSpaceUri } from '../uri.js';
+
+/**
+ * @param {string} error
+ * @param {string} message
+ * @param {number} [status]
+ * @returns {Response}
+ */
+function errorResponse(error, message, status = 400) {
+  return Response.json({ error, message }, { status });
+}
+
+/**
+ * @param {unknown} err
+ * @returns {Response}
+ */
+function tokenErrorResponse(err) {
+  if (err instanceof SpaceTokenError) {
+    return errorResponse(err.code, err.message, 401);
+  }
+  throw err;
+}
+
+/**
+ * @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 createAuthRoutes(ctx) {
+  const { spaceStorage, getDid, getSigner, resolveDid, verifier } = ctx;
+  const getSigningKey = didKeyResolver(resolveDid);
+
+  return {
+    // PDS role: mint a token proving this user delegated to the caller. Signed
+    // by the user's own #atproto key and addressed to the authority's space
+    // host, so it is useless anywhere else and expires in a minute.
+    '/xrpc/com.atproto.space.getDelegationToken': {
+      auth: 'required',
+      handler: async (_request, url, auth) => {
+        const space = url.searchParams.get('space');
+        if (!space) return errorResponse('InvalidRequest', 'space is required');
+        /** @type {{spaceDid: string, spaceType: string, skey: string}} */
+        let parsed;
+        try {
+          parsed = parseSpaceUri(space);
+        } catch {
+          return errorResponse('InvalidSpaceUri', `Not a space uri: ${space}`);
+        }
+
+        const did = /** @type {{did: string}} */ (auth).did;
+
+        // `read` grants whole-space access and with it the delegation token;
+        // `read_self` deliberately does not, since it only ever covers the
+        // holder's own repo and needs no credential.
+        const permissions = new ScopePermissions(
+          /** @type {{scope?: string}} */ (auth).scope,
+        );
+        if (
+          !permissions.allowsSpace({
+            spaceType: parsed.spaceType,
+            authority: parsed.spaceDid,
+            skey: parsed.skey,
+            action: 'read',
+            userDid: did,
+          })
+        ) {
+          return errorResponse(
+            'InvalidToken',
+            `Scope does not permit reading ${space}`,
+            403,
+          );
+        }
+
+        const hosted = await getDid();
+        if (did !== hosted) {
+          return errorResponse(
+            'Forbidden',
+            'Can only mint a delegation token for the hosted account',
+            403,
+          );
+        }
+
+        const token = await createSpaceToken(
+          'delegation',
+          {
+            iss: did,
+            sub: space,
+            aud: spaceHostAudience(parsed.spaceDid),
+          },
+          await getSigner(),
+        );
+        return Response.json({ token });
+      },
+    },
+
+    // Authority role: exchange a delegation token for a space credential.
+    // Unauthenticated at the PDS layer — the delegation token IS the credential
+    // for this call, and is verified here.
+    '/xrpc/com.atproto.space.getSpaceCredential': {
+      method: 'POST',
+      handler: async (request) => {
+        const body = await readJson(request);
+        if (!body) return errorResponse('InvalidRequest', 'Invalid JSON body');
+        const { space, clientAttestation } = body;
+        if (typeof space !== 'string') {
+          return errorResponse('InvalidRequest', 'space is required');
+        }
+        try {
+          parseSpaceUri(space);
+        } catch {
+          return errorResponse('InvalidSpaceUri', `Not a space uri: ${space}`);
+        }
+
+        const header = request.headers.get('authorization') ?? '';
+        const match = header.match(/^Bearer\s+(.+)$/i);
+        if (!match) {
+          return errorResponse(
+            'InvalidDelegationToken',
+            'A delegation token is required',
+            401,
+          );
+        }
+
+        const authorityDid = await getDid();
+        if (!authorityDid) {
+          return errorResponse('SpaceNotFound', 'Server not initialised', 404);
+        }
+
+        /** @type {string} */
+        let userDid;
+        try {
+          const { payload } = await verifySpaceToken('delegation', match[1], {
+            getSigningKey,
+            verifier,
+            aud: spaceHostAudience(authorityDid),
+            sub: space,
+          });
+          userDid = payload.iss;
+        } catch (err) {
+          return tokenErrorResponse(err);
+        }
+
+        // Structural validation only. Full verification means resolving the
+        // client_id to its client-metadata.json, fetching the published JWKS,
+        // and checking the signature against the key named by `kid`. Until then
+        // the attested client_id is advisory, so an allowList is only as strong
+        // as the caller's honesty. The reference implementation carries the same
+        // gap.
+        /** @type {string|undefined} */
+        let clientId;
+        if (clientAttestation) {
+          try {
+            clientId = parseSpaceToken('clientAttestation', clientAttestation)
+              .payload.iss;
+          } catch (err) {
+            return errorResponse(
+              'InvalidClientAttestation',
+              err instanceof Error ? err.message : String(err),
+            );
+          }
+        }
+
+        const spaceRow = await spaceStorage.getSpace(space);
+        if (!spaceRow || !spaceRow.isOwner) {
+          return errorResponse('SpaceNotFound', 'Space not found', 404);
+        }
+        if (spaceRow.deletedAt) {
+          return errorResponse('SpaceDeleted', 'Space has been deleted');
+        }
+
+        // User perimeter.
+        let userAuthorized;
+        if (spaceRow.policy === 'public') {
+          userAuthorized = true;
+        } else if (spaceRow.policy === 'member-list') {
+          userAuthorized = await spaceStorage.isMember(space, userDid);
+        } else if (spaceRow.policy === 'managing-app') {
+          // Delegate the per-user decision to the named service. Any failure —
+          // unresolvable DID, unreachable app, malformed answer — denies rather
+          // than admits.
+          userAuthorized = await checkUserAccess({
+            managingApp: spaceRow.managingApp,
+            authorityDid,
+            space,
+            userDid,
+            clientId,
+            resolveDid,
+            getSigner,
+            fetch: ctx.fetch,
+          });
+        } else {
+          userAuthorized = false;
+        }
+        if (!userAuthorized) {
+          return errorResponse(
+            'UserNotAuthorized',
+            'User not authorized for this space',
+            403,
+          );
+        }
+
+        // App perimeter.
+        if (spaceRow.appAccessType === 'allowList') {
+          if (!clientId || !spaceRow.appAllowed.includes(clientId)) {
+            return errorResponse(
+              'AppNotAuthorized',
+              'Application not authorized for this space',
+              403,
+            );
+          }
+        }
+
+        const credential = await createSpaceToken(
+          'credential',
+          { iss: authorityDid, sub: space },
+          await getSigner(),
+        );
+        return Response.json({ credential });
+      },
+    },
+
+    // Authority role: describe a space.
+    '/xrpc/com.atproto.space.getSpace': {
+      handler: async (_request, url) => {
+        const space = url.searchParams.get('space');
+        if (!space) return errorResponse('InvalidRequest', 'space is required');
+        const row = await spaceStorage.getSpace(space);
+        if (!row || !row.isOwner) {
+          return errorResponse('SpaceNotFound', 'Space not found', 404);
+        }
+        return Response.json({
+          uri: row.uri,
+          config: {
+            $type: 'com.atproto.simplespace.defs#spaceConfig',
+            policy: row.policy,
+            ...(row.managingApp ? { managingApp: row.managingApp } : {}),
+            appAccess:
+              row.appAccessType === 'allowList'
+                ? {
+                    $type: 'com.atproto.simplespace.defs#allowList',
+                    allowed: row.appAllowed,
+                  }
+                : { $type: 'com.atproto.simplespace.defs#open' },
+          },
+        });
+      },
+    },
+
+    // Authority role: the writer set, which is the sync boundary. Accounts that
+    // have written at least one record — not the broader set allowed to write,
+    // which the authority may not even track.
+    '/xrpc/com.atproto.space.listRepos': {
+      handler: async (_request, url) => {
+        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 spaceStorage.getSpace(space);
+        if (!row || !row.isOwner) {
+          return errorResponse('SpaceNotFound', 'Space not found', 404);
+        }
+
+        const { writers, cursor } = await spaceStorage.listSpaceWriters(
+          space,
+          url.searchParams.get('cursor'),
+          limit,
+        );
+        return Response.json({
+          ...(cursor ? { cursor } : {}),
+          repos: writers.map((w) => ({
+            did: w.did,
+            rev: w.rev,
+            hash: toJsonBytes(w.hash),
+          })),
+        });
+      },
+    },
+  };
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {{$bytes: string}}
+ */
+function toJsonBytes(bytes) {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return { $bytes: btoa(binary).replace(/=+$/, '') };
+}
+
+/**
+ * Verify a space credential presented to a repo host.
+ *
+ * @param {Object} opts
+ * @param {string} opts.credential - the raw JWT
+ * @param {string} opts.space - the space the request targets
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @returns {Promise<{iss: string}>}
+ */
+export async function verifySpaceCredential({
+  credential,
+  space,
+  resolveDid,
+  verifier,
+}) {
+  const { spaceDid } = parseSpaceUri(space);
+  const { payload } = await verifySpaceToken('credential', credential, {
+    verifier,
+    // A credential is signed by the authority's space key, so it is verified
+    // without contacting the authority.
+    getSigningKey: async (iss) => {
+      const didDoc = await resolveDid(iss);
+      if (!didDoc) {
+        throw new SpaceTokenError(`Could not resolve ${iss}`, 'DidNotFound');
+      }
+      return spaceSigningKey(didDoc, iss);
+    },
+    sub: space,
+  });
+  if (payload.iss !== spaceDid) {
+    throw new SpaceTokenError(
+      'Credential was not issued by this space authority',
+      'BadJwtIss',
+    );
+  }
+  return { iss: payload.iss };
+}
+
+/**
+ * Ask a space's managing app whether to authorize a user.
+ *
+ * Fails closed: anything short of an explicit `authorized: true` is a refusal,
+ * so an app being down denies access rather than granting it.
+ *
+ * @param {Object} opts
+ * @param {string|null} opts.managingApp - a `did#serviceId` identifier
+ * @param {string} opts.authorityDid
+ * @param {string} opts.space
+ * @param {string} opts.userDid
+ * @param {string|undefined} opts.clientId
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} opts.getSigner
+ * @param {typeof fetch} [opts.fetch]
+ * @returns {Promise<boolean>}
+ */
+export async function checkUserAccess({
+  managingApp,
+  authorityDid,
+  space,
+  userDid,
+  clientId,
+  resolveDid,
+  getSigner,
+  fetch: doFetch,
+}) {
+  if (!managingApp) return false;
+  try {
+    const [appDid] = managingApp.split('#');
+    const didDoc = await resolveDid(appDid);
+    if (!didDoc) return false;
+    const endpoint = spaceHostEndpoint(didDoc, appDid);
+
+    const token = await createServiceAuth({
+      iss: authorityDid,
+      aud: managingApp,
+      lxm: 'com.atproto.simplespace.checkUserAccess',
+      signer: await getSigner(),
+    });
+
+    const url = new URL(
+      `${endpoint}/xrpc/com.atproto.simplespace.checkUserAccess`,
+    );
+    url.searchParams.set('space', space);
+    url.searchParams.set('user', userDid);
+    if (clientId) url.searchParams.set('clientId', clientId);
+
+    const res = await (doFetch ?? fetch)(url, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return false;
+    const body = await res.json();
+    return body?.authorized === true;
+  } catch {
+    return false;
+  }
+}

package/src/handlers/manage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 declare function createManageRoutes(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;
+    fetch?: typeof fetch;
+}): import('@pdsjs/core/pds').Routes;