@pdsjs/spaces 2.0.1 → 2.0.3

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: {
@@ -19,24 +20,52 @@ export const SPACE_TOKEN_TYPES = {
     kid: '#atproto',
     expiresInSec: 60,
     requireAud: true,
+    requireCnf: false,
   },
+  // An authority that publishes a dedicated `#atproto_space` key signs with it
+  // and names that key in `kid`. This server signs with the account's own
+  // `#atproto` key, which is the only key a PDS-hosted authority has.
   credential: {
     typ: 'atproto-space-credential+jwt',
-    kid: '#atproto_space',
-    // Multi-use across repo hosts until it expires, so it carries no aud.
+    kid: '#atproto',
+    // Multi-use across repo hosts until it expires, so it carries no aud. It is
+    // bound to the holder's key instead — see dpop.js.
     expiresInSec: 7200,
     requireAud: false,
+    requireCnf: true,
   },
   clientAttestation: {
     typ: 'atproto-client-attestation+jwt',
     kid: undefined,
     expiresInSec: 60,
     requireAud: true,
+    requireCnf: false,
   },
 };
 
 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
@@ -49,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
@@ -57,6 +115,7 @@ export class SpaceTokenError extends Error {
  * @property {number} iat
  * @property {number} exp
  * @property {string} jti
+ * @property {{jkt: string}} [cnf] - the key the holder must prove possession of
  */
 
 /**
@@ -92,8 +151,8 @@ function decodeJsonPart(b64, part) {
 
 /**
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
- * @param {{iss: string, sub: string, aud?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @param {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
+ * @param {SpaceSigner} signer
  * @returns {Promise<string>}
  */
 export async function createSpaceToken(type, opts, signer) {
@@ -101,10 +160,13 @@ export async function createSpaceToken(type, opts, signer) {
   if (spec.requireAud && !opts.aud) {
     throw new SpaceTokenError(`a ${type} token requires an "aud"`);
   }
+  if (spec.requireCnf && !opts.dpopJkt) {
+    throw new SpaceTokenError(`a ${type} token requires a "dpopJkt"`);
+  }
 
   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;
 
@@ -113,6 +175,7 @@ export async function createSpaceToken(type, opts, signer) {
     iss: opts.iss,
     sub: opts.sub,
     ...(opts.aud ? { aud: opts.aud } : undefined),
+    ...(opts.dpopJkt ? { cnf: { jkt: opts.dpopJkt } } : undefined),
     iat,
     exp: iat + (opts.expiresInSec ?? spec.expiresInSec),
     jti: bytesToHex(crypto.getRandomValues(new Uint8Array(16))),
@@ -163,6 +226,9 @@ export function parseSpaceToken(type, jwt) {
   if (spec.requireAud && !payload.aud) {
     throw new SpaceTokenError('missing token "aud"', 'BadJwtAudience');
   }
+  if (spec.requireCnf && !payload.cnf?.jkt) {
+    throw new SpaceTokenError('missing token "cnf.jkt"', 'BadJwtCnf');
+  }
   if (type === 'clientAttestation' && payload.iss !== payload.sub) {
     throw new SpaceTokenError(
       'client attestation "iss" and "sub" must both be the client_id',
@@ -182,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
@@ -209,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);
       }