@pdsjs/spaces 2.0.1 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdsjs/spaces",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -20,10 +20,11 @@
     "./car": "./src/car.js",
     "./token": "./src/token.js",
     "./authority": "./src/authority.js",
-    "./service-auth": "./src/service-auth.js"
+    "./service-auth": "./src/service-auth.js",
+    "./admin": "./src/admin.js"
   },
   "dependencies": {
-    "@pdsjs/core": "2.1.0"
+    "@pdsjs/core": "2.3.0"
   },
   "publishConfig": {
     "access": "public"

package/src/admin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @returns {import('@pdsjs/core/ports').SpaceAdminPort}
+ */
+export declare function createSpaceAdmin({ spaceStorage, getDid }: {
+    spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    getDid: () => Promise<string | null>;
+}): import('@pdsjs/core/ports').SpaceAdminPort;

package/src/admin.js

@@ -0,0 +1,115 @@
+// @pdsjs/spaces/admin - space management for the account page.
+//
+// The account page runs behind the owner's own session, so these skip the
+// scope checks the XRPC management endpoints apply to third-party callers.
+// They mutate the same storage the same way com.atproto.simplespace.* does.
+
+import { cborDecode, createTid } from '@pdsjs/core/repo';
+import { LtHash } from './lthash.js';
+import { makeSpaceRow } from './space-row.js';
+import { formatSpaceUri } from './uri.js';
+import { applyWrites } from './writer.js';
+
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<string|null>} ctx.getDid
+ * @returns {import('@pdsjs/core/ports').SpaceAdminPort}
+ */
+export function createSpaceAdmin({ spaceStorage, getDid }) {
+  /** @returns {Promise<string>} */
+  async function requireDid() {
+    const did = await getDid();
+    if (!did) throw new Error('server not initialised');
+    return did;
+  }
+
+  /**
+   * @param {string} space
+   * @returns {Promise<void>}
+   */
+  async function requireOwnedSpace(space) {
+    const row = await spaceStorage.getSpace(space);
+    if (!row?.isOwner || row.deletedAt) {
+      throw new Error(`no such space: ${space}`);
+    }
+  }
+
+  return {
+    async createSpace({ type, skey }) {
+      if (!type.includes('.')) {
+        throw new Error(`space type must be an NSID: ${type}`);
+      }
+      if (skey && skey.length > 512) {
+        throw new Error('skey is too long');
+      }
+      const did = await requireDid();
+      const uri = formatSpaceUri({
+        spaceDid: did,
+        spaceType: type,
+        skey: skey || createTid(),
+      });
+      if (await spaceStorage.getSpace(uri)) {
+        throw new Error(`space already exists: ${uri}`);
+      }
+      await spaceStorage.putSpace(makeSpaceRow(uri, { isOwner: true }));
+      // The owner joins their own space: a member-list space checks membership
+      // before it issues a credential, and that is the default policy.
+      await spaceStorage.addMember(uri, did);
+      return { uri };
+    },
+
+    async addMember(space, did) {
+      if (!did.startsWith('did:')) {
+        throw new Error(`not a DID: ${did}`);
+      }
+      await requireOwnedSpace(space);
+      await spaceStorage.addMember(space, did);
+    },
+
+    async removeMember(space, did) {
+      const owner = await requireDid();
+      if (did === owner) {
+        throw new Error('the owner cannot leave their own space');
+      }
+      await requireOwnedSpace(space);
+      await spaceStorage.removeMember(space, did);
+    },
+
+    async getRecord(space, collection, rkey) {
+      await requireOwnedSpace(space);
+      const row = await spaceStorage.getSpaceRecord(space, collection, rkey);
+      return row ? /** @type {Object} */ (cborDecode(row.value)) : null;
+    },
+
+    async createRecord(space, collection, rkey, record) {
+      await writeRecord(space, 'create', collection, rkey, record);
+    },
+
+    async putRecord(space, collection, rkey, record) {
+      await writeRecord(space, 'put', collection, rkey, record);
+    },
+  };
+
+  /**
+   * @param {string} space
+   * @param {'create'|'put'} action
+   * @param {string} collection
+   * @param {string} rkey
+   * @param {Object} record
+   * @returns {Promise<void>}
+   */
+  async function writeRecord(space, action, collection, rkey, record) {
+    const did = await requireDid();
+    await requireOwnedSpace(space);
+    const commit = await applyWrites(spaceStorage, {
+      space,
+      writes: [{ action, collection, rkey, record }],
+    });
+    // What fireNotifyWrite does after an XRPC write into the owner's own
+    // space: record the owner in the writer set, so listRepos knows this
+    // repo before its first push.
+    const hash = await new LtHash(commit.setHash).digest();
+    await spaceStorage.putSpaceWriter(space, did, commit.rev, hash);
+  }
+}

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
@@ -41,7 +51,7 @@ export declare function spaceHostAudience(spaceDid: string): string;
 /**
  * Build the `getSigningKey` callback verifySpaceToken expects.
  *
- * @param {(did: string) => Promise<any>} resolveDid
- * @returns {(iss: string, kid?: string) => Promise<string>}
+ * @param {import('@pdsjs/core/ports').DidResolverPort} resolveDid
+ * @returns {(iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>}
  */
-export declare function didKeyResolver(resolveDid: (did: string) => Promise<any>): (iss: string, kid?: string) => Promise<string>;
+export declare function didKeyResolver(resolveDid: import('@pdsjs/core/ports').DidResolverPort): (iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>;

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
@@ -132,12 +150,12 @@ export function spaceHostAudience(spaceDid) {
 /**
  * Build the `getSigningKey` callback verifySpaceToken expects.
  *
- * @param {(did: string) => Promise<any>} resolveDid
- * @returns {(iss: string, kid?: string) => Promise<string>}
+ * @param {import('@pdsjs/core/ports').DidResolverPort} resolveDid
+ * @returns {(iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>}
  */
 export function didKeyResolver(resolveDid) {
-  return async (iss, kid) => {
-    const didDoc = await resolveDid(iss);
+  return async (iss, kid, forceRefresh = false) => {
+    const didDoc = await resolveDid(iss, { forceRefresh });
     if (!didDoc) {
       throw new SpaceAuthorityError(`Could not resolve ${iss}`, 'DidNotFound');
     }

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,31 @@
+/**
+ * The key an application asks a credential to be bound to, read from the proof
+ * it presents when it asks.
+ *
+ * A thumbprint named in the request body is a claim: any holder of the
+ * delegation token can make it about a key somebody else controls. A proof
+ * demonstrates possession of the key it names. The proof carries no `ath`,
+ * because a delegation token is an authorization grant rather than an access
+ * token, so there is no bound token to hash.
+ *
+ * @param {Request} request
+ * @returns {Promise<string|null>} the proof's thumbprint, or null when the
+ *   request carries no proof
+ * @throws {SpaceTokenError} when a proof is present but invalid or replayed
+ */
+export declare function credentialBindingFromProof(request: Request): Promise<string | null>;
+/**
+ * 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,121 @@
+// @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;
+}
+
+/**
+ * The key an application asks a credential to be bound to, read from the proof
+ * it presents when it asks.
+ *
+ * A thumbprint named in the request body is a claim: any holder of the
+ * delegation token can make it about a key somebody else controls. A proof
+ * demonstrates possession of the key it names. The proof carries no `ath`,
+ * because a delegation token is an authorization grant rather than an access
+ * token, so there is no bound token to hash.
+ *
+ * @param {Request} request
+ * @returns {Promise<string|null>} the proof's thumbprint, or null when the
+ *   request carries no proof
+ * @throws {SpaceTokenError} when a proof is present but invalid or replayed
+ */
+export async function credentialBindingFromProof(request) {
+  const proof = request.headers.get('dpop');
+  if (!proof) return null;
+
+  /** @type {import('@pdsjs/core/oauth').DpopProofResult} */
+  let parsed;
+  try {
+    parsed = await parseDpopProof(proof, request.method, request.url);
+  } 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');
+  }
+  return parsed.jkt;
+}
+
+/**
+ * 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

@@ -2,8 +2,8 @@
  * @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 {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
  * @param {typeof fetch} [ctx.fetch]
  * @returns {import('@pdsjs/core/pds').Routes}
@@ -11,30 +11,83 @@
 export declare function createAuthRoutes(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
     getDid: () => Promise<string | null>;
-    getSigner: () => Promise<{
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    }>;
-    resolveDid: (did: string) => Promise<any>;
+    getSigner: () => Promise<import('../token.js').SpaceSigner>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
     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 {import('@pdsjs/core/ports').DidResolverPort} 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: import('@pdsjs/core/ports').DidResolverPort;
+    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').DidResolverPort} 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: import('@pdsjs/core/ports').DidResolverPort;
+    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 {import('@pdsjs/core/ports').DidResolverPort} 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;
-    resolveDid: (did: string) => Promise<any>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): Promise<{
     iss: string;
+    jkt: string;
 }>;
 /**
  * Ask a space's managing app whether to authorize a user.
@@ -48,8 +101,8 @@ export declare function verifySpaceCredential({ credential, space, resolveDid, v
  * @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 {import('@pdsjs/core/ports').DidResolverPort} opts.resolveDid
+ * @param {() => Promise<import('../token.js').SpaceSigner>} opts.getSigner
  * @param {typeof fetch} [opts.fetch]
  * @returns {Promise<boolean>}
  */
@@ -59,9 +112,7 @@ export declare function checkUserAccess({ managingApp, authorityDid, space, user
     space: string;
     userDid: string;
     clientId: string | undefined;
-    resolveDid: (did: string) => Promise<any>;
-    getSigner: () => Promise<{
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    }>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
+    getSigner: () => Promise<import('../token.js').SpaceSigner>;
     fetch?: typeof fetch;
 }): Promise<boolean>;