@pdsjs/spaces 1.0.0

package/src/handlers/write.js

@@ -0,0 +1,462 @@
+// @pdsjs/spaces/handlers/write - com.atproto.space write endpoints.
+//
+// createRecord, putRecord, deleteRecord and applyWrites are thin shells over
+// applyWrites() in ../writer.js: they validate the request, translate it into
+// write descriptors, and shape the response. All the repo logic lives there.
+//
+// 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 } from '@pdsjs/core/repo';
+import { ScopePermissions } from '@pdsjs/core/scope';
+import { spaceHostEndpoint } from '../authority.js';
+import { LtHash } from '../lthash.js';
+import { createServiceAuth } from '../service-auth.js';
+import { parseSpaceUri } from '../uri.js';
+import { applyWrites, SpaceWriteError } from '../writer.js';
+
+const MAX_JSON_BODY = 512 * 1024;
+
+/**
+ * @param {string} error
+ * @param {string} message
+ * @param {number} [status]
+ * @returns {Response}
+ */
+function errorResponse(error, message, status = 400) {
+  return Response.json({ error, message }, { status });
+}
+
+/**
+ * Parse a JSON body, rejecting oversized or malformed input.
+ * @param {Request} request
+ * @returns {Promise<{ok: true, body: any}|{ok: false, response: Response}>}
+ */
+async function readJson(request) {
+  const text = await request.text();
+  if (text.length > MAX_JSON_BODY) {
+    return {
+      ok: false,
+      response: errorResponse('InvalidRequest', 'Request body too large', 413),
+    };
+  }
+  try {
+    return { ok: true, body: JSON.parse(text) };
+  } catch {
+    return {
+      ok: false,
+      response: errorResponse('InvalidRequest', 'Invalid JSON body'),
+    };
+  }
+}
+
+/**
+ * Space URIs arrive typed only as `at-uri`, so a malformed one is a request
+ * error rather than a 500.
+ * @param {string} space
+ * @returns {Response|null}
+ */
+function validateSpaceUri(space) {
+  if (typeof space !== 'string') {
+    return errorResponse('InvalidRequest', 'space is required');
+  }
+  try {
+    parseSpaceUri(space);
+    return null;
+  } catch {
+    return errorResponse('InvalidSpaceUri', `Not a space uri: ${space}`);
+  }
+}
+
+/**
+ * Assert the token's `space:` scope covers this operation.
+ *
+ * A grant that names no `collection` should fall back to the space type's
+ * declared collections. Resolving a space-type declaration means fetching its
+ * lexicon, which this implementation does not do yet — so such a grant
+ * currently authorizes no write targets. That fails closed, and a grant that
+ * names its collections explicitly works as specified.
+ *
+ * @param {{did: string, scope?: string}|null} auth
+ * @param {string} space
+ * @param {{action: string, collection?: string}} op
+ * @returns {Response|null}
+ */
+function checkSpaceScope(auth, space, op) {
+  const { spaceDid, spaceType, skey } = parseSpaceUri(space);
+  const permissions = new ScopePermissions(auth?.scope);
+  const allowed = permissions.allowsSpace({
+    spaceType,
+    authority: spaceDid,
+    skey,
+    action: op.action,
+    collection: op.collection,
+    userDid: auth?.did,
+  });
+  if (!allowed) {
+    return errorResponse(
+      'InvalidToken',
+      `Scope does not permit ${op.action} in ${space}`,
+      403,
+    );
+  }
+  return null;
+}
+
+/**
+ * A writer may only write its own repo.
+ * @param {string} repo
+ * @param {string} did
+ * @returns {Response|null}
+ */
+function validateRepo(repo, did) {
+  if (repo !== did) {
+    return errorResponse(
+      'Forbidden',
+      'repo must match authenticated user',
+      403,
+    );
+  }
+  return null;
+}
+
+/**
+ * @param {unknown} err
+ * @returns {Response}
+ */
+function writeErrorResponse(err) {
+  if (err instanceof SpaceWriteError) {
+    return errorResponse(err.code, err.message);
+  }
+  throw err;
+}
+
+/**
+ * @param {string} space
+ * @param {string} did
+ * @param {string} collection
+ * @param {string} rkey
+ * @returns {string}
+ */
+function recordUri(space, did, collection, rkey) {
+  return `${space}/${did}/${collection}/${rkey}`;
+}
+
+/**
+ * @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 {typeof fetch} [ctx.fetch]
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export function createWriteRoutes(ctx) {
+  const { spaceStorage, getDid, getSigner, resolveDid } = ctx;
+
+  /**
+   * Tell the space authority this repo advanced, so it can maintain the writer
+   * set that listRepos enumerates and fan out to syncers.
+   *
+   * Best-effort by design: sync correctness rests on comparing set hashes, so a
+   * dropped notification is recovered by a later write or a periodic sweep.
+   *
+   * @param {string} space
+   * @param {{rev: string, setHash: Uint8Array}} commit
+   * @returns {Promise<void>}
+   */
+  async function fireNotifyWrite(space, commit) {
+    try {
+      const { spaceDid } = parseSpaceUri(space);
+      const did = await getDid();
+      if (!did) return;
+      // Writing into our own space: record the writer directly instead of
+      // notifying ourselves over HTTP. Skipping entirely would leave the
+      // authority out of its own writer set, and every syncer walking
+      // listRepos would silently miss this repo.
+      if (spaceDid === did) {
+        const hash = await new LtHash(commit.setHash).digest();
+        await spaceStorage.putSpaceWriter(space, did, commit.rev, hash);
+        return;
+      }
+      const didDoc = await resolveDid(spaceDid);
+      if (!didDoc) return;
+      const endpoint = spaceHostEndpoint(didDoc, spaceDid);
+      const token = await createServiceAuth({
+        iss: did,
+        aud: spaceDid,
+        lxm: 'com.atproto.space.notifyWrite',
+        signer: await getSigner(),
+      });
+      const hash = await new LtHash(commit.setHash).digest();
+      let binary = '';
+      for (const b of hash) binary += String.fromCharCode(b);
+      await (ctx.fetch ?? fetch)(
+        `${endpoint}/xrpc/com.atproto.space.notifyWrite`,
+        {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${token}`,
+          },
+          body: JSON.stringify({
+            space,
+            repo: did,
+            rev: commit.rev,
+            hash: { $bytes: btoa(binary).replace(/=+$/, '') },
+          }),
+        },
+      );
+    } catch {
+      // Best effort.
+    }
+  }
+
+  /**
+   * Shared shell for the three single-write endpoints.
+   * @param {Request} request
+   * @param {{did: string, scope?: string}|null} auth
+   * @param {(body: any) => {action: 'create'|'put'|'delete', collection: string, rkey: string, record?: any}} toWrite
+   * @param {(body: any, result: import('../writer.js').SpaceWriteResult, did: string) => any} toBody
+   * @returns {Promise<Response>}
+   */
+  async function singleWrite(request, auth, toWrite, toBody) {
+    const parsed = await readJson(request);
+    if (!parsed.ok) return parsed.response;
+    const body = parsed.body;
+    const did = /** @type {{did: string}} */ (auth).did;
+
+    const uriError = validateSpaceUri(body.space);
+    if (uriError) return uriError;
+    const repoError = validateRepo(body.repo, did);
+    if (repoError) return repoError;
+    if (typeof body.collection !== 'string') {
+      return errorResponse('InvalidRequest', 'collection is required');
+    }
+
+    let write;
+    try {
+      write = toWrite(body);
+    } catch (err) {
+      return writeErrorResponse(err);
+    }
+
+    // A put may create or update, so resolve which before checking scope, the
+    // way the reference implementation does.
+    /** @type {string} */
+    let action = write.action;
+    if (action === 'put') {
+      const existing = await spaceStorage.getSpaceRecordCid(
+        body.space,
+        write.collection,
+        write.rkey,
+      );
+      action = existing ? 'update' : 'create';
+    }
+    const scopeError = checkSpaceScope(auth, body.space, {
+      action,
+      collection: write.collection,
+    });
+    if (scopeError) return scopeError;
+
+    try {
+      const commit = await applyWrites(spaceStorage, {
+        space: body.space,
+        writes: [write],
+      });
+      await fireNotifyWrite(body.space, commit);
+      return Response.json(toBody(body, commit.results[0], did));
+    } catch (err) {
+      return writeErrorResponse(err);
+    }
+  }
+
+  return {
+    '/xrpc/com.atproto.space.createRecord': {
+      method: 'POST',
+      auth: 'required',
+      handler: (request, _url, auth) =>
+        singleWrite(
+          request,
+          auth,
+          (body) => {
+            if (body.record === undefined) {
+              throw new SpaceWriteError('record is required', 'InvalidRequest');
+            }
+            return {
+              action: 'create',
+              collection: body.collection,
+              rkey: body.rkey ?? createTid(),
+              record: body.record,
+            };
+          },
+          (body, result, did) => ({
+            uri: recordUri(body.space, did, result.collection, result.rkey),
+            cid: result.cid,
+          }),
+        ),
+    },
+
+    '/xrpc/com.atproto.space.putRecord': {
+      method: 'POST',
+      auth: 'required',
+      handler: (request, _url, auth) =>
+        singleWrite(
+          request,
+          auth,
+          (body) => {
+            if (typeof body.rkey !== 'string') {
+              throw new SpaceWriteError('rkey is required', 'InvalidRequest');
+            }
+            if (body.record === undefined) {
+              throw new SpaceWriteError('record is required', 'InvalidRequest');
+            }
+            return {
+              action: 'put',
+              collection: body.collection,
+              rkey: body.rkey,
+              record: body.record,
+            };
+          },
+          (body, result, did) => ({
+            uri: recordUri(body.space, did, result.collection, result.rkey),
+            cid: result.cid,
+          }),
+        ),
+    },
+
+    '/xrpc/com.atproto.space.deleteRecord': {
+      method: 'POST',
+      auth: 'required',
+      handler: (request, _url, auth) =>
+        singleWrite(
+          request,
+          auth,
+          (body) => {
+            if (typeof body.rkey !== 'string') {
+              throw new SpaceWriteError('rkey is required', 'InvalidRequest');
+            }
+            return {
+              action: 'delete',
+              collection: body.collection,
+              rkey: body.rkey,
+            };
+          },
+          () => ({}),
+        ),
+    },
+
+    '/xrpc/com.atproto.space.applyWrites': {
+      method: 'POST',
+      auth: 'required',
+      handler: async (request, _url, auth) => {
+        const parsed = await readJson(request);
+        if (!parsed.ok) return parsed.response;
+        const body = parsed.body;
+        const did = /** @type {{did: string}} */ (auth).did;
+
+        const uriError = validateSpaceUri(body.space);
+        if (uriError) return uriError;
+        const repoError = validateRepo(body.repo, did);
+        if (repoError) return repoError;
+        if (!Array.isArray(body.writes)) {
+          return errorResponse('InvalidRequest', 'writes must be an array');
+        }
+
+        /** @type {import('../writer.js').SpaceWriteInput[]} */
+        const writes = [];
+        for (const w of body.writes) {
+          const type = w?.$type;
+          const collection = w?.collection;
+          if (typeof collection !== 'string') {
+            return errorResponse(
+              'InvalidRequest',
+              'each write needs a collection',
+            );
+          }
+          if (type === 'com.atproto.space.applyWrites#create') {
+            writes.push({
+              action: 'create',
+              collection,
+              rkey: w.rkey ?? createTid(),
+              record: w.value,
+            });
+          } else if (type === 'com.atproto.space.applyWrites#update') {
+            writes.push({
+              action: 'update',
+              collection,
+              rkey: w.rkey,
+              record: w.value,
+            });
+          } else if (type === 'com.atproto.space.applyWrites#delete') {
+            writes.push({ action: 'delete', collection, rkey: w.rkey });
+          } else {
+            return errorResponse(
+              'InvalidRequest',
+              `Unsupported write type: ${type}`,
+            );
+          }
+        }
+
+        for (const w of writes) {
+          const scopeError = checkSpaceScope(auth, body.space, {
+            action: w.action,
+            collection: w.collection,
+          });
+          if (scopeError) return scopeError;
+        }
+
+        try {
+          const commit = await applyWrites(spaceStorage, {
+            space: body.space,
+            writes,
+          });
+          await fireNotifyWrite(body.space, commit);
+          return Response.json({
+            results: commit.results.map((r) =>
+              r.action === 'delete'
+                ? { $type: 'com.atproto.space.applyWrites#deleteResult' }
+                : {
+                    $type: `com.atproto.space.applyWrites#${r.action}Result`,
+                    uri: recordUri(body.space, did, r.collection, r.rkey),
+                    cid: r.cid,
+                  },
+            ),
+          });
+        } catch (err) {
+          return writeErrorResponse(err);
+        }
+      },
+    },
+
+    '/xrpc/com.atproto.space.listSpaces': {
+      auth: 'required',
+      handler: async (_request, url) => {
+        const params = url.searchParams;
+        const limitParam = params.get('limit');
+        let limit = limitParam === null ? 50 : Number(limitParam);
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+          if (limitParam !== null) {
+            return errorResponse(
+              'InvalidRequest',
+              'limit must be an integer between 1 and 100',
+            );
+          }
+          limit = 50;
+        }
+
+        const { spaces, cursor } = await spaceStorage.listSpaces({
+          type: params.get('type'),
+          did: params.get('did'),
+          cursor: params.get('cursor'),
+          limit,
+        });
+
+        return Response.json({
+          ...(cursor ? { cursor } : {}),
+          spaces: spaces.map((s) => ({ uri: s.uri, isOwner: s.isOwner })),
+        });
+      },
+    },
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,15 @@
+export { ATPROTO_KEY_ID, ATPROTO_PDS_ID, atprotoSigningKey, didKeyResolver, SPACE_HOST_ID, SPACE_KEY_ID, SpaceAuthorityError, spaceHostAudience, spaceHostEndpoint, spaceSigningKey, } from './authority.js';
+export { blake3 } from './blake3.js';
+export { byCanonicalKey, serializeRepo } from './car.js';
+export { RepoCommit, verifyCommit } from './commit.js';
+export { verifySpaceCredential } from './handlers/auth.js';
+export { LTHASH_STATE_BYTES, LtHash } from './lthash.js';
+export { bytesEqual, COMMIT_VERSION, computeMac, encodeCommitCtx, hkdfExpandSha256, hmacSha256, } from './mac.js';
+export { createMemorySpaceStorage } from './memory-storage.js';
+export { formatRecordPath, formatSetHashElement, parseRecordPath, } from './path.js';
+export { createSpaceRoutes } from './routes.js';
+export { makeSpaceRow } from './space-row.js';
+export { createSpaceToken, parseSpaceToken, SPACE_TOKEN_TYPES, SpaceTokenError, verifySpaceToken, } from './token.js';
+export { formatSpaceUri, isSpaceUri, parseSpaceUri, SPACE_MARKER, } from './uri.js';
+export { createVerifier, parseDidKey } from './verifier.js';
+export { applyWrites, MAX_WRITES_PER_COMMIT, SpaceRecordAlreadyExistsError, SpaceRecordNotFoundError, SpaceWriteError, } from './writer.js';

package/src/index.js

@@ -0,0 +1,56 @@
+// @pdsjs/spaces - AT Protocol permissioned data (proposal 0016)
+
+export {
+  ATPROTO_KEY_ID,
+  ATPROTO_PDS_ID,
+  atprotoSigningKey,
+  didKeyResolver,
+  SPACE_HOST_ID,
+  SPACE_KEY_ID,
+  SpaceAuthorityError,
+  spaceHostAudience,
+  spaceHostEndpoint,
+  spaceSigningKey,
+} from './authority.js';
+export { blake3 } from './blake3.js';
+export { byCanonicalKey, serializeRepo } from './car.js';
+export { RepoCommit, verifyCommit } from './commit.js';
+export { verifySpaceCredential } from './handlers/auth.js';
+export { LTHASH_STATE_BYTES, LtHash } from './lthash.js';
+export {
+  bytesEqual,
+  COMMIT_VERSION,
+  computeMac,
+  encodeCommitCtx,
+  hkdfExpandSha256,
+  hmacSha256,
+} from './mac.js';
+export { createMemorySpaceStorage } from './memory-storage.js';
+export {
+  formatRecordPath,
+  formatSetHashElement,
+  parseRecordPath,
+} from './path.js';
+export { createSpaceRoutes } from './routes.js';
+export { makeSpaceRow } from './space-row.js';
+export {
+  createSpaceToken,
+  parseSpaceToken,
+  SPACE_TOKEN_TYPES,
+  SpaceTokenError,
+  verifySpaceToken,
+} from './token.js';
+export {
+  formatSpaceUri,
+  isSpaceUri,
+  parseSpaceUri,
+  SPACE_MARKER,
+} from './uri.js';
+export { createVerifier, parseDidKey } from './verifier.js';
+export {
+  applyWrites,
+  MAX_WRITES_PER_COMMIT,
+  SpaceRecordAlreadyExistsError,
+  SpaceRecordNotFoundError,
+  SpaceWriteError,
+} from './writer.js';

package/src/lthash.d.ts

@@ -0,0 +1,24 @@
+export declare const LTHASH_STATE_BYTES: number;
+/**
+ * A homomorphic set hash. Each element expands to 1024 little-endian u16 lanes
+ * summed into the state mod 2^16. Addition and subtraction commute, so the state
+ * depends only on the current set, not on insertion order.
+ */
+export declare class LtHash {
+    bytes: Uint8Array<ArrayBuffer>;
+    lanes: Uint16Array<ArrayBuffer>;
+    /** @param {Uint8Array|null} [state] */
+    constructor(state?: Uint8Array | null);
+    /** @param {string} element @returns {this} */
+    add(element: string): this;
+    /** @param {string} element @returns {this} */
+    remove(element: string): this;
+    /** @returns {Uint8Array} the full state, for persistence */
+    state(): Uint8Array;
+    /** @returns {Promise<Uint8Array>} */
+    digest(): Promise<Uint8Array>;
+    /** @returns {boolean} */
+    isEmpty(): boolean;
+    /** @param {LtHash} other @returns {boolean} */
+    equals(other: LtHash): boolean;
+}

package/src/lthash.js

@@ -0,0 +1,86 @@
+// @pdsjs/spaces/lthash - homomorphic set hash for permissioned repo commits.
+
+import { blake3 } from './blake3.js';
+
+const LANES = 1024;
+// Cannot change without reworking the Uint16Array impl. `new Uint16Array(buffer)`
+// reads/writes in host byte order, which is little-endian on every platform
+// pds.js targets (Node, Deno, browsers, Cloudflare Workers) and matches the
+// little-endian lanes described above and by the spec; digests would only
+// diverge from the reference on a big-endian host.
+const LANE_BYTES = 2;
+export const LTHASH_STATE_BYTES = LANES * LANE_BYTES; // 2048
+
+/**
+ * A homomorphic set hash. Each element expands to 1024 little-endian u16 lanes
+ * summed into the state mod 2^16. Addition and subtraction commute, so the state
+ * depends only on the current set, not on insertion order.
+ */
+export class LtHash {
+  /** @param {Uint8Array|null} [state] */
+  constructor(state) {
+    if (state && state.length !== LTHASH_STATE_BYTES) {
+      throw new Error(
+        `LtHash state must be ${LTHASH_STATE_BYTES} bytes, got ${state.length}`,
+      );
+    }
+    const buffer = new ArrayBuffer(LTHASH_STATE_BYTES);
+    this.bytes = new Uint8Array(buffer);
+    this.lanes = new Uint16Array(buffer);
+    if (state) this.bytes.set(state);
+  }
+
+  /** @param {string} element @returns {this} */
+  add(element) {
+    const lanes = expand(element);
+    for (let i = 0; i < LANES; i++) this.lanes[i] += lanes[i];
+    return this;
+  }
+
+  /** @param {string} element @returns {this} */
+  remove(element) {
+    const lanes = expand(element);
+    for (let i = 0; i < LANES; i++) this.lanes[i] -= lanes[i];
+    return this;
+  }
+
+  /** @returns {Uint8Array} the full state, for persistence */
+  state() {
+    return new Uint8Array(this.bytes);
+  }
+
+  /** @returns {Promise<Uint8Array>} */
+  async digest() {
+    const hash = await crypto.subtle.digest('SHA-256', this.bytes);
+    return new Uint8Array(hash);
+  }
+
+  /** @returns {boolean} */
+  isEmpty() {
+    for (let i = 0; i < LANES; i++) if (this.lanes[i] !== 0) return false;
+    return true;
+  }
+
+  /** @param {LtHash} other @returns {boolean} */
+  equals(other) {
+    for (let i = 0; i < LANES; i++) {
+      if (this.lanes[i] !== other.lanes[i]) return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Expand an element to 1024 little-endian u16 lanes with BLAKE3 in XOF mode.
+ * @param {string} element
+ * @returns {Uint16Array}
+ */
+function expand(element) {
+  const expanded = blake3(
+    new TextEncoder().encode(element),
+    LTHASH_STATE_BYTES,
+  );
+  const buffer = new ArrayBuffer(LTHASH_STATE_BYTES);
+  new Uint8Array(buffer).set(expanded);
+  return new Uint16Array(buffer);
+}

package/src/mac.d.ts

@@ -0,0 +1,50 @@
+export declare const COMMIT_VERSION = 1;
+/**
+ * ctx = "atproto-space-v1"
+ *    || uint16be(len(space))  || space
+ *    || uint16be(len(author)) || author
+ *    || uint16be(len(rev))    || rev
+ *    || uint16be(len(ikm))    || ikm
+ *
+ * Length prefixes are big-endian per the TLS variable-length vector convention,
+ * deliberately the opposite byte order from the set hash's lanes.
+ *
+ * @param {{space: string, author: string, rev: string}} ctx
+ * @param {Uint8Array} ikm
+ * @returns {Uint8Array}
+ */
+export declare function encodeCommitCtx(ctx: {
+    space: string;
+    author: string;
+    rev: string;
+}, ikm: Uint8Array): Uint8Array;
+/**
+ * @param {Uint8Array} key
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * HKDF-Expand (RFC 5869 §2.3) with SHA-256 and L = 32, matching the reference's
+ * `expand(sha256, ikm, info, 32)`. `ikm` is used directly as the PRK — there is
+ * no extract step, which is why crypto.subtle's HKDF cannot be used here. With
+ * L equal to the hash length this is exactly one block.
+ *
+ * @param {Uint8Array} ikm
+ * @param {Uint8Array} info
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function hkdfExpandSha256(ikm: Uint8Array, info: Uint8Array): Promise<Uint8Array>;
+/**
+ * @param {Uint8Array} ikm
+ * @param {Uint8Array} ctxBytes
+ * @param {Uint8Array} hash
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function computeMac(ikm: Uint8Array, ctxBytes: Uint8Array, hash: Uint8Array): Promise<Uint8Array>;
+/**
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {boolean}
+ */
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;