@pdsjs/spaces 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdsjs/spaces",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -23,7 +23,7 @@
     "./service-auth": "./src/service-auth.js"
   },
   "dependencies": {
-    "@pdsjs/core": "2.0.0"
+    "@pdsjs/core": "2.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/authority.d.ts

@@ -32,6 +32,16 @@ export declare function atprotoSigningKey(didDoc: any, did: string): string;
  * @returns {string}
  */
 export declare function spaceHostEndpoint(didDoc: any, did: string): string;
+/**
+ * Where a service identifier points. A service identifier is a DID with an
+ * optional fragment naming the entry in its DID document. Without a fragment
+ * the account's ordinary PDS entry answers.
+ *
+ * @param {any} didDoc
+ * @param {string} service - e.g. 'did:web:syncer.example#atproto_space_syncer'
+ * @returns {string|null}
+ */
+export declare function namedServiceEndpoint(didDoc: any, service: string): string | null;
 /**
  * The `aud` a delegation token must carry for a given authority.
  * @param {string} spaceDid

package/src/authority.js

@@ -120,6 +120,24 @@ export function spaceHostEndpoint(didDoc, did) {
   return endpoint;
 }
 
+/**
+ * Where a service identifier points. A service identifier is a DID with an
+ * optional fragment naming the entry in its DID document. Without a fragment
+ * the account's ordinary PDS entry answers.
+ *
+ * @param {any} didDoc
+ * @param {string} service - e.g. 'did:web:syncer.example#atproto_space_syncer'
+ * @returns {string|null}
+ */
+export function namedServiceEndpoint(didDoc, service) {
+  const [did, fragment] = service.split('#');
+  return serviceEndpoint(
+    didDoc,
+    did,
+    fragment ? `#${fragment}` : ATPROTO_PDS_ID,
+  );
+}
+
 /**
  * The `aud` a delegation token must carry for a given authority.
  * @param {string} spaceDid

package/src/car.d.ts

@@ -15,16 +15,18 @@ export type SerializedRecord = {
     rkey: string;
     cid: string;
     /**
-     * - DAG-CBOR encoded record
+     * - DAG-CBOR encoded record, absent under
+     * excludeValues
      */
-    value: Uint8Array;
+    value?: Uint8Array;
 };
 /**
  * @typedef {Object} SerializedRecord
  * @property {string} collection
  * @property {string} rkey
  * @property {string} cid
- * @property {Uint8Array} value - DAG-CBOR encoded record
+ * @property {Uint8Array} [value] - DAG-CBOR encoded record, absent under
+ *   excludeValues
  */
 /**
  * Serialize a repo as a CAR: two roots in order — the signed commit, then the
@@ -34,8 +36,15 @@ export type SerializedRecord = {
  * Records are collected up front because the index has to precede the blocks it
  * describes.
  *
+ * Under `excludeValues` the CAR carries the two roots and no other block. The
+ * index still folds into the same set hash, so a syncer authenticates it against
+ * the commit and then fetches only the records it lacks.
+ *
  * @param {import('./commit.js').SignedCommit} commit
  * @param {Iterable<SerializedRecord>} records
+ * @param {{excludeValues?: boolean}} [opts]
  * @returns {Promise<Uint8Array>}
  */
-export declare function serializeRepo(commit: import('./commit.js').SignedCommit, records: Iterable<SerializedRecord>): Promise<Uint8Array>;
+export declare function serializeRepo(commit: import('./commit.js').SignedCommit, records: Iterable<SerializedRecord>, opts?: {
+    excludeValues?: boolean;
+}): Promise<Uint8Array>;

package/src/car.js

@@ -31,7 +31,8 @@ export function byCanonicalKey(a, b) {
  * @property {string} collection
  * @property {string} rkey
  * @property {string} cid
- * @property {Uint8Array} value - DAG-CBOR encoded record
+ * @property {Uint8Array} [value] - DAG-CBOR encoded record, absent under
+ *   excludeValues
  */
 
 /**
@@ -42,11 +43,16 @@ export function byCanonicalKey(a, b) {
  * Records are collected up front because the index has to precede the blocks it
  * describes.
  *
+ * Under `excludeValues` the CAR carries the two roots and no other block. The
+ * index still folds into the same set hash, so a syncer authenticates it against
+ * the commit and then fetches only the records it lacks.
+ *
  * @param {import('./commit.js').SignedCommit} commit
  * @param {Iterable<SerializedRecord>} records
+ * @param {{excludeValues?: boolean}} [opts]
  * @returns {Promise<Uint8Array>}
  */
-export async function serializeRepo(commit, records) {
+export async function serializeRepo(commit, records, opts = {}) {
   /** @type {Map<string, SerializedRecord>} */
   const byPath = new Map();
   for (const record of records) {
@@ -71,10 +77,15 @@ export async function serializeRepo(commit, records) {
   const blocks = [
     { cid: commitRoot, data: commitBytes },
     { cid: indexRoot, data: indexBytes },
-    ...paths.map((path) => {
-      const record = /** @type {SerializedRecord} */ (byPath.get(path));
-      return { cid: record.cid, data: record.value };
-    }),
+    ...(opts.excludeValues
+      ? []
+      : paths.map((path) => {
+          const record = /** @type {SerializedRecord} */ (byPath.get(path));
+          return {
+            cid: record.cid,
+            data: /** @type {Uint8Array} */ (record.value),
+          };
+        })),
   ];
 
   return buildCarFile([commitRoot, indexRoot], blocks);

package/src/dpop.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Check the DPoP proof presented with a space credential.
+ *
+ * @param {Object} opts
+ * @param {Request} opts.request - the request the proof must cover
+ * @param {string} opts.credential - the raw credential, hashed into `ath`
+ * @param {string} opts.jkt - the thumbprint from the credential's `cnf.jkt`
+ * @returns {Promise<void>}
+ * @throws {SpaceTokenError} when the proof is absent, invalid, or replayed
+ */
+export declare function verifyCredentialProof({ request, credential, jkt }: {
+    request: Request;
+    credential: string;
+    jkt: string;
+}): Promise<void>;

package/src/dpop.js

@@ -0,0 +1,85 @@
+// @pdsjs/spaces/dpop - the key a space credential is bound to (RFC 9449).
+//
+// One credential reads a whole space, and the holder presents it to every repo
+// host in that space. A bearer credential would therefore be a shared secret: a
+// host handed one to serve its own repo could replay it against every other host
+// in the space. So the authority binds the credential to a key the application
+// names as a thumbprint, and each request carries a fresh proof signed by that
+// key.
+//
+// The proof itself is verified by @pdsjs/core/oauth, which does the same work
+// for OAuth access tokens. What this module adds is the space rules: the proof
+// is mandatory, and a jti is accepted once.
+
+import { parseDpopProof } from '@pdsjs/core/oauth';
+import { SpaceTokenError } from './token.js';
+
+// parseDpopProof accepts an `iat` up to 300 seconds old, so a jti has to be
+// remembered for longer than that. Otherwise a proof outlives the memory of it
+// and the last few seconds of its life are replayable.
+const JTI_RETENTION_MS = 360_000;
+
+/** @type {Map<string, number>} jti -> the instant it may be forgotten */
+const seenJtis = new Map();
+
+/**
+ * Record a jti, answering whether this is the first time it was presented.
+ *
+ * Held in memory, which is sound for the same reason the write queue in
+ * writer.js is: one space is served by exactly one process, a Node PDS or a
+ * single Durable Object. Expired entries are dropped on each call, so the map
+ * holds one request's worth of traffic rather than growing without bound.
+ *
+ * @param {string} jti
+ * @param {number} now
+ * @returns {boolean}
+ */
+function firstUse(jti, now) {
+  for (const [seen, expiresAt] of seenJtis) {
+    if (expiresAt <= now) seenJtis.delete(seen);
+  }
+  if (seenJtis.has(jti)) return false;
+  seenJtis.set(jti, now + JTI_RETENTION_MS);
+  return true;
+}
+
+/**
+ * Check the DPoP proof presented with a space credential.
+ *
+ * @param {Object} opts
+ * @param {Request} opts.request - the request the proof must cover
+ * @param {string} opts.credential - the raw credential, hashed into `ath`
+ * @param {string} opts.jkt - the thumbprint from the credential's `cnf.jkt`
+ * @returns {Promise<void>}
+ * @throws {SpaceTokenError} when the proof is absent, invalid, or replayed
+ */
+export async function verifyCredentialProof({ request, credential, jkt }) {
+  const proof = request.headers.get('dpop');
+  if (!proof) {
+    throw new SpaceTokenError(
+      'A space credential requires a DPoP proof',
+      'MissingDpopProof',
+    );
+  }
+
+  /** @type {import('@pdsjs/core/oauth').DpopProofResult} */
+  let parsed;
+  try {
+    parsed = await parseDpopProof(
+      proof,
+      request.method,
+      request.url,
+      jkt,
+      credential,
+    );
+  } catch (err) {
+    throw new SpaceTokenError(
+      err instanceof Error ? err.message : String(err),
+      'BadDpopProof',
+    );
+  }
+
+  if (!firstUse(parsed.jti, Date.now())) {
+    throw new SpaceTokenError('DPoP proof replayed', 'BadDpopProof');
+  }
+}

package/src/handlers/auth.d.ts

@@ -19,15 +19,69 @@ export declare function createAuthRoutes(ctx: {
     fetch?: typeof fetch;
 }): import('@pdsjs/core/pds').Routes;
 /**
- * Verify a space credential presented to a repo host.
+ * Build the read check the space endpoints share: the hosted account's own
+ * session, or a space credential for the space being read.
+ *
+ * @param {Object} ctx
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @returns {(request: Request, space: string, auth: {did: string}|null) => Promise<Response|null>}
+ *   a Response to return, or null to proceed
+ */
+export declare function createReadAuthorizer({ getDid, resolveDid, verifier }: {
+    getDid: () => Promise<string | null>;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+}): (request: Request, space: string, auth: {
+    did: string;
+} | null) => Promise<Response | null>;
+/**
+ * The space credential a request presents, or null.
+ *
+ * `DPoP`, never `Bearer`: a credential names the key it is bound to, and a
+ * presentation that proves nothing about that key is what the binding exists to
+ * refuse.
+ *
+ * @param {Request} request
+ * @returns {string|null}
+ */
+export declare function credentialFromRequest(request: Request): string | null;
+/**
+ * Check a presented space credential: the token itself, then the caller's
+ * possession of the key it names.
+ *
+ * The two questions are one function so that no endpoint accepting a credential
+ * can answer the first and forget the second.
  *
  * @param {Object} opts
+ * @param {Request} opts.request - the request the DPoP proof must cover
  * @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 declare function verifyPresentedCredential({ request, credential, space, resolveDid, verifier, }: {
+    request: Request;
+    credential: string;
+    space: string;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+}): Promise<{
+    iss: string;
+}>;
+/**
+ * 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, jkt: string}>} the authority, and the key the
+ *   holder must prove possession of
+ */
 export declare function verifySpaceCredential({ credential, space, resolveDid, verifier, }: {
     credential: string;
     space: string;
@@ -35,6 +89,7 @@ export declare function verifySpaceCredential({ credential, space, resolveDid, v
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): Promise<{
     iss: string;
+    jkt: string;
 }>;
 /**
  * Ask a space's managing app whether to authorize a user.

package/src/handlers/auth.js

@@ -15,6 +15,7 @@ import {
   spaceHostEndpoint,
   spaceSigningKey,
 } from '../authority.js';
+import { verifyCredentialProof } from '../dpop.js';
 import { createServiceAuth } from '../service-auth.js';
 import {
   createSpaceToken,
@@ -142,7 +143,7 @@ export function createAuthRoutes(ctx) {
       handler: async (request) => {
         const body = await readJson(request);
         if (!body) return errorResponse('InvalidRequest', 'Invalid JSON body');
-        const { space, clientAttestation } = body;
+        const { space, dpopJkt, clientAttestation } = body;
         if (typeof space !== 'string') {
           return errorResponse('InvalidRequest', 'space is required');
         }
@@ -181,6 +182,14 @@ export function createAuthRoutes(ctx) {
           return tokenErrorResponse(err);
         }
 
+        // Checked after the token, so a caller with no credentials at all reads
+        // 401 rather than a complaint about their body. Required, because an
+        // unbound credential is a bearer token for the whole space and every
+        // repo host in it would accept a replay of it.
+        if (typeof dpopJkt !== 'string' || !dpopJkt) {
+          return errorResponse('InvalidRequest', 'dpopJkt is required');
+        }
+
         // 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
@@ -202,7 +211,7 @@ export function createAuthRoutes(ctx) {
         }
 
         const spaceRow = await spaceStorage.getSpace(space);
-        if (!spaceRow || !spaceRow.isOwner) {
+        if (!spaceRow?.isOwner) {
           return errorResponse('SpaceNotFound', 'Space not found', 404);
         }
         if (spaceRow.deletedAt) {
@@ -253,40 +262,13 @@ export function createAuthRoutes(ctx) {
 
         const credential = await createSpaceToken(
           'credential',
-          { iss: authorityDid, sub: space },
+          { iss: authorityDid, sub: space, dpopJkt },
           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.
@@ -305,7 +287,7 @@ export function createAuthRoutes(ctx) {
         }
 
         const row = await spaceStorage.getSpace(space);
-        if (!row || !row.isOwner) {
+        if (!row?.isOwner) {
           return errorResponse('SpaceNotFound', 'Space not found', 404);
         }
 
@@ -338,15 +320,107 @@ function toJsonBytes(bytes) {
 }
 
 /**
- * Verify a space credential presented to a repo host.
+ * Build the read check the space endpoints share: the hosted account's own
+ * session, or a space credential for the space being read.
+ *
+ * @param {Object} ctx
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @returns {(request: Request, space: string, auth: {did: string}|null) => Promise<Response|null>}
+ *   a Response to return, or null to proceed
+ */
+export function createReadAuthorizer({ getDid, resolveDid, verifier }) {
+  return async (request, space, auth) => {
+    const hosted = await getDid();
+    if (auth && auth.did === hosted) return null;
+
+    const credential = credentialFromRequest(request);
+    if (!credential) {
+      return errorResponse(
+        'AuthenticationRequired',
+        'A session or 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;
+    }
+  };
+}
+
+/**
+ * The space credential a request presents, or null.
+ *
+ * `DPoP`, never `Bearer`: a credential names the key it is bound to, and a
+ * presentation that proves nothing about that key is what the binding exists to
+ * refuse.
+ *
+ * @param {Request} request
+ * @returns {string|null}
+ */
+export function credentialFromRequest(request) {
+  const match = (request.headers.get('authorization') ?? '').match(
+    /^DPoP\s+(.+)$/i,
+  );
+  return match ? match[1] : null;
+}
+
+/**
+ * Check a presented space credential: the token itself, then the caller's
+ * possession of the key it names.
+ *
+ * The two questions are one function so that no endpoint accepting a credential
+ * can answer the first and forget the second.
  *
  * @param {Object} opts
+ * @param {Request} opts.request - the request the DPoP proof must cover
  * @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 verifyPresentedCredential({
+  request,
+  credential,
+  space,
+  resolveDid,
+  verifier,
+}) {
+  const { iss, jkt } = await verifySpaceCredential({
+    credential,
+    space,
+    resolveDid,
+    verifier,
+  });
+  await verifyCredentialProof({ request, credential, jkt });
+  return { iss };
+}
+
+/**
+ * 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, jkt: string}>} the authority, and the key the
+ *   holder must prove possession of
+ */
 export async function verifySpaceCredential({
   credential,
   space,
@@ -373,7 +447,14 @@ export async function verifySpaceCredential({
       'BadJwtIss',
     );
   }
-  return { iss: payload.iss };
+  // parseSpaceToken refuses a credential without one, so this is reachable only
+  // if that check is relaxed. It stays because the cost of it being wrong is a
+  // credential for a whole space that anyone holding a copy may present.
+  const jkt = payload.cnf?.jkt;
+  if (!jkt) {
+    throw new SpaceTokenError('Credential is not bound to a key', 'BadJwtCnf');
+  }
+  return { iss: payload.iss, jkt };
 }
 
 /**