@pdsjs/spaces 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chad Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pdsjs/spaces",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./blake3": "./src/blake3.js",
+    "./lthash": "./src/lthash.js",
+    "./path": "./src/path.js",
+    "./uri": "./src/uri.js",
+    "./mac": "./src/mac.js",
+    "./verifier": "./src/verifier.js",
+    "./commit": "./src/commit.js",
+    "./memory-storage": "./src/memory-storage.js",
+    "./routes": "./src/routes.js",
+    "./space-row": "./src/space-row.js",
+    "./writer": "./src/writer.js",
+    "./car": "./src/car.js",
+    "./token": "./src/token.js",
+    "./authority": "./src/authority.js",
+    "./service-auth": "./src/service-auth.js"
+  },
+  "dependencies": {
+    "@pdsjs/core": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://tangled.org/chadtmiller.com/pds.js",
+    "directory": "packages/spaces"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/authority.d.ts

@@ -0,0 +1,47 @@
+export declare const SPACE_KEY_ID = "#atproto_space";
+export declare const SPACE_HOST_ID = "#atproto_space_host";
+export declare const ATPROTO_KEY_ID = "#atproto";
+export declare const ATPROTO_PDS_ID = "#atproto_pds";
+export declare class SpaceAuthorityError extends Error {
+    code: string;
+    /** @param {string} message @param {string} [code] */
+    constructor(message: string, code?: string);
+}
+/**
+ * The key that verifies a space authority's credentials.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string} did:key
+ */
+export declare function spaceSigningKey(didDoc: any, did: string): string;
+/**
+ * The key that verifies an ordinary account's signatures — delegation tokens and
+ * repo commits. Always the account's `#atproto` key.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string} did:key
+ */
+export declare function atprotoSigningKey(didDoc: any, did: string): string;
+/**
+ * Where a space's authority serves its host endpoints.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string}
+ */
+export declare function spaceHostEndpoint(didDoc: any, did: string): string;
+/**
+ * The `aud` a delegation token must carry for a given authority.
+ * @param {string} spaceDid
+ * @returns {string}
+ */
+export declare function spaceHostAudience(spaceDid: string): string;
+/**
+ * Build the `getSigningKey` callback verifySpaceToken expects.
+ *
+ * @param {(did: string) => Promise<any>} resolveDid
+ * @returns {(iss: string, kid?: string) => Promise<string>}
+ */
+export declare function didKeyResolver(resolveDid: (did: string) => Promise<any>): (iss: string, kid?: string) => Promise<string>;

package/src/authority.js

@@ -0,0 +1,148 @@
+// @pdsjs/spaces/authority - resolving a space authority from its DID document.
+//
+// Proposal 0016 gives a space authority two optional DID document entries, each
+// with a fallback to the account's ordinary atproto entry:
+//
+//   verification method #atproto_space      -> falls back to #atproto
+//   service            #atproto_space_host  -> falls back to #atproto_pds
+//
+// The service fallback is why a space-unaware PDS still receives space requests:
+// clients resolve the space host to its ordinary PDS endpoint.
+
+export const SPACE_KEY_ID = '#atproto_space';
+export const SPACE_HOST_ID = '#atproto_space_host';
+export const ATPROTO_KEY_ID = '#atproto';
+export const ATPROTO_PDS_ID = '#atproto_pds';
+
+export class SpaceAuthorityError extends Error {
+  /** @param {string} message @param {string} [code] */
+  constructor(message, code = 'SpaceAuthorityNotFound') {
+    super(message);
+    this.name = 'SpaceAuthorityError';
+    this.code = code;
+  }
+}
+
+/**
+ * @param {any} didDoc
+ * @param {string} did
+ * @param {string} id - fragment, e.g. '#atproto'
+ * @returns {string|null} did:key, or null when absent
+ */
+function verificationMethod(didDoc, did, id) {
+  const methods = didDoc?.verificationMethod ?? [];
+  for (const method of methods) {
+    // A DID document may write the id either fully-qualified or as a bare
+    // fragment; accept both.
+    if (method?.id === id || method?.id === `${did}${id}`) {
+      return method.publicKeyMultibase
+        ? `did:key:${method.publicKeyMultibase}`
+        : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {any} didDoc
+ * @param {string} did
+ * @param {string} id
+ * @returns {string|null}
+ */
+function serviceEndpoint(didDoc, did, id) {
+  const services = didDoc?.service ?? [];
+  for (const service of services) {
+    if (service?.id === id || service?.id === `${did}${id}`) {
+      return typeof service.serviceEndpoint === 'string'
+        ? service.serviceEndpoint
+        : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The key that verifies a space authority's credentials.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string} did:key
+ */
+export function spaceSigningKey(didDoc, did) {
+  const key =
+    verificationMethod(didDoc, did, SPACE_KEY_ID) ??
+    verificationMethod(didDoc, did, ATPROTO_KEY_ID);
+  if (!key) {
+    throw new SpaceAuthorityError(
+      `No space signing key for ${did}`,
+      'SpaceKeyNotFound',
+    );
+  }
+  return key;
+}
+
+/**
+ * The key that verifies an ordinary account's signatures — delegation tokens and
+ * repo commits. Always the account's `#atproto` key.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string} did:key
+ */
+export function atprotoSigningKey(didDoc, did) {
+  const key = verificationMethod(didDoc, did, ATPROTO_KEY_ID);
+  if (!key) {
+    throw new SpaceAuthorityError(
+      `No atproto signing key for ${did}`,
+      'SigningKeyNotFound',
+    );
+  }
+  return key;
+}
+
+/**
+ * Where a space's authority serves its host endpoints.
+ *
+ * @param {any} didDoc
+ * @param {string} did
+ * @returns {string}
+ */
+export function spaceHostEndpoint(didDoc, did) {
+  const endpoint =
+    serviceEndpoint(didDoc, did, SPACE_HOST_ID) ??
+    serviceEndpoint(didDoc, did, ATPROTO_PDS_ID);
+  if (!endpoint) {
+    throw new SpaceAuthorityError(
+      `No space host for ${did}`,
+      'SpaceHostNotFound',
+    );
+  }
+  return endpoint;
+}
+
+/**
+ * The `aud` a delegation token must carry for a given authority.
+ * @param {string} spaceDid
+ * @returns {string}
+ */
+export function spaceHostAudience(spaceDid) {
+  return `${spaceDid}${SPACE_HOST_ID}`;
+}
+
+/**
+ * Build the `getSigningKey` callback verifySpaceToken expects.
+ *
+ * @param {(did: string) => Promise<any>} resolveDid
+ * @returns {(iss: string, kid?: string) => Promise<string>}
+ */
+export function didKeyResolver(resolveDid) {
+  return async (iss, kid) => {
+    const didDoc = await resolveDid(iss);
+    if (!didDoc) {
+      throw new SpaceAuthorityError(`Could not resolve ${iss}`, 'DidNotFound');
+    }
+    return kid === SPACE_KEY_ID
+      ? spaceSigningKey(didDoc, iss)
+      : atprotoSigningKey(didDoc, iss);
+  };
+}

package/src/blake3.d.ts

@@ -0,0 +1,14 @@
+export type Output = {
+    cv: Uint32Array;
+    block: Uint32Array;
+    counter: number;
+    blockLen: number;
+    flags: number;
+};
+/**
+ * Unkeyed BLAKE3 with extendable output.
+ * @param {Uint8Array} input
+ * @param {number} [outLen] - output length in bytes, default 32
+ * @returns {Uint8Array}
+ */
+export declare function blake3(input: Uint8Array, outLen?: number): Uint8Array;

package/src/blake3.js

@@ -0,0 +1,272 @@
+// @pdsjs/spaces/blake3 - vendored BLAKE3 with extendable output.
+//
+// This is the only hand-written cryptographic primitive in pds.js. WebCrypto
+// has no BLAKE3, and LtHash (proposal 0016) is defined in terms of it. Verified
+// against the official BLAKE3 test vectors in test/fixtures/blake3-vectors.json;
+// do not modify without re-running packages/spaces/test/blake3.test.js.
+//
+// Transliterated from the BLAKE3 reference implementation
+// (https://github.com/BLAKE3-team/BLAKE3, reference_impl/reference_impl.rs),
+// per the spec at https://github.com/BLAKE3-team/BLAKE3-specs. Only the
+// unkeyed, extendable-output mode is implemented — no keyed hash, no
+// derive-key mode.
+
+const IV = new Uint32Array([
+  0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+  0x1f83d9ab, 0x5be0cd19,
+]);
+
+const MSG_PERMUTATION = [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8];
+
+const CHUNK_START = 1 << 0;
+const CHUNK_END = 1 << 1;
+const PARENT = 1 << 2;
+const ROOT = 1 << 3;
+
+const BLOCK_LEN = 64;
+const CHUNK_LEN = 1024;
+
+/**
+ * A deferred compression: the final block of a chunk or parent, not yet
+ * compressed, so the ROOT flag can still be applied to the last one.
+ * @typedef {Object} Output
+ * @property {Uint32Array} cv
+ * @property {Uint32Array} block
+ * @property {number} counter
+ * @property {number} blockLen
+ * @property {number} flags
+ */
+
+/**
+ * @param {number} x
+ * @param {number} n
+ * @returns {number}
+ */
+const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
+
+/**
+ * The quarter-round. Rotations are 16, 12, 8, 7.
+ * @param {Uint32Array} s - 16-word compression state, mutated in place
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @param {number} mx
+ * @param {number} my
+ * @returns {void}
+ */
+function g(s, a, b, c, d, mx, my) {
+  s[a] = (s[a] + s[b] + mx) >>> 0;
+  s[d] = rotr(s[d] ^ s[a], 16);
+  s[c] = (s[c] + s[d]) >>> 0;
+  s[b] = rotr(s[b] ^ s[c], 12);
+  s[a] = (s[a] + s[b] + my) >>> 0;
+  s[d] = rotr(s[d] ^ s[a], 8);
+  s[c] = (s[c] + s[d]) >>> 0;
+  s[b] = rotr(s[b] ^ s[c], 7);
+}
+
+/**
+ * Four column mixes then four diagonal mixes.
+ * @param {Uint32Array} s - 16-word compression state, mutated in place
+ * @param {Uint32Array} m - 16 message words
+ * @returns {void}
+ */
+function round(s, m) {
+  g(s, 0, 4, 8, 12, m[0], m[1]);
+  g(s, 1, 5, 9, 13, m[2], m[3]);
+  g(s, 2, 6, 10, 14, m[4], m[5]);
+  g(s, 3, 7, 11, 15, m[6], m[7]);
+  g(s, 0, 5, 10, 15, m[8], m[9]);
+  g(s, 1, 6, 11, 12, m[10], m[11]);
+  g(s, 2, 7, 8, 13, m[12], m[13]);
+  g(s, 3, 4, 9, 14, m[14], m[15]);
+}
+
+/**
+ * @param {Uint32Array} m - 16 message words
+ * @returns {Uint32Array} the message words reordered by MSG_PERMUTATION
+ */
+function permute(m) {
+  const out = new Uint32Array(16);
+  for (let i = 0; i < 16; i++) out[i] = m[MSG_PERMUTATION[i]];
+  return out;
+}
+
+/**
+ * @param {Uint32Array} cv - 8-word chaining value
+ * @param {Uint32Array} block - 16 message words
+ * @param {number} counter
+ * @param {number} blockLen
+ * @param {number} flags
+ * @returns {Uint32Array} all 16 state words — the first 8 are the chaining
+ * value, all 16 are needed for extended output.
+ */
+function compress(cv, block, counter, blockLen, flags) {
+  const s = new Uint32Array(16);
+  s.set(cv, 0);
+  s[8] = IV[0];
+  s[9] = IV[1];
+  s[10] = IV[2];
+  s[11] = IV[3];
+  s[12] = counter >>> 0;
+  s[13] = Math.floor(counter / 2 ** 32) >>> 0;
+  s[14] = blockLen;
+  s[15] = flags;
+
+  let m = block;
+  for (let i = 0; i < 7; i++) {
+    round(s, m);
+    if (i < 6) m = permute(m);
+  }
+  for (let i = 0; i < 8; i++) {
+    s[i] = (s[i] ^ s[i + 8]) >>> 0;
+    s[i + 8] = (s[i + 8] ^ cv[i]) >>> 0;
+  }
+  return s;
+}
+
+/**
+ * Read 16 little-endian uint32s from a 64-byte block.
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @returns {Uint32Array}
+ */
+function wordsFromBlock(bytes, offset) {
+  const m = new Uint32Array(16);
+  for (let i = 0; i < 16; i++) {
+    const o = offset + i * 4;
+    m[i] =
+      (bytes[o] |
+        (bytes[o + 1] << 8) |
+        (bytes[o + 2] << 16) |
+        (bytes[o + 3] << 24)) >>>
+      0;
+  }
+  return m;
+}
+
+/**
+ * @param {Output} o
+ * @returns {Uint32Array} the 8-word chaining value
+ */
+function outputChainingValue(o) {
+  return compress(o.cv, o.block, o.counter, o.blockLen, o.flags).slice(0, 8);
+}
+
+/**
+ * @param {Output} o
+ * @param {number} outLen - output length in bytes
+ * @returns {Uint8Array}
+ */
+function rootOutputBytes(o, outLen) {
+  const out = new Uint8Array(outLen);
+  let i = 0;
+  let counter = 0;
+  while (i < outLen) {
+    const words = compress(o.cv, o.block, counter, o.blockLen, o.flags | ROOT);
+    for (let w = 0; w < 16 && i < outLen; w++) {
+      for (let b = 0; b < 4 && i < outLen; b++) {
+        out[i++] = (words[w] >>> (8 * b)) & 0xff;
+      }
+    }
+    counter++;
+  }
+  return out;
+}
+
+/**
+ * @param {Uint8Array} input
+ * @param {number} start - byte offset of the chunk within input
+ * @param {number} len - chunk length in bytes
+ * @param {number} chunkCounter
+ * @returns {Output}
+ */
+function chunkOutput(input, start, len, chunkCounter) {
+  let cv = IV.slice(0, 8);
+  let blockFlags = CHUNK_START;
+  let pos = 0;
+  while (len - pos > BLOCK_LEN) {
+    const m = wordsFromBlock(input, start + pos);
+    cv = compress(cv, m, chunkCounter, BLOCK_LEN, blockFlags).slice(0, 8);
+    pos += BLOCK_LEN;
+    blockFlags = 0;
+  }
+  const blockLen = len - pos;
+  const padded = new Uint8Array(BLOCK_LEN);
+  padded.set(input.subarray(start + pos, start + len));
+  return {
+    cv,
+    block: wordsFromBlock(padded, 0),
+    counter: chunkCounter,
+    blockLen,
+    flags: blockFlags | CHUNK_END,
+  };
+}
+
+/**
+ * @param {Uint32Array} leftCv - 8-word chaining value
+ * @param {Uint32Array} rightCv - 8-word chaining value
+ * @returns {Output}
+ */
+function parentOutput(leftCv, rightCv) {
+  const block = new Uint32Array(16);
+  block.set(leftCv, 0);
+  block.set(rightCv, 8);
+  return {
+    cv: IV.slice(0, 8),
+    block,
+    counter: 0,
+    blockLen: BLOCK_LEN,
+    flags: PARENT,
+  };
+}
+
+/**
+ * Unkeyed BLAKE3 with extendable output.
+ * @param {Uint8Array} input
+ * @param {number} [outLen] - output length in bytes, default 32
+ * @returns {Uint8Array}
+ */
+export function blake3(input, outLen = 32) {
+  const chunks = Math.max(1, Math.ceil(input.length / CHUNK_LEN));
+  /** @type {Uint32Array[]} */
+  const stack = [];
+  /** @type {Output|undefined} */
+  let output;
+
+  for (let i = 0; i < chunks; i++) {
+    const start = i * CHUNK_LEN;
+    const len = Math.min(CHUNK_LEN, Math.max(0, input.length - start));
+    const chunk = chunkOutput(input, start, len, i);
+
+    // The last chunk stays an Output so the ROOT flag can reach it.
+    if (i === chunks - 1) {
+      output = chunk;
+      break;
+    }
+
+    // Merge while the completed-chunk count has a trailing zero bit.
+    let cv = outputChainingValue(chunk);
+    let n = i + 1;
+    while ((n & 1) === 0) {
+      // Guaranteed non-empty: n's trailing zero count never exceeds the
+      // number of merges already pushed onto the stack.
+      cv = outputChainingValue(
+        parentOutput(/** @type {Uint32Array} */ (stack.pop()), cv),
+      );
+      n >>= 1;
+    }
+    stack.push(cv);
+  }
+
+  // At least one chunk always runs, so `output` is set by the time either
+  // loop below reads it.
+  while (stack.length > 0) {
+    output = parentOutput(
+      /** @type {Uint32Array} */ (stack.pop()),
+      outputChainingValue(/** @type {Output} */ (output)),
+    );
+  }
+  return rootOutputBytes(/** @type {Output} */ (output), outLen);
+}

package/src/car.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical DAG-CBOR map key order: shortest key first, then bytewise.
+ *
+ * This is NOT plain lexicographic order — `a/b` sorts before `aa/b`. A consumer
+ * walks the index in the order the CBOR encoder emitted its keys and expects the
+ * record blocks to follow, so both have to use this comparison.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export declare function byCanonicalKey(a: string, b: string): number;
+export type SerializedRecord = {
+    collection: string;
+    rkey: string;
+    cid: string;
+    /**
+     * - DAG-CBOR encoded record
+     */
+    value: Uint8Array;
+};
+/**
+ * @typedef {Object} SerializedRecord
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {string} cid
+ * @property {Uint8Array} value - DAG-CBOR encoded record
+ */
+/**
+ * Serialize a repo as a CAR: two roots in order — the signed commit, then the
+ * index — followed by one block per index entry, in the index's order. Blobs are
+ * excluded.
+ *
+ * Records are collected up front because the index has to precede the blocks it
+ * describes.
+ *
+ * @param {import('./commit.js').SignedCommit} commit
+ * @param {Iterable<SerializedRecord>} records
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function serializeRepo(commit: import('./commit.js').SignedCommit, records: Iterable<SerializedRecord>): Promise<Uint8Array>;

package/src/car.js

@@ -0,0 +1,98 @@
+// @pdsjs/spaces/car - permissioned repo CAR serialization.
+
+import {
+  buildCarFile,
+  CID,
+  cborEncodeDagCbor,
+  cidToBytes,
+  cidToString,
+  createCid,
+} from '@pdsjs/core/repo';
+import { formatRecordPath } from './path.js';
+
+/**
+ * Canonical DAG-CBOR map key order: shortest key first, then bytewise.
+ *
+ * This is NOT plain lexicographic order — `a/b` sorts before `aa/b`. A consumer
+ * walks the index in the order the CBOR encoder emitted its keys and expects the
+ * record blocks to follow, so both have to use this comparison.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function byCanonicalKey(a, b) {
+  if (a.length !== b.length) return a.length - b.length;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * @typedef {Object} SerializedRecord
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {string} cid
+ * @property {Uint8Array} value - DAG-CBOR encoded record
+ */
+
+/**
+ * Serialize a repo as a CAR: two roots in order — the signed commit, then the
+ * index — followed by one block per index entry, in the index's order. Blobs are
+ * excluded.
+ *
+ * Records are collected up front because the index has to precede the blocks it
+ * describes.
+ *
+ * @param {import('./commit.js').SignedCommit} commit
+ * @param {Iterable<SerializedRecord>} records
+ * @returns {Promise<Uint8Array>}
+ */
+export async function serializeRepo(commit, records) {
+  /** @type {Map<string, SerializedRecord>} */
+  const byPath = new Map();
+  for (const record of records) {
+    byPath.set(formatRecordPath(record.collection, record.rkey), record);
+  }
+  const paths = [...byPath.keys()].sort(byCanonicalKey);
+
+  /** @type {Record<string, any>} */
+  const index = {};
+  for (const path of paths) {
+    // A CID instance is what the DAG-CBOR encoder emits as a tag-42 link.
+    index[path] = new CID(
+      cidToBytes(/** @type {SerializedRecord} */ (byPath.get(path)).cid),
+    );
+  }
+
+  const commitBytes = cborEncodeDagCbor(toCommitBlock(commit));
+  const indexBytes = cborEncodeDagCbor(index);
+  const commitRoot = cidToString(await createCid(commitBytes));
+  const indexRoot = cidToString(await createCid(indexBytes));
+
+  const blocks = [
+    { cid: commitRoot, data: commitBytes },
+    { cid: indexRoot, data: indexBytes },
+    ...paths.map((path) => {
+      const record = /** @type {SerializedRecord} */ (byPath.get(path));
+      return { cid: record.cid, data: record.value };
+    }),
+  ];
+
+  return buildCarFile([commitRoot, indexRoot], blocks);
+}
+
+/**
+ * The commit block is plain DAG-CBOR with byte fields, not the JSON `$bytes`
+ * shape used on the wire elsewhere.
+ * @param {import('./commit.js').SignedCommit} commit
+ * @returns {Object}
+ */
+function toCommitBlock(commit) {
+  return {
+    ver: commit.ver,
+    hash: commit.hash,
+    ikm: commit.ikm,
+    sig: commit.sig,
+    mac: commit.mac,
+    rev: commit.rev,
+  };
+}