@pdsjs/spaces 1.0.0

package/src/handlers/read.js

@@ -0,0 +1,394 @@
+// @pdsjs/spaces/handlers/read - com.atproto.space read and sync endpoints.
+//
+// These are the repo-host role: an application syncing a space pulls each
+// member's repo from its PDS through here.
+//
+// Two ways in: the hosted account's own session, or a space credential issued
+// by the space's authority. The credential is what lets a syncer read a repo it
+// does not own — it is signed by the authority, so it verifies without
+// contacting them.
+
+import { cborDecode } from '@pdsjs/core/repo';
+import { serializeRepo } from '../car.js';
+import { RepoCommit } from '../commit.js';
+import { SpaceTokenError } from '../token.js';
+import { parseSpaceUri } from '../uri.js';
+import { verifySpaceCredential } from './auth.js';
+
+/**
+ * @param {string} error
+ * @param {string} message
+ * @param {number} [status]
+ * @returns {Response}
+ */
+function errorResponse(error, message, status = 400) {
+  return Response.json({ error, message }, { status });
+}
+
+/**
+ * @param {URL} url
+ * @returns {{space: string, repo: string|null}|Response}
+ */
+function readTarget(url) {
+  const space = url.searchParams.get('space');
+  if (!space) return errorResponse('InvalidRequest', 'space is required');
+  try {
+    parseSpaceUri(space);
+  } catch {
+    return errorResponse('InvalidSpaceUri', `Not a space uri: ${space}`);
+  }
+  return { space, repo: url.searchParams.get('repo') };
+}
+
+/**
+ * @param {URL} url
+ * @param {string} name
+ * @param {number} def
+ * @param {number} max
+ * @returns {number|Response}
+ */
+function readLimit(url, name, def, max) {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return def;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > max) {
+    return errorResponse(
+      'InvalidRequest',
+      `${name} must be an integer between 1 and ${max}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * atproto's JSON representation of a byte string.
+ * @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(/=+$/, '') };
+}
+
+/**
+ * @param {import('../commit.js').SignedCommit} commit
+ * @returns {Object}
+ */
+function toJsonCommit(commit) {
+  return {
+    ver: commit.ver,
+    hash: toJsonBytes(commit.hash),
+    ikm: toJsonBytes(commit.ikm),
+    sig: toJsonBytes(commit.sig),
+    mac: toJsonBytes(commit.mac),
+    rev: commit.rev,
+  };
+}
+
+/**
+ * Build a signed commit over the repo's current state. Undefined when the repo
+ * has never been written to.
+ *
+ * @param {Object} opts
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} opts.spaceStorage
+ * @param {string} opts.space
+ * @param {string} opts.author
+ * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @returns {Promise<import('../commit.js').SignedCommit|undefined>}
+ */
+async function buildSignedCommit({ spaceStorage, space, author, signer }) {
+  const state = await spaceStorage.getSpaceRepo(space);
+  if (!state?.setHash || !state.rev) return undefined;
+  return RepoCommit.fromState(state.setHash).sign(
+    { space, author, rev: state.rev },
+    signer,
+  );
+}
+
+/**
+ * @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 {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export function createReadRoutes(ctx) {
+  const { spaceStorage, getDid, getSigner, resolveDid, verifier } = ctx;
+
+  /**
+   * Authorize a read: the hosted account itself, or a valid space credential for
+   * the space being read.
+   *
+   * @param {Request} request
+   * @param {string} space
+   * @param {{did: string}|null} auth
+   * @returns {Promise<Response|null>} a Response to return, or null to proceed
+   */
+  async function authorizeRead(request, space, auth) {
+    const hosted = await getDid();
+    if (auth && auth.did === hosted) return null;
+
+    const header = request.headers.get('authorization') ?? '';
+    const match = header.match(/^Bearer\s+(.+)$/i);
+    if (!match) {
+      return errorResponse(
+        'AuthenticationRequired',
+        'A session or space credential is required',
+        401,
+      );
+    }
+    try {
+      await verifySpaceCredential({
+        credential: match[1],
+        space,
+        resolveDid,
+        verifier,
+      });
+      return null;
+    } catch (err) {
+      if (err instanceof SpaceTokenError) {
+        return errorResponse(err.code, err.message, 401);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * The repo a request targets. `repo` is optional on the wire; this PDS hosts
+   * exactly one account, so anything else is a miss rather than a proxy.
+   * @param {string|null} repo
+   * @returns {Promise<string|Response>}
+   */
+  async function resolveRepo(repo) {
+    const did = await getDid();
+    if (!did) return errorResponse('RepoNotFound', 'Server not initialised');
+    if (repo && repo !== did) {
+      return errorResponse('RepoNotFound', `Not hosted here: ${repo}`, 404);
+    }
+    return did;
+  }
+
+  return {
+    '/xrpc/com.atproto.space.getRecord': {
+      auth: 'optional',
+      handler: async (request, url, auth) => {
+        const target = readTarget(url);
+        if (target instanceof Response) return target;
+        const denied = await authorizeRead(request, target.space, auth);
+        if (denied) return denied;
+        const did = await resolveRepo(target.repo);
+        if (did instanceof Response) return did;
+
+        const collection = url.searchParams.get('collection');
+        const rkey = url.searchParams.get('rkey');
+        if (!collection || !rkey) {
+          return errorResponse(
+            'InvalidRequest',
+            'collection and rkey are required',
+          );
+        }
+
+        const row = await spaceStorage.getSpaceRecord(
+          target.space,
+          collection,
+          rkey,
+        );
+        if (!row) {
+          return errorResponse(
+            'RecordNotFound',
+            `Record not found: ${collection}/${rkey}`,
+            404,
+          );
+        }
+        return Response.json({
+          uri: `${target.space}/${did}/${collection}/${rkey}`,
+          cid: row.cid,
+          value: cborDecode(row.value),
+        });
+      },
+    },
+
+    '/xrpc/com.atproto.space.listRecords': {
+      auth: 'optional',
+      handler: async (request, url, auth) => {
+        const target = readTarget(url);
+        if (target instanceof Response) return target;
+        const denied = await authorizeRead(request, target.space, auth);
+        if (denied) return denied;
+        const did = await resolveRepo(target.repo);
+        if (did instanceof Response) return did;
+
+        const limit = readLimit(url, 'limit', 50, 100);
+        if (limit instanceof Response) return limit;
+
+        const collection = url.searchParams.get('collection');
+        if (!collection) {
+          return errorResponse(
+            'InvalidRequest',
+            'collection is required by this implementation',
+          );
+        }
+
+        const { records, cursor } = await spaceStorage.listSpaceRecords(
+          target.space,
+          collection,
+          url.searchParams.get('cursor'),
+          limit,
+        );
+        return Response.json({
+          ...(cursor ? { cursor } : {}),
+          records: records.map((r) => ({
+            uri: `${target.space}/${did}/${r.collection}/${r.rkey}`,
+            cid: r.cid,
+            value: cborDecode(r.value),
+          })),
+        });
+      },
+    },
+
+    '/xrpc/com.atproto.space.listRepoOps': {
+      auth: 'optional',
+      handler: async (request, url, auth) => {
+        const target = readTarget(url);
+        if (target instanceof Response) return target;
+        const denied = await authorizeRead(request, target.space, auth);
+        if (denied) return denied;
+        const did = await resolveRepo(target.repo);
+        if (did instanceof Response) return did;
+
+        const limit = readLimit(url, 'limit', 100, 1000);
+        if (limit instanceof Response) return limit;
+        const excludeValues = url.searchParams.get('excludeValues') === 'true';
+
+        const ops = await spaceStorage.listSpaceOps(
+          target.space,
+          url.searchParams.get('since'),
+          limit,
+        );
+
+        // Inline each op's record value so a syncer advances without a
+        // getRecord round-trip per write. A value is omitted for deletes, when
+        // excludeValues is set, and when a later op superseded it — the stored
+        // record is the current one, so it is only this op's value if the CIDs
+        // still agree.
+        const entries = [];
+        for (const op of ops) {
+          /** @type {Record<string, unknown>} */
+          const entry = {
+            rev: op.rev,
+            collection: op.collection,
+            rkey: op.rkey,
+            cid: op.cid,
+            prev: op.prev,
+          };
+          if (!excludeValues && op.cid) {
+            const row = await spaceStorage.getSpaceRecord(
+              target.space,
+              op.collection,
+              op.rkey,
+            );
+            if (row && row.cid === op.cid) {
+              entry.value = cborDecode(row.value);
+            }
+          }
+          entries.push(entry);
+        }
+
+        /** @type {Record<string, unknown>} */
+        const body = { ops: entries };
+        // The commit describes the head, so it is only meaningful once the
+        // response has reached it. A full page may have more behind it.
+        if (ops.length < limit) {
+          const commit = await buildSignedCommit({
+            spaceStorage,
+            space: target.space,
+            author: did,
+            signer: await getSigner(),
+          });
+          if (commit) body.commit = toJsonCommit(commit);
+        } else {
+          body.cursor = ops[ops.length - 1].rev;
+        }
+        return Response.json(body);
+      },
+    },
+
+    '/xrpc/com.atproto.space.getLatestCommit': {
+      auth: 'optional',
+      handler: async (request, url, auth) => {
+        const target = readTarget(url);
+        if (target instanceof Response) return target;
+        const denied = await authorizeRead(request, target.space, auth);
+        if (denied) return denied;
+        const did = await resolveRepo(target.repo);
+        if (did instanceof Response) return did;
+
+        const commit = await buildSignedCommit({
+          spaceStorage,
+          space: target.space,
+          author: did,
+          signer: await getSigner(),
+        });
+        return Response.json(commit ? { commit: toJsonCommit(commit) } : {});
+      },
+    },
+
+    '/xrpc/com.atproto.space.getRepo': {
+      auth: 'optional',
+      handler: async (request, url, auth) => {
+        const target = readTarget(url);
+        if (target instanceof Response) return target;
+        const denied = await authorizeRead(request, target.space, auth);
+        if (denied) return denied;
+        const did = await resolveRepo(target.repo);
+        if (did instanceof Response) return did;
+
+        const commit = await buildSignedCommit({
+          spaceStorage,
+          space: target.space,
+          author: did,
+          signer: await getSigner(),
+        });
+        if (!commit) {
+          return errorResponse(
+            'RepoNotFound',
+            `Could not find repo for space: ${target.space}`,
+            404,
+          );
+        }
+
+        const paths = await spaceStorage.listAllSpaceRecords(target.space);
+        const records = [];
+        for (const p of paths) {
+          const row = await spaceStorage.getSpaceRecord(
+            target.space,
+            p.collection,
+            p.rkey,
+          );
+          if (row) {
+            records.push({
+              collection: p.collection,
+              rkey: p.rkey,
+              cid: row.cid,
+              value: row.value,
+            });
+          }
+        }
+
+        const car = await serializeRepo(commit, records);
+        // Copy into a plain ArrayBuffer: a Uint8Array view is not a BodyInit
+        // per the DOM lib types, and `.buffer` widens to ArrayBufferLike, which
+        // includes SharedArrayBuffer. The copy keeps this honest rather than
+        // casting past the check.
+        const body = new ArrayBuffer(car.byteLength);
+        new Uint8Array(body).set(car);
+        return new Response(body, {
+          headers: { 'content-type': 'application/vnd.ipld.car' },
+        });
+      },
+    },
+  };
+}

package/src/handlers/write.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 declare function createWriteRoutes(ctx: {
+    spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    getDid: () => Promise<string | null>;
+    getSigner: () => Promise<{
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    }>;
+    resolveDid: (did: string) => Promise<any>;
+    fetch?: typeof fetch;
+}): import('@pdsjs/core/pds').Routes;