@pdsjs/spaces 2.0.1 → 2.0.3

package/src/handlers/read.js

@@ -8,12 +8,11 @@
 // does not own — it is signed by the authority, so it verifies without
 // contacting them.
 
-import { cborDecode } from '@pdsjs/core/repo';
+import { cborDecode, findBlobRefs } 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';
+import { createReadAuthorizer } from './auth.js';
 
 /**
  * @param {string} error
@@ -106,55 +105,51 @@ async function buildSignedCommit({ spaceStorage, space, author, signer }) {
   );
 }
 
+/**
+ * Every blob CID a space's records reference, paired with the rev of the commit
+ * that wrote the referencing record.
+ *
+ * Read from the records themselves rather than from a link table. A space repo
+ * on a personal server is small, and a table that can drift is the one thing a
+ * blob's reachability must not rest on.
+ *
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} spaceStorage
+ * @param {string} space
+ * @returns {Promise<Map<string, string>>} blob CID -> earliest referencing rev
+ */
+async function spaceBlobRefs(spaceStorage, space) {
+  /** @type {Map<string, string>} */
+  const refs = new Map();
+  const paths = await spaceStorage.listAllSpaceRecords(space);
+  for (const path of paths) {
+    const row = await spaceStorage.getSpaceRecord(
+      space,
+      path.collection,
+      path.rkey,
+    );
+    if (!row) continue;
+    for (const cid of findBlobRefs(cborDecode(row.value))) {
+      const seen = refs.get(cid);
+      if (seen === undefined || row.repoRev < seen) refs.set(cid, row.repoRev);
+    }
+  }
+  return refs;
+}
+
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs
  * @param {() => Promise<string|null>} ctx.getDid
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
- * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} 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;
+  const { spaceStorage, blobs, 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;
-    }
-  }
+  const authorizeRead = createReadAuthorizer({ getDid, resolveDid, verifier });
 
   /**
    * The repo a request targets. `repo` is optional on the wire; this PDS hosts
@@ -171,6 +166,27 @@ export function createReadRoutes(ctx) {
     return did;
   }
 
+  /** @type {import('@pdsjs/core/pds').Route} */
+  const latestCommitRoute = {
+    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) } : {});
+    },
+  };
+
   return {
     '/xrpc/com.atproto.space.getRecord': {
       auth: 'optional',
@@ -221,29 +237,26 @@ export function createReadRoutes(ctx) {
         const did = await resolveRepo(target.repo);
         if (did instanceof Response) return did;
 
-        const limit = readLimit(url, 'limit', 50, 100);
+        const limit = readLimit(url, 'limit', 50, 1000);
         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,
+          {
+            collection: url.searchParams.get('collection'),
+            cursor: url.searchParams.get('cursor'),
+            limit,
+            reverse: url.searchParams.get('reverse') === 'true',
+            excludeValues: url.searchParams.get('excludeValues') === 'true',
+          },
         );
         return Response.json({
           ...(cursor ? { cursor } : {}),
           records: records.map((r) => ({
-            uri: `${target.space}/${did}/${r.collection}/${r.rkey}`,
+            collection: r.collection,
+            rkey: r.rkey,
             cid: r.cid,
-            value: cborDecode(r.value),
+            ...(r.value === undefined ? {} : { value: cborDecode(r.value) }),
           })),
         });
       },
@@ -316,7 +329,17 @@ export function createReadRoutes(ctx) {
       },
     },
 
-    '/xrpc/com.atproto.space.getLatestCommit': {
+    '/xrpc/com.atproto.space.getLatestCommit': latestCommitRoute,
+
+    // The same handler under the name this method shipped as before the draft
+    // renamed it. Both are in use, and a client that knows only one reads the
+    // whole feature as missing.
+    '/xrpc/com.atproto.space.getRepoState': latestCommitRoute,
+
+    // Blobs are uploaded through com.atproto.repo.uploadBlob and referenced
+    // from a space record, so a client writing blob-bearing records needs a
+    // blob permission alongside its space permission.
+    '/xrpc/com.atproto.space.listBlobs': {
       auth: 'optional',
       handler: async (request, url, auth) => {
         const target = readTarget(url);
@@ -326,13 +349,65 @@ export function createReadRoutes(ctx) {
         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(),
+        const limit = readLimit(url, 'limit', 500, 1000);
+        if (limit instanceof Response) return limit;
+        const since = url.searchParams.get('since');
+        const cursor = url.searchParams.get('cursor');
+
+        const refs = await spaceBlobRefs(spaceStorage, target.space);
+        const cids = [...refs]
+          .filter(([, rev]) => (since ? rev > since : true))
+          .map(([cid]) => cid)
+          .filter((cid) => (cursor ? cid > cursor : true))
+          .sort();
+        const page = cids.slice(0, limit);
+
+        return Response.json({
+          cids: page,
+          ...(page.length < limit ? {} : { cursor: page[page.length - 1] }),
+        });
+      },
+    },
+
+    // Scoped to the space: a credential admits its holder to that space, not to
+    // the account's whole blob store. The reference serves any blob the account
+    // holds once the space read passes.
+    '/xrpc/com.atproto.space.getBlob': {
+      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 cid = url.searchParams.get('cid');
+        if (!cid) return errorResponse('InvalidRequest', 'cid is required');
+
+        const refs = await spaceBlobRefs(spaceStorage, target.space);
+        if (!refs.has(cid)) {
+          return errorResponse(
+            'BlobNotFound',
+            `No record in ${target.space} references ${cid}`,
+            404,
+          );
+        }
+
+        const blob = await blobs.get(did, cid);
+        if (!blob) {
+          return errorResponse('BlobNotFound', 'Blob not found', 404);
+        }
+        return new Response(/** @type {BodyInit} */ (blob.data), {
+          headers: {
+            'Content-Type': blob.mimeType,
+            'X-Content-Type-Options': 'nosniff',
+            // Force download and block execution so a hostile blob cannot run
+            // in the PDS origin.
+            'Content-Disposition': `attachment; filename="${cid}"`,
+            'Content-Security-Policy': "default-src 'none'; sandbox",
+          },
         });
-        return Response.json(commit ? { commit: toJsonCommit(commit) } : {});
       },
     },
 
@@ -360,9 +435,19 @@ export function createReadRoutes(ctx) {
           );
         }
 
+        const excludeValues = url.searchParams.get('excludeValues') === 'true';
         const paths = await spaceStorage.listAllSpaceRecords(target.space);
+        /** @type {import('../car.js').SerializedRecord[]} */
         const records = [];
         for (const p of paths) {
+          if (excludeValues) {
+            records.push({
+              collection: p.collection,
+              rkey: p.rkey,
+              cid: p.cid,
+            });
+            continue;
+          }
           const row = await spaceStorage.getSpaceRecord(
             target.space,
             p.collection,
@@ -378,7 +463,7 @@ export function createReadRoutes(ctx) {
           }
         }
 
-        const car = await serializeRepo(commit, records);
+        const car = await serializeRepo(commit, records, { excludeValues });
         // 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

package/src/handlers/write.d.ts

@@ -1,18 +1,31 @@
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @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
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
- * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid
+ * @param {{collections: string[], check: (write: {space: string|null, collection: string, rkey: string, prevValue: unknown|null, nextValue: unknown|null}) => Promise<void>}} [ctx.recordGuard]
  * @param {typeof fetch} [ctx.fetch]
  * @returns {import('@pdsjs/core/pds').Routes}
  */
 export declare function createWriteRoutes(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    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>;
-    }>;
-    resolveDid: (did: string) => Promise<any>;
+    getSigner: () => Promise<import('../token.js').SpaceSigner>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
+    recordGuard?: {
+        collections: string[];
+        check: (write: {
+            space: string | null;
+            collection: string;
+            rkey: string;
+            prevValue: unknown | null;
+            nextValue: unknown | null;
+        }) => Promise<void>;
+    };
     fetch?: typeof fetch;
 }): import('@pdsjs/core/pds').Routes;

package/src/handlers/write.js

@@ -7,10 +7,16 @@
 // 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 {
+  cborDecode,
+  createTid,
+  findBlobRefs,
+  recordTimeOf,
+} from '@pdsjs/core/repo';
 import { ScopePermissions } from '@pdsjs/core/scope';
 import { spaceHostEndpoint } from '../authority.js';
 import { LtHash } from '../lthash.js';
+import { forwardToSyncers } from '../notify.js';
 import { createServiceAuth } from '../service-auth.js';
 import { parseSpaceUri } from '../uri.js';
 import { applyWrites, SpaceWriteError } from '../writer.js';
@@ -142,17 +148,110 @@ function recordUri(space, did, collection, rkey) {
   return `${space}/${did}/${collection}/${rkey}`;
 }
 
+const WRITE_ACTIONS = ['create', 'update', 'delete'];
+
+/**
+ * Which of the three operations a write in an applyWrites batch is.
+ *
+ * The proposal made these a closed union discriminated by `$type` after clients
+ * had shipped against an `action` string. Both say the same thing, so both are
+ * read; anything else is a write this server cannot place.
+ *
+ * @param {any} write
+ * @returns {'create'|'update'|'delete'|null}
+ */
+function writeAction(write) {
+  const fromType = String(write?.$type ?? '').match(
+    /^com\.atproto\.space\.applyWrites#(create|update|delete)$/,
+  );
+  if (fromType) return /** @type {any} */ (fromType[1]);
+  if (WRITE_ACTIONS.includes(write?.action)) return write.action;
+  return null;
+}
+
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @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
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
- * @param {(did: string) => Promise<any>} ctx.resolveDid
+ * @param {() => Promise<import('../token.js').SpaceSigner>} ctx.getSigner
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid
+ * @param {{collections: string[], check: (write: {space: string|null, collection: string, rkey: string, prevValue: unknown|null, nextValue: unknown|null}) => Promise<void>}} [ctx.recordGuard]
  * @param {typeof fetch} [ctx.fetch]
  * @returns {import('@pdsjs/core/pds').Routes}
  */
 export function createWriteRoutes(ctx) {
-  const { spaceStorage, getDid, getSigner, resolveDid } = ctx;
+  const {
+    spaceStorage,
+    linkBlob,
+    unlinkBlobs,
+    getDid,
+    getSigner,
+    resolveDid,
+    recordGuard,
+  } = ctx;
+
+  /**
+   * Consult the write guard for one write in a collection it covers. Null to
+   * proceed, the refusal Response otherwise. Read-then-check races the write
+   * queue; the single account that writes here makes that a non-event.
+   * @param {string} space
+   * @param {import('../writer.js').SpaceWriteInput} write
+   * @returns {Promise<Response|null>}
+   */
+  async function guardWrite(space, write) {
+    if (!recordGuard || !recordGuard.collections.includes(write.collection)) {
+      return null;
+    }
+    const prev = await spaceStorage.getSpaceRecord(
+      space,
+      write.collection,
+      write.rkey,
+    );
+    try {
+      await recordGuard.check({
+        space,
+        collection: write.collection,
+        rkey: write.rkey,
+        prevValue: prev ? cborDecode(prev.value) : null,
+        nextValue: write.action === 'delete' ? null : (write.record ?? null),
+      });
+      return null;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code =
+        err instanceof Error && 'code' in err
+          ? String(/** @type {{code: unknown}} */ (err).code)
+          : 'InvalidRequest';
+      return errorResponse(code, message);
+    }
+  }
+
+  /**
+   * Record which blobs a space write leaves referenced.
+   *
+   * The links go in the account's one blob link table, beside those of public
+   * records. Orphan reaping asks that table whether anything still points at a
+   * blob, so a space record protects its blobs the same way a public record
+   * does, with no second table for the reaper to be taught about.
+   *
+   * @param {string} space
+   * @param {string} did
+   * @param {import('../writer.js').SpaceWriteInput[]} writes
+   * @returns {Promise<void>}
+   */
+  async function indexBlobs(space, did, writes) {
+    for (const write of writes) {
+      const uri = recordUri(space, did, write.collection, write.rkey);
+      // An update replaces the record's references rather than adding to them.
+      await unlinkBlobs(uri);
+      if (write.action === 'delete') continue;
+      for (const cid of findBlobRefs(write.record)) {
+        await linkBlob(cid, uri, recordTimeOf(write.record));
+      }
+    }
+  }
 
   /**
    * Tell the space authority this repo advanced, so it can maintain the writer
@@ -170,13 +269,21 @@ export function createWriteRoutes(ctx) {
       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.
+      // Writing into our own space: this server is both the repo host and the
+      // authority, so it does what the authority would have done on receiving
+      // the notification. Both halves of that, not just the first — a syncer
+      // registered for this space is owed the notice however the write reached
+      // it, and a Durable Object cannot post to itself to be told.
       if (spaceDid === did) {
         const hash = await new LtHash(commit.setHash).digest();
         await spaceStorage.putSpaceWriter(space, did, commit.rev, hash);
+        await forwardToSyncers(ctx, {
+          authorityDid: did,
+          space,
+          repo: did,
+          rev: commit.rev,
+          hash,
+        });
         return;
       }
       const didDoc = await resolveDid(spaceDid);
@@ -259,11 +366,19 @@ export function createWriteRoutes(ctx) {
     });
     if (scopeError) return scopeError;
 
+    const refused = await guardWrite(body.space, write);
+    if (refused) return refused;
+
     try {
       const commit = await applyWrites(spaceStorage, {
         space: body.space,
         writes: [write],
       });
+      // After the commit: the write is what makes the references real, and a
+      // link to a record that failed to write would keep a blob alive forever.
+      await indexBlobs(body.space, did, [
+        { ...write, rkey: commit.results[0].rkey },
+      ]);
       await fireNotifyWrite(body.space, commit);
       return Response.json(toBody(body, commit.results[0], did));
     } catch (err) {
@@ -311,11 +426,28 @@ export function createWriteRoutes(ctx) {
             if (body.record === undefined) {
               throw new SpaceWriteError('record is required', 'InvalidRequest');
             }
+            if (
+              body.swapRecord !== undefined &&
+              body.swapRecord !== null &&
+              typeof body.swapRecord !== 'string'
+            ) {
+              throw new SpaceWriteError(
+                'swapRecord must be a CID string or null',
+                'InvalidRequest',
+              );
+            }
             return {
               action: 'put',
               collection: body.collection,
               rkey: body.rkey,
               record: body.record,
+              // A pds.js extension the draft proposal does not have: null
+              // requires that the record does not exist, a CID requires that
+              // exact version, absent skips the check. A server without it
+              // ignores the field, so a client falls back to last-write-wins.
+              ...(body.swapRecord !== undefined
+                ? { swapCid: body.swapRecord }
+                : {}),
             };
           },
           (body, result, did) => ({
@@ -366,7 +498,6 @@ export function createWriteRoutes(ctx) {
         /** @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(
@@ -374,27 +505,24 @@ export function createWriteRoutes(ctx) {
               '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') {
+          const action = writeAction(w);
+          if (!action) {
+            return errorResponse(
+              'InvalidRequest',
+              `Unsupported write type: ${w?.$type ?? w?.action ?? '(none)'}`,
+            );
+          }
+          if (action === 'delete') {
+            writes.push({ action, collection, rkey: w.rkey });
+          } else {
             writes.push({
-              action: 'update',
+              action,
               collection,
-              rkey: w.rkey,
+              // A create may leave the server to mint the key. An empty string
+              // is how the earlier clients say so.
+              rkey: action === 'create' ? w.rkey || createTid() : 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}`,
-            );
           }
         }
 
@@ -405,12 +533,21 @@ export function createWriteRoutes(ctx) {
           });
           if (scopeError) return scopeError;
         }
+        for (const w of writes) {
+          const refused = await guardWrite(body.space, w);
+          if (refused) return refused;
+        }
 
         try {
           const commit = await applyWrites(spaceStorage, {
             space: body.space,
             writes,
           });
+          await indexBlobs(
+            body.space,
+            did,
+            writes.map((w, i) => ({ ...w, rkey: commit.results[i].rkey })),
+          );
           await fireNotifyWrite(body.space, commit);
           return Response.json({
             results: commit.results.map((r) =>

package/src/memory-storage.d.ts

@@ -1,3 +1,17 @@
+/**
+ * The blob store and blob link table createSpaceRoutes wants, in memory. A real
+ * deployment passes the account's own store and link table; here they are two
+ * Maps that answer the same way.
+ *
+ * @returns {{blobs: import('@pdsjs/core/ports').BlobPort, linkBlob: (blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>, unlinkBlobs: (recordUri: string) => Promise<void>, links: Map<string, Set<string>>, put: (cid: string, data: Uint8Array, mimeType?: string) => void}}
+ */
+export declare function createMemoryBlobContext(): {
+    blobs: import('@pdsjs/core/ports').BlobPort;
+    linkBlob: (blobCid: string, recordUri: string, recordTime: number | null) => Promise<void>;
+    unlinkBlobs: (recordUri: string) => Promise<void>;
+    links: Map<string, Set<string>>;
+    put: (cid: string, data: Uint8Array, mimeType?: string) => void;
+};
 /**
  * @returns {import('@pdsjs/core/ports').SpaceStoragePort}
  */