@pdsjs/spaces 2.0.1 → 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

@@ -19,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,
   },
 };
 
@@ -57,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
  */
 
 /**
@@ -92,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>}
  */
@@ -101,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} */
@@ -113,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))),
@@ -163,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',