@pdsjs/spaces 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdsjs/spaces",
-  "version": "2.0.2",
+  "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.2.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

@@ -51,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

@@ -150,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/dpop.d.ts

@@ -1,3 +1,19 @@
+/**
+ * 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.
  *

package/src/dpop.js

@@ -43,6 +43,42 @@ function firstUse(jti, now) {
   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.
  *

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,10 +11,8 @@
 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;
@@ -24,14 +22,14 @@ export declare function createAuthRoutes(ctx: {
  *
  * @param {Object} ctx
  * @param {() => Promise<string|null>} ctx.getDid
- * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @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: (did: string) => Promise<any>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): (request: Request, space: string, auth: {
     did: string;
@@ -58,7 +56,7 @@ export declare function credentialFromRequest(request: Request): string | null;
  * @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}>}
  */
@@ -66,7 +64,7 @@ export declare function verifyPresentedCredential({ request, credential, space,
     request: Request;
     credential: string;
     space: string;
-    resolveDid: (did: string) => Promise<any>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): Promise<{
     iss: string;
@@ -77,7 +75,7 @@ export declare function verifyPresentedCredential({ request, credential, space,
  * @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').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
@@ -85,7 +83,7 @@ export declare function verifyPresentedCredential({ request, credential, space,
 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;
@@ -103,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>}
  */
@@ -114,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>;

package/src/handlers/auth.js

@@ -15,7 +15,7 @@ import {
   spaceHostEndpoint,
   spaceSigningKey,
 } from '../authority.js';
-import { verifyCredentialProof } from '../dpop.js';
+import { credentialBindingFromProof, verifyCredentialProof } from '../dpop.js';
 import { createServiceAuth } from '../service-auth.js';
 import {
   createSpaceToken,
@@ -62,8 +62,8 @@ async function readJson(request) {
  * @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}
@@ -183,11 +183,35 @@ export function createAuthRoutes(ctx) {
         }
 
         // Checked after the token, so a caller with no credentials at all reads
-        // 401 rather than a complaint about their body. Required, because an
+        // 401 rather than a complaint about their request. 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');
+        //
+        // The key arrives two ways. A DPoP proof demonstrates it, which is what
+        // the Rust implementation sends; a `dpopJkt` body field asserts it,
+        // which is what the reference implementation reads. Both are accepted,
+        // and a caller sending both must agree with itself.
+        /** @type {string|null} */
+        let boundJkt;
+        try {
+          boundJkt = await credentialBindingFromProof(request);
+        } catch (err) {
+          return tokenErrorResponse(err);
+        }
+        if (typeof dpopJkt === 'string' && dpopJkt) {
+          if (boundJkt && boundJkt !== dpopJkt) {
+            return errorResponse(
+              'InvalidRequest',
+              'dpopJkt names a different key than the DPoP proof proves',
+            );
+          }
+          boundJkt ??= dpopJkt;
+        }
+        if (!boundJkt) {
+          return errorResponse(
+            'InvalidRequest',
+            'A DPoP proof or a dpopJkt is required',
+          );
         }
 
         // Structural validation only. Full verification means resolving the
@@ -218,9 +242,12 @@ export function createAuthRoutes(ctx) {
           return errorResponse('SpaceDeleted', 'Space has been deleted');
         }
 
-        // User perimeter.
+        // User perimeter. The authority is the only party who can reconfigure
+        // the space, so no policy may lock it out of its own space.
         let userAuthorized;
-        if (spaceRow.policy === 'public') {
+        if (userDid === authorityDid) {
+          userAuthorized = true;
+        } else if (spaceRow.policy === 'public') {
           userAuthorized = true;
         } else if (spaceRow.policy === 'member-list') {
           userAuthorized = await spaceStorage.isMember(space, userDid);
@@ -262,7 +289,7 @@ export function createAuthRoutes(ctx) {
 
         const credential = await createSpaceToken(
           'credential',
-          { iss: authorityDid, sub: space, dpopJkt },
+          { iss: authorityDid, sub: space, dpopJkt: boundJkt },
           await getSigner(),
         );
         return Response.json({ credential });
@@ -325,7 +352,7 @@ function toJsonBytes(bytes) {
  *
  * @param {Object} ctx
  * @param {() => Promise<string|null>} ctx.getDid
- * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @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
@@ -389,7 +416,7 @@ export function credentialFromRequest(request) {
  * @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}>}
  */
@@ -416,7 +443,7 @@ export async function verifyPresentedCredential({
  * @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').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
@@ -469,8 +496,8 @@ export async function verifySpaceCredential({
  * @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>}
  */

package/src/handlers/manage.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,10 +11,8 @@
 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>;
+    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;

package/src/handlers/manage.js

@@ -212,8 +212,8 @@ async function readJson(request) {
  * @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}
@@ -745,7 +745,7 @@ export function createManageRoutes(ctx) {
  * @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 {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
  * @param {typeof fetch} [ctx.fetch]
  * @param {string} space
  * @returns {Promise<void>}

package/src/handlers/read.d.ts

@@ -3,8 +3,8 @@
  * @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
+ * @param {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
  * @returns {import('@pdsjs/core/pds').Routes}
  */
@@ -12,9 +12,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>;
-    }>;
-    resolveDid: (did: string) => Promise<any>;
+    getSigner: () => Promise<import('../token.js').SpaceSigner>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): import('@pdsjs/core/pds').Routes;

package/src/handlers/read.js

@@ -141,8 +141,8 @@ async function spaceBlobRefs(spaceStorage, space) {
  * @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
+ * @param {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
  * @returns {import('@pdsjs/core/pds').Routes}
  */

package/src/handlers/write.d.ts

@@ -4,8 +4,9 @@
  * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
  * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @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 {{collections: string[], check: (write: {space: string|null, collection: string, rkey: string, prevValue: unknown|null, nextValue: unknown|null}) => Promise<void>}} [ctx.recordGuard]
  * @param {typeof fetch} [ctx.fetch]
  * @returns {import('@pdsjs/core/pds').Routes}
  */
@@ -14,9 +15,17 @@ export declare function createWriteRoutes(ctx: {
     linkBlob: (blobCid: string, recordUri: string, recordTime: number | null) => Promise<void>;
     unlinkBlobs: (recordUri: string) => Promise<void>;
     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;
+    recordGuard?: {
+        collections: string[];
+        check: (write: {
+            space: string | null;
+            collection: string;
+            rkey: string;
+            prevValue: unknown | null;
+            nextValue: unknown | null;
+        }) => Promise<void>;
+    };
     fetch?: typeof fetch;
 }): import('@pdsjs/core/pds').Routes;

package/src/handlers/write.js

@@ -7,7 +7,12 @@
 // Authorization is two checks: the caller may only write its own repo, and the
 // token's `space:` scope must cover the target space, action and collection.
 
-import { createTid, findBlobRefs, recordTimeOf } from '@pdsjs/core/repo';
+import {
+  cborDecode,
+  createTid,
+  findBlobRefs,
+  recordTimeOf,
+} from '@pdsjs/core/repo';
 import { ScopePermissions } from '@pdsjs/core/scope';
 import { spaceHostEndpoint } from '../authority.js';
 import { LtHash } from '../lthash.js';
@@ -170,14 +175,58 @@ function writeAction(write) {
  * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
  * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @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 {{collections: string[], check: (write: {space: string|null, collection: string, rkey: string, prevValue: unknown|null, nextValue: unknown|null}) => Promise<void>}} [ctx.recordGuard]
  * @param {typeof fetch} [ctx.fetch]
  * @returns {import('@pdsjs/core/pds').Routes}
  */
 export function createWriteRoutes(ctx) {
-  const { spaceStorage, linkBlob, unlinkBlobs, getDid, getSigner, resolveDid } =
-    ctx;
+  const {
+    spaceStorage,
+    linkBlob,
+    unlinkBlobs,
+    getDid,
+    getSigner,
+    resolveDid,
+    recordGuard,
+  } = ctx;
+
+  /**
+   * Consult the write guard for one write in a collection it covers. Null to
+   * proceed, the refusal Response otherwise. Read-then-check races the write
+   * queue; the single account that writes here makes that a non-event.
+   * @param {string} space
+   * @param {import('../writer.js').SpaceWriteInput} write
+   * @returns {Promise<Response|null>}
+   */
+  async function guardWrite(space, write) {
+    if (!recordGuard || !recordGuard.collections.includes(write.collection)) {
+      return null;
+    }
+    const prev = await spaceStorage.getSpaceRecord(
+      space,
+      write.collection,
+      write.rkey,
+    );
+    try {
+      await recordGuard.check({
+        space,
+        collection: write.collection,
+        rkey: write.rkey,
+        prevValue: prev ? cborDecode(prev.value) : null,
+        nextValue: write.action === 'delete' ? null : (write.record ?? null),
+      });
+      return null;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code =
+        err instanceof Error && 'code' in err
+          ? String(/** @type {{code: unknown}} */ (err).code)
+          : 'InvalidRequest';
+      return errorResponse(code, message);
+    }
+  }
 
   /**
    * Record which blobs a space write leaves referenced.
@@ -317,6 +366,9 @@ export function createWriteRoutes(ctx) {
     });
     if (scopeError) return scopeError;
 
+    const refused = await guardWrite(body.space, write);
+    if (refused) return refused;
+
     try {
       const commit = await applyWrites(spaceStorage, {
         space: body.space,
@@ -374,11 +426,28 @@ export function createWriteRoutes(ctx) {
             if (body.record === undefined) {
               throw new SpaceWriteError('record is required', 'InvalidRequest');
             }
+            if (
+              body.swapRecord !== undefined &&
+              body.swapRecord !== null &&
+              typeof body.swapRecord !== 'string'
+            ) {
+              throw new SpaceWriteError(
+                'swapRecord must be a CID string or null',
+                'InvalidRequest',
+              );
+            }
             return {
               action: 'put',
               collection: body.collection,
               rkey: body.rkey,
               record: body.record,
+              // A pds.js extension the draft proposal does not have: null
+              // requires that the record does not exist, a CID requires that
+              // exact version, absent skips the check. A server without it
+              // ignores the field, so a client falls back to last-write-wins.
+              ...(body.swapRecord !== undefined
+                ? { swapCid: body.swapRecord }
+                : {}),
             };
           },
           (body, result, did) => ({
@@ -464,6 +533,10 @@ export function createWriteRoutes(ctx) {
           });
           if (scopeError) return scopeError;
         }
+        for (const w of writes) {
+          const refused = await guardWrite(body.space, w);
+          if (refused) return refused;
+        }
 
         try {
           const commit = await applyWrites(spaceStorage, {

package/src/notify.d.ts

@@ -13,7 +13,7 @@
  *
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  * @param {typeof fetch} [ctx.fetch]
  * @param {Object} notice
  * @param {string} notice.authorityDid - the space's authority, which signs
@@ -25,9 +25,7 @@
  */
 export declare function forwardToSyncers(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
-    getSigner: () => Promise<{
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    }>;
+    getSigner: () => Promise<import('./token.js').SpaceSigner>;
     fetch?: typeof fetch;
 }, { authorityDid, space, repo, rev, hash }: {
     authorityDid: string;

package/src/notify.js

@@ -23,7 +23,7 @@ import { createServiceAuth } from './service-auth.js';
  *
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  * @param {typeof fetch} [ctx.fetch]
  * @param {Object} notice
  * @param {string} notice.authorityDid - the space's authority, which signs

package/src/routes.d.ts

@@ -6,11 +6,13 @@
  * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
  * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @param {() => Promise<string|null>} ctx.getDid - the hosted account's DID
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  *   - the account's signing key, used to sign repo commits and space tokens
- * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid - DID document lookup,
  *   injected so this package stays dependency-free
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {import('@pdsjs/core/ports').RecordWriteGuardPort} [ctx.recordGuard]
+ *   - a veto over writes in its named collections, e.g. git branch protection
  * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
  *   calls, so tests can observe them without a network
  * @returns {import('@pdsjs/core/pds').Routes}
@@ -21,10 +23,9 @@ export declare function createSpaceRoutes(ctx: {
     linkBlob: (blobCid: string, recordUri: string, recordTime: number | null) => Promise<void>;
     unlinkBlobs: (recordUri: string) => Promise<void>;
     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;
+    recordGuard?: import('@pdsjs/core/ports').RecordWriteGuardPort;
     fetch?: typeof fetch;
 }): import('@pdsjs/core/pds').Routes;

package/src/routes.js

@@ -18,11 +18,13 @@ import { createWriteRoutes } from './handlers/write.js';
  * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
  * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @param {() => Promise<string|null>} ctx.getDid - the hosted account's DID
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  *   - the account's signing key, used to sign repo commits and space tokens
- * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid - DID document lookup,
  *   injected so this package stays dependency-free
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {import('@pdsjs/core/ports').RecordWriteGuardPort} [ctx.recordGuard]
+ *   - a veto over writes in its named collections, e.g. git branch protection
  * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
  *   calls, so tests can observe them without a network
  * @returns {import('@pdsjs/core/pds').Routes}

package/src/service-auth.d.ts

@@ -5,7 +5,7 @@
  * @param {string} opts.jwt
  * @param {string} opts.aud - our own DID; the token must be addressed to us
  * @param {string} opts.lxm - the method being called
- * @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}>}
  */
@@ -13,7 +13,7 @@ export declare function verifyServiceAuth({ jwt, aud, lxm, resolveDid, verifier,
     jwt: string;
     aud: string;
     lxm: string;
-    resolveDid: (did: string) => Promise<any>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): Promise<{
     iss: string;
@@ -29,14 +29,12 @@ export declare function verifyServiceAuth({ jwt, aud, lxm, resolveDid, verifier,
  * @param {string} opts.iss - our DID
  * @param {string} opts.aud - the service we are calling
  * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @param {import('./token.js').SpaceSigner} opts.signer
  * @returns {Promise<string>}
  */
 export declare function createServiceAuth({ iss, aud, lxm, signer }: {
     iss: string;
     aud: string;
     lxm: string;
-    signer: {
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    };
+    signer: import('./token.js').SpaceSigner;
 }): Promise<string>;

package/src/service-auth.js

@@ -7,7 +7,7 @@
 
 import { base64UrlEncode, bytesToHex } from '@pdsjs/core/crypto';
 import { atprotoSigningKey } from './authority.js';
-import { SpaceTokenError } from './token.js';
+import { assertKeyAlg, SpaceTokenError, signerAlg } from './token.js';
 
 const CLOCK_SKEW_SEC = 5;
 
@@ -43,7 +43,7 @@ function decodeSig(b64) {
  * @param {string} opts.jwt
  * @param {string} opts.aud - our own DID; the token must be addressed to us
  * @param {string} opts.lxm - the method being called
- * @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}>}
  */
@@ -60,14 +60,19 @@ export async function verifyServiceAuth({
   }
   const [headerB64, payloadB64, sigB64] = parts;
 
+  /** @type {any} */
+  let header;
   /** @type {any} */
   let payload;
   try {
-    decodePart(headerB64);
+    header = decodePart(headerB64);
     payload = decodePart(payloadB64);
   } catch {
     throw new SpaceTokenError('could not parse service token', 'BadJwt');
   }
+  if (typeof header?.alg !== 'string' || !header.alg) {
+    throw new SpaceTokenError('missing service token "alg"', 'BadJwt');
+  }
 
   const now = Math.floor(Date.now() / 1000);
   if (typeof payload.exp !== 'number' || now - CLOCK_SKEW_SEC >= payload.exp) {
@@ -91,30 +96,47 @@ export async function verifyServiceAuth({
     );
   }
 
-  const didDoc = await resolveDid(payload.iss);
-  if (!didDoc) {
-    throw new SpaceTokenError(
-      `could not resolve ${payload.iss}`,
-      'DidNotFound',
-    );
-  }
-  const didKey = atprotoSigningKey(didDoc, payload.iss);
   const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const sig = decodeSig(sigB64);
 
-  let valid;
-  try {
-    valid = await verifier.verify(didKey, signingInput, decodeSig(sigB64));
-  } catch (err) {
-    throw new SpaceTokenError(
-      `could not verify service token: ${err instanceof Error ? err.message : String(err)}`,
-      'BadJwtSignature',
-    );
-  }
-  if (!valid) {
-    throw new SpaceTokenError(
-      'invalid service token signature',
-      'BadJwtSignature',
-    );
+  /**
+   * @param {boolean} forceRefresh
+   * @returns {Promise<{didKey: string, valid: boolean}>}
+   */
+  const matchesSignature = async (forceRefresh) => {
+    const didDoc = await resolveDid(payload.iss, { forceRefresh });
+    if (!didDoc) {
+      throw new SpaceTokenError(
+        `could not resolve ${payload.iss}`,
+        'DidNotFound',
+      );
+    }
+    const didKey = atprotoSigningKey(didDoc, payload.iss);
+    assertKeyAlg(didKey, header.alg);
+    try {
+      return {
+        didKey,
+        valid: await verifier.verify(didKey, signingInput, sig),
+      };
+    } catch (err) {
+      throw new SpaceTokenError(
+        `could not verify service token: ${err instanceof Error ? err.message : String(err)}`,
+        'BadJwtSignature',
+      );
+    }
+  };
+
+  const first = await matchesSignature(false);
+  if (!first.valid) {
+    // A resolver that holds its answers can name a key the caller has rotated
+    // away from, and the token is signed by the current one.
+    const fresh = await matchesSignature(true);
+    if (fresh.didKey === first.didKey || !fresh.valid) {
+      throw new SpaceTokenError(
+        'invalid service token signature',
+        'BadJwtSignature',
+      );
+    }
   }
 
   return { iss: payload.iss };
@@ -131,12 +153,12 @@ export async function verifyServiceAuth({
  * @param {string} opts.iss - our DID
  * @param {string} opts.aud - the service we are calling
  * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @param {import('./token.js').SpaceSigner} opts.signer
  * @returns {Promise<string>}
  */
 export async function createServiceAuth({ iss, aud, lxm, signer }) {
   const now = Math.floor(Date.now() / 1000);
-  const header = { typ: 'JWT', alg: 'ES256' };
+  const header = { typ: 'JWT', alg: signerAlg(signer) };
   const payload = {
     iss,
     aud,

package/src/token.d.ts

@@ -21,6 +21,21 @@ export declare const SPACE_TOKEN_TYPES: {
         requireCnf: boolean;
     };
 };
+export type SpaceSigner = {
+    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    /**
+     * - p256 when absent
+     */
+    curve?: 'p256' | 'secp256k1';
+};
+/**
+ * The JWT `alg` for a signer's curve. A verifier resolves the issuer's key,
+ * reads its type, and refuses a header that names another algorithm before it
+ * checks the signature. So a secp256k1 key must stamp ES256K.
+ * @param {SpaceSigner} signer
+ * @returns {string}
+ */
+export declare function signerAlg(signer: SpaceSigner): string;
 export declare class SpaceTokenError extends Error {
     code: string;
     /**
@@ -29,6 +44,18 @@ export declare class SpaceTokenError extends Error {
      */
     constructor(message: string, code?: string);
 }
+/**
+ * Refuse a token whose header names an algorithm the issuer's key cannot
+ * produce. The signature would verify anyway, since the curve comes from the
+ * resolved key rather than the header. The reference implementation rejects
+ * the mismatch, so a token this server accepts has to be one the rest of the
+ * ecosystem accepts too.
+ *
+ * @param {string} didKey
+ * @param {string} alg - the token header's `alg`
+ * @throws {SpaceTokenError}
+ */
+export declare function assertKeyAlg(didKey: string, alg: string): void;
 export type SpaceTokenPayload = {
     iss: string;
     /**
@@ -54,7 +81,7 @@ export type SpaceTokenHeader = {
 /**
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
  * @param {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @param {SpaceSigner} signer
  * @returns {Promise<string>}
  */
 export declare function createSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, opts: {
@@ -65,9 +92,7 @@ export declare function createSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, o
     expiresInSec?: number;
     kid?: string;
     alg?: string;
-}, signer: {
-    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-}): Promise<string>;
+}, signer: SpaceSigner): Promise<string>;
 /**
  * Structural validation only, no signature check. This is as far as we go for
  * client attestations, whose key comes from the client's JWKS rather than a DID
@@ -87,15 +112,16 @@ export declare function parseSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jw
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
  * @param {string} jwt
  * @param {Object} opts
- * @param {(iss: string, kid?: string) => Promise<string>} opts.getSigningKey
- *   - resolves the issuer to a did:key. Given `kid` so it can honour the key id.
+ * @param {(iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>} opts.getSigningKey
+ *   - resolves the issuer to a did:key. Given `kid` so it can honour the key
+ *   id, and `forceRefresh` to read past a held answer after a signature fails.
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
  * @param {string} [opts.aud] - required audience, when the caller knows it
  * @param {string} [opts.sub] - required subject, when the caller knows it
  * @returns {Promise<{header: SpaceTokenHeader, payload: SpaceTokenPayload}>}
  */
 export declare function verifySpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jwt: string, opts: {
-    getSigningKey: (iss: string, kid?: string) => Promise<string>;
+    getSigningKey: (iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
     aud?: string;
     sub?: string;

package/src/token.js

@@ -12,6 +12,7 @@ import {
   base64UrlEncode,
   bytesToHex,
 } from '@pdsjs/core/crypto';
+import { parseDidKey } from '@pdsjs/core/verify';
 
 export const SPACE_TOKEN_TYPES = {
   delegation: {
@@ -44,6 +45,27 @@ export const SPACE_TOKEN_TYPES = {
 
 const CLOCK_SKEW_SEC = 5;
 
+/**
+ * The account key that signs space tokens and repo commits.
+ * @typedef {Object} SpaceSigner
+ * @property {(bytes: Uint8Array) => Promise<Uint8Array>} sign
+ * @property {'p256'|'secp256k1'} [curve] - p256 when absent
+ */
+
+/** The JWT `alg` each curve signs under. */
+const JWT_ALG = { p256: 'ES256', secp256k1: 'ES256K' };
+
+/**
+ * The JWT `alg` for a signer's curve. A verifier resolves the issuer's key,
+ * reads its type, and refuses a header that names another algorithm before it
+ * checks the signature. So a secp256k1 key must stamp ES256K.
+ * @param {SpaceSigner} signer
+ * @returns {string}
+ */
+export function signerAlg(signer) {
+  return JWT_ALG[signer.curve ?? 'p256'];
+}
+
 export class SpaceTokenError extends Error {
   /**
    * @param {string} message
@@ -56,6 +78,35 @@ export class SpaceTokenError extends Error {
   }
 }
 
+/**
+ * Refuse a token whose header names an algorithm the issuer's key cannot
+ * produce. The signature would verify anyway, since the curve comes from the
+ * resolved key rather than the header. The reference implementation rejects
+ * the mismatch, so a token this server accepts has to be one the rest of the
+ * ecosystem accepts too.
+ *
+ * @param {string} didKey
+ * @param {string} alg - the token header's `alg`
+ * @throws {SpaceTokenError}
+ */
+export function assertKeyAlg(didKey, alg) {
+  let expected;
+  try {
+    expected = JWT_ALG[parseDidKey(didKey).curve];
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not read the issuer key: ${err instanceof Error ? err.message : String(err)}`,
+      'BadJwtSignature',
+    );
+  }
+  if (alg !== expected) {
+    throw new SpaceTokenError(
+      `token alg ${alg} does not match the issuer key, which signs ${expected}`,
+      'BadJwtSignature',
+    );
+  }
+}
+
 /**
  * @typedef {Object} SpaceTokenPayload
  * @property {string} iss
@@ -101,7 +152,7 @@ function decodeJsonPart(b64, part) {
 /**
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
  * @param {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @param {SpaceSigner} signer
  * @returns {Promise<string>}
  */
 export async function createSpaceToken(type, opts, signer) {
@@ -115,7 +166,7 @@ export async function createSpaceToken(type, opts, signer) {
 
   const iat = Math.floor(Date.now() / 1000);
   /** @type {SpaceTokenHeader} */
-  const header = { alg: opts.alg ?? 'ES256', typ: spec.typ };
+  const header = { alg: opts.alg ?? signerAlg(signer), typ: spec.typ };
   const kid = opts.kid ?? spec.kid;
   if (kid) header.kid = kid;
 
@@ -197,8 +248,9 @@ export function parseSpaceToken(type, jwt) {
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
  * @param {string} jwt
  * @param {Object} opts
- * @param {(iss: string, kid?: string) => Promise<string>} opts.getSigningKey
- *   - resolves the issuer to a did:key. Given `kid` so it can honour the key id.
+ * @param {(iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>} opts.getSigningKey
+ *   - resolves the issuer to a did:key. Given `kid` so it can honour the key
+ *   id, and `forceRefresh` to read past a held answer after a signature fails.
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
  * @param {string} [opts.aud] - required audience, when the caller knows it
  * @param {string} [opts.sub] - required subject, when the caller knows it
@@ -224,19 +276,31 @@ export async function verifySpaceToken(type, jwt, opts) {
     );
   }
 
+  /**
+   * @param {string} didKey
+   * @returns {Promise<boolean>}
+   */
+  const matchesSignature = async (didKey) => {
+    assertKeyAlg(didKey, header.alg);
+    try {
+      return await opts.verifier.verify(didKey, signingInput, sig);
+    } catch (err) {
+      throw new SpaceTokenError(
+        `could not verify token signature: ${err instanceof Error ? err.message : String(err)}`,
+        'BadJwtSignature',
+      );
+    }
+  };
+
   const didKey = await opts.getSigningKey(payload.iss, header.kid);
-  let valid;
-  try {
-    valid = await opts.verifier.verify(didKey, signingInput, sig);
-  } catch (err) {
-    throw new SpaceTokenError(
-      `could not verify token signature: ${err instanceof Error ? err.message : String(err)}`,
-      'BadJwtSignature',
-    );
-  }
-  if (!valid) {
-    throw new SpaceTokenError('invalid token signature', 'BadJwtSignature');
+  if (await matchesSignature(didKey)) return { header, payload };
+
+  // A resolver that holds its answers can name a key the issuer has rotated
+  // away from, and the token is signed by the current one.
+  const freshDidKey = await opts.getSigningKey(payload.iss, header.kid, true);
+  if (freshDidKey !== didKey && (await matchesSignature(freshDidKey))) {
+    return { header, payload };
   }
 
-  return { header, payload };
+  throw new SpaceTokenError('invalid token signature', 'BadJwtSignature');
 }

package/src/writer.d.ts

@@ -23,6 +23,13 @@ export type SpaceWriteInput = {
      * - required for everything but delete
      */
     record?: Object;
+    /**
+     * - compare-and-swap: the CID the record must
+     * currently have, or null to require that it does not exist. Absent means no
+     * check. Checked inside the per-space queue, so the comparison and the commit
+     * cannot interleave with another write.
+     */
+    swapCid?: string | null;
 };
 export type SpaceWriteResult = {
     action: 'create' | 'update' | 'delete';
@@ -43,6 +50,10 @@ export type SpaceWriteResult = {
  * @property {string} collection
  * @property {string} rkey
  * @property {Object} [record] - required for everything but delete
+ * @property {string|null} [swapCid] - compare-and-swap: the CID the record must
+ *   currently have, or null to require that it does not exist. Absent means no
+ *   check. Checked inside the per-space queue, so the comparison and the commit
+ *   cannot interleave with another write.
  */
 /**
  * @typedef {Object} SpaceWriteResult

package/src/writer.js

@@ -88,6 +88,10 @@ function serialize(storage, space, fn) {
  * @property {string} collection
  * @property {string} rkey
  * @property {Object} [record] - required for everything but delete
+ * @property {string|null} [swapCid] - compare-and-swap: the CID the record must
+ *   currently have, or null to require that it does not exist. Absent means no
+ *   check. Checked inside the per-space queue, so the comparison and the commit
+ *   cannot interleave with another write.
  */
 
 /**
@@ -150,6 +154,12 @@ export async function applyWrites(storage, { space, writes, now }) {
         ? /** @type {string|null} */ (staged.get(key))
         : await storage.getSpaceRecordCid(space, collection, rkey);
 
+      if (write.swapCid !== undefined && write.swapCid !== prev) {
+        throw new SpaceWriteError(
+          `Record ${collection}/${rkey} is at ${prev ?? 'no version'}, expected ${write.swapCid ?? 'no record'}`,
+          'InvalidSwap',
+        );
+      }
       if (write.action === 'create' && prev) {
         throw new SpaceRecordAlreadyExistsError(collection, rkey);
       }