@pdsjs/spaces 2.0.0 → 2.0.2

package/src/notify.js

@@ -0,0 +1,87 @@
+// @pdsjs/spaces/notify - telling a space's syncers that a repo advanced.
+//
+// A space's writes are never broadcast, which is the point of one. So a service
+// that wants to follow a space registers with the authority through
+// registerNotify, and the authority forwards each write notice it learns of. A
+// syncer that receives one holds a session and can read; the notice itself
+// carries no records, only the rev the repo reached.
+
+import { createServiceAuth } from './service-auth.js';
+
+/**
+ * Forward a write notice to every service registered for this space.
+ *
+ * Best effort, and deliberately so: sync correctness rests on comparing set
+ * hashes, so a syncer that misses a notice finds out on the next one or on its
+ * own next walk. One unreachable recipient must not fail the others, and none of
+ * them may fail the write that produced the notice.
+ *
+ * The caller awaits this, which puts one round trip per recipient in front of
+ * the response. A Worker cancels a promise still running when it answers, and
+ * this package holds no execution context to hand the work to, so backgrounding
+ * it here would mean dropping notifications on Cloudflare.
+ *
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {typeof fetch} [ctx.fetch]
+ * @param {Object} notice
+ * @param {string} notice.authorityDid - the space's authority, which signs
+ * @param {string} notice.space
+ * @param {string} notice.repo - the account whose repo advanced
+ * @param {string} notice.rev
+ * @param {Uint8Array} notice.hash - the repo's commit hash after the write
+ * @returns {Promise<void>}
+ */
+export async function forwardToSyncers(
+  ctx,
+  { authorityDid, space, repo, rev, hash },
+) {
+  let recipients;
+  try {
+    recipients = await ctx.spaceStorage.listCredentialRecipients(space);
+  } catch {
+    return;
+  }
+  if (recipients.length === 0) return;
+
+  const body = JSON.stringify({ space, repo, rev, hash: toJsonBytes(hash) });
+  const doFetch = ctx.fetch ?? fetch;
+  const signer = await ctx.getSigner();
+
+  await Promise.all(
+    recipients.map(async (recipient) => {
+      try {
+        const token = await createServiceAuth({
+          iss: authorityDid,
+          aud: recipient.serviceDid,
+          lxm: 'com.atproto.space.notifyWrite',
+          signer,
+        });
+        await doFetch(
+          `${recipient.serviceEndpoint}/xrpc/com.atproto.space.notifyWrite`,
+          {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+              authorization: `Bearer ${token}`,
+            },
+            body,
+          },
+        );
+      } catch {
+        // Best effort.
+      }
+    }),
+  );
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {{$bytes: string}}
+ */
+function toJsonBytes(bytes) {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return { $bytes: btoa(binary).replace(/=+$/, '') };
+}

package/src/routes.d.ts

@@ -1,6 +1,10 @@
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs - blobs referenced
+ *   from space records live in the account's ordinary blob store
+ * @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
  *   - the account's signing key, used to sign repo commits and space tokens
@@ -13,6 +17,9 @@
  */
 export declare function createSpaceRoutes(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    blobs: import('@pdsjs/core/ports').BlobPort;
+    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>;

package/src/routes.js

@@ -13,6 +13,10 @@ import { createWriteRoutes } from './handlers/write.js';
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs - blobs referenced
+ *   from space records live in the account's ordinary blob store
+ * @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
  *   - the account's signing key, used to sign repo commits and space tokens
@@ -33,6 +37,13 @@ export function createSpaceRoutes(ctx) {
   if (!ctx.resolveDid || !ctx.verifier) {
     throw new Error('createSpaceRoutes requires resolveDid and a verifier');
   }
+  // Refused rather than defaulted: without the link callbacks a space record's
+  // blobs look unreferenced, and orphan cleanup deletes them.
+  if (!ctx.blobs || !ctx.linkBlob || !ctx.unlinkBlobs) {
+    throw new Error(
+      'createSpaceRoutes requires blobs, linkBlob and unlinkBlobs',
+    );
+  }
   return {
     ...createWriteRoutes(ctx),
     ...createReadRoutes(ctx),

package/src/token.d.ts

@@ -4,18 +4,21 @@ export declare const SPACE_TOKEN_TYPES: {
         kid: string;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
     credential: {
         typ: string;
         kid: string;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
     clientAttestation: {
         typ: string;
         kid: undefined;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
 };
 export declare class SpaceTokenError extends Error {
@@ -36,6 +39,12 @@ export type SpaceTokenPayload = {
     iat: number;
     exp: number;
     jti: string;
+    /**
+     * - the key the holder must prove possession of
+     */
+    cnf?: {
+        jkt: string;
+    };
 };
 export type SpaceTokenHeader = {
     alg: string;
@@ -44,7 +53,7 @@ export type SpaceTokenHeader = {
 };
 /**
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
- * @param {{iss: string, sub: string, aud?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
+ * @param {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
  * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
  * @returns {Promise<string>}
  */
@@ -52,6 +61,7 @@ export declare function createSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, o
     iss: string;
     sub: string;
     aud?: string;
+    dpopJkt?: string;
     expiresInSec?: number;
     kid?: string;
     alg?: string;

package/src/token.js

@@ -7,7 +7,11 @@
 // They share a wire shape and differ only in who signs, who they address, and
 // how long they live — so they are data, not three implementations.
 
-import { base64UrlDecode, base64UrlEncode, bytesToHex } from '@pdsjs/core/crypto';
+import {
+  base64UrlDecode,
+  base64UrlEncode,
+  bytesToHex,
+} from '@pdsjs/core/crypto';
 
 export const SPACE_TOKEN_TYPES = {
   delegation: {
@@ -15,19 +19,26 @@ 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,
   },
 };
 
@@ -53,6 +64,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
  */
 
 /**
@@ -88,7 +100,7 @@ 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 {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
  * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
  * @returns {Promise<string>}
  */
@@ -97,6 +109,9 @@ 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} */
@@ -109,6 +124,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))),
@@ -159,6 +175,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',

package/src/verifier.d.ts

@@ -1,15 +1 @@
-/**
- * @param {string} didKey - did:key:z… (the did: prefix is optional)
- * @returns {{curve: 'p256'|'secp256k1', publicKey: Uint8Array}}
- */
-export declare function parseDidKey(didKey: string): {
-    curve: 'p256' | 'secp256k1';
-    publicKey: Uint8Array;
-};
-/**
- * @param {{secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>}} [opts]
- * @returns {import('@pdsjs/core/ports').SignatureVerifierPort}
- */
-export declare function createVerifier(opts?: {
-    secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>;
-}): import('@pdsjs/core/ports').SignatureVerifierPort;
+export { createVerifier, parseDidKey } from '@pdsjs/core/verify';

package/src/verifier.js

@@ -1,74 +1,8 @@
 // @pdsjs/spaces/verifier - signature verification port.
 //
-// P-256 ships built in on crypto.subtle. secp256k1 is injected: hand-rolling
-// ECDSA verification is a different risk class from hand-rolling a hash, since
-// a subtle bug means accepting a forged credential rather than a failing test.
-// Without an injected verifier, spaces interoperate only with P-256 accounts.
+// The implementation now lives in @pdsjs/core/verify so that core features
+// (service-auth verification on account migration) and spaces (space
+// credentials) share one verifier. This module re-exports it to keep the
+// @pdsjs/spaces/verifier entry point stable for existing importers.
 
-import { base58btcDecode, P256_MULTICODEC } from '@pdsjs/core/plc';
-
-const SECP256K1_MULTICODEC = [0xe7, 0x01];
-
-/**
- * @param {string} didKey - did:key:z… (the did: prefix is optional)
- * @returns {{curve: 'p256'|'secp256k1', publicKey: Uint8Array}}
- */
-export function parseDidKey(didKey) {
-  const value = didKey.startsWith('did:key:') ? didKey.slice(8) : didKey;
-  if (!value.startsWith('z')) {
-    throw new Error(`expected a did:key multibase value, got: ${didKey}`);
-  }
-  const bytes = base58btcDecode(value.slice(1));
-  if (bytes[0] === P256_MULTICODEC[0] && bytes[1] === P256_MULTICODEC[1]) {
-    return { curve: 'p256', publicKey: bytes.slice(2) };
-  }
-  if (
-    bytes[0] === SECP256K1_MULTICODEC[0] &&
-    bytes[1] === SECP256K1_MULTICODEC[1]
-  ) {
-    return { curve: 'secp256k1', publicKey: bytes.slice(2) };
-  }
-  throw new Error(`unsupported did:key multicodec: ${didKey}`);
-}
-
-/**
- * @param {{secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>}} [opts]
- * @returns {import('@pdsjs/core/ports').SignatureVerifierPort}
- */
-export function createVerifier(opts = {}) {
-  return {
-    async verify(didKey, data, sig) {
-      const { curve, publicKey } = parseDidKey(didKey);
-      if (curve === 'p256') return verifyP256(publicKey, data, sig);
-      if (!opts.secp256k1) {
-        throw new Error(
-          'secp256k1 verification requires an injected verifier; ' +
-            'this deployment supports P-256 keys only',
-        );
-      }
-      return opts.secp256k1(publicKey, data, sig);
-    },
-  };
-}
-
-/**
- * @param {Uint8Array} publicKey - 33-byte compressed point
- * @param {Uint8Array} data
- * @param {Uint8Array} sig - 64-byte raw r||s
- * @returns {Promise<boolean>}
- */
-async function verifyP256(publicKey, data, sig) {
-  const key = await crypto.subtle.importKey(
-    'raw',
-    /** @type {BufferSource} */ (publicKey),
-    { name: 'ECDSA', namedCurve: 'P-256' },
-    false,
-    ['verify'],
-  );
-  return crypto.subtle.verify(
-    { name: 'ECDSA', hash: 'SHA-256' },
-    key,
-    /** @type {BufferSource} */ (sig),
-    /** @type {BufferSource} */ (data),
-  );
-}
+export { createVerifier, parseDidKey } from '@pdsjs/core/verify';