@pdsjs/spaces 1.0.0

package/src/mac.js

@@ -0,0 +1,107 @@
+// @pdsjs/spaces/mac - commit context encoding and deniable-signature MAC.
+
+export const COMMIT_VERSION = 1;
+
+const DOMAIN_PREFIX = new TextEncoder().encode('atproto-space-v1');
+
+/**
+ * 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 function encodeCommitCtx(ctx, ikm) {
+  const encoder = new TextEncoder();
+  const fields = [
+    encoder.encode(ctx.space),
+    encoder.encode(ctx.author),
+    encoder.encode(ctx.rev),
+    ikm,
+  ];
+
+  let size = DOMAIN_PREFIX.length;
+  for (const field of fields) {
+    if (field.length > 0xffff) {
+      throw new Error('commit ctx field exceeds uint16 length prefix');
+    }
+    size += 2 + field.length;
+  }
+
+  const out = new Uint8Array(size);
+  out.set(DOMAIN_PREFIX);
+  let offset = DOMAIN_PREFIX.length;
+  for (const field of fields) {
+    out[offset++] = (field.length >>> 8) & 0xff;
+    out[offset++] = field.length & 0xff;
+    out.set(field, offset);
+    offset += field.length;
+  }
+  return out;
+}
+
+/**
+ * @param {Uint8Array} key
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function hmacSha256(key, data) {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    /** @type {BufferSource} */ (key),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const sig = await crypto.subtle.sign(
+    'HMAC',
+    cryptoKey,
+    /** @type {BufferSource} */ (data),
+  );
+  return new Uint8Array(sig);
+}
+
+/**
+ * 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 function hkdfExpandSha256(ikm, info) {
+  const block = new Uint8Array(info.length + 1);
+  block.set(info);
+  block[info.length] = 0x01;
+  return hmacSha256(ikm, block);
+}
+
+/**
+ * @param {Uint8Array} ikm
+ * @param {Uint8Array} ctxBytes
+ * @param {Uint8Array} hash
+ * @returns {Promise<Uint8Array>}
+ */
+export async function computeMac(ikm, ctxBytes, hash) {
+  return hmacSha256(await hkdfExpandSha256(ikm, ctxBytes), hash);
+}
+
+/**
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {boolean}
+ */
+export function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}

package/src/memory-storage.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns {import('@pdsjs/core/ports').SpaceStoragePort}
+ */
+export declare function createMemorySpaceStorage(): import('@pdsjs/core/ports').SpaceStoragePort;

package/src/memory-storage.js

@@ -0,0 +1,244 @@
+// @pdsjs/spaces/memory-storage - in-memory SpaceStoragePort.
+//
+// Backs unit tests and gives handler tests a store with no database. Keyed
+// exactly like the SQL adapters so the shared conformance suite exercises the
+// same behaviour everywhere.
+
+/**
+ * Keyset pagination over a sorted key list.
+ * @template T
+ * @param {string[]} sortedKeys
+ * @param {string|null} cursor - exclusive lower bound
+ * @param {number} limit
+ * @param {(key: string) => T} map
+ * @returns {{items: T[], cursor: string|null}}
+ */
+function page(sortedKeys, cursor, limit, map) {
+  const start = cursor ? sortedKeys.findIndex((k) => k > cursor) : 0;
+  if (start === -1) return { items: [], cursor: null };
+  const slice = sortedKeys.slice(start, start + limit);
+  return {
+    items: slice.map(map),
+    // A full page always yields a cursor, even if it happened to be the last
+    // one. The next call then returns empty with a null cursor. This matches
+    // `WHERE key > ? LIMIT n` in the SQL adapters — do not "optimise" it to
+    // return null on the final full page, or the two diverge.
+    cursor: slice.length === limit ? slice[slice.length - 1] : null,
+  };
+}
+
+/**
+ * @returns {import('@pdsjs/core/ports').SpaceStoragePort}
+ */
+export function createMemorySpaceStorage() {
+  /** @type {Map<string, import('@pdsjs/core/ports').SpaceRow>} */
+  const spaces = new Map();
+  /** @type {Map<string, Set<string>>} space uri -> dids */
+  const members = new Map();
+  /** @type {Map<string, Map<string, import('@pdsjs/core/ports').SpaceRecordRow>>} */
+  const records = new Map();
+  /** @type {Map<string, {setHash: Uint8Array|null, rev: string|null}>} */
+  const repos = new Map();
+  /** @type {Map<string, import('@pdsjs/core/ports').SpaceOpRow[]>} */
+  const oplog = new Map();
+  /** @type {Map<string, Map<string, import('@pdsjs/core/ports').SpaceWriterRow>>} */
+  const writers = new Map();
+  /** @type {Map<string, Map<string, import('@pdsjs/core/ports').SpaceRecipientRow>>} */
+  const recipients = new Map();
+
+  return {
+    async getSpace(uri) {
+      const row = spaces.get(uri);
+      return row ? { ...row, appAllowed: [...row.appAllowed] } : null;
+    },
+
+    async putSpace(space) {
+      spaces.set(space.uri, { ...space, appAllowed: [...space.appAllowed] });
+    },
+
+    async deleteSpace(uri, deletedAt) {
+      const row = spaces.get(uri);
+      if (row) spaces.set(uri, { ...row, deletedAt });
+    },
+
+    async listSpaces({ type = null, did = null, cursor = null, limit = 50 }) {
+      let keys = [...spaces.keys()].sort();
+      if (type || did) {
+        keys = keys.filter((uri) => {
+          // Filter on the stored components, not by re-parsing the URI: the
+          // domain supplies them, and every adapter must agree on the result.
+          const row = /** @type {import('@pdsjs/core/ports').SpaceRow} */ (
+            spaces.get(uri)
+          );
+          if (type && row.spaceType !== type) return false;
+          if (did && row.spaceDid !== did) return false;
+          return true;
+        });
+      }
+      const { items, cursor: next } = page(keys, cursor, limit, (uri) => {
+        // uri comes from spaces.keys(), so this lookup is always present.
+        const row = /** @type {import('@pdsjs/core/ports').SpaceRow} */ (
+          spaces.get(uri)
+        );
+        return { ...row, appAllowed: [...row.appAllowed] };
+      });
+      return { spaces: items, cursor: next };
+    },
+
+    async addMember(space, did) {
+      let set = members.get(space);
+      if (!set) {
+        set = new Set();
+        members.set(space, set);
+      }
+      set.add(did);
+    },
+
+    async removeMember(space, did) {
+      members.get(space)?.delete(did);
+    },
+
+    async listMembers(space, cursor, limit) {
+      const keys = [...(members.get(space) ?? [])].sort();
+      const { items, cursor: next } = page(keys, cursor, limit, (d) => d);
+      return { dids: items, cursor: next };
+    },
+
+    async isMember(space, did) {
+      return members.get(space)?.has(did) ?? false;
+    },
+
+    async getSpaceRecord(space, collection, rkey) {
+      const row = records.get(space)?.get(`${collection}/${rkey}`);
+      return row ? { ...row, value: new Uint8Array(row.value) } : null;
+    },
+
+    async getSpaceRecordCid(space, collection, rkey) {
+      return records.get(space)?.get(`${collection}/${rkey}`)?.cid ?? null;
+    },
+
+    async listSpaceRecords(space, collection, cursor, limit) {
+      const inSpace = records.get(space) ?? new Map();
+      const keys = [...inSpace.values()]
+        .filter((r) => r.collection === collection)
+        .map((r) => r.rkey)
+        .sort();
+      const { items, cursor: next } = page(keys, cursor, limit, (rkey) => {
+        const row = inSpace.get(`${collection}/${rkey}`);
+        return { ...row, value: new Uint8Array(row.value) };
+      });
+      return { records: items, cursor: next };
+    },
+
+    async listAllSpaceRecords(space) {
+      const inSpace = records.get(space) ?? new Map();
+      return [...inSpace.keys()].sort().map((key) => {
+        const row = inSpace.get(key);
+        return { collection: row.collection, rkey: row.rkey, cid: row.cid };
+      });
+    },
+
+    async commitSpaceWrite(space, { writes, setHash, rev, indexedAt }) {
+      // Validate everything before mutating: this method is atomic.
+      for (const w of writes) {
+        if (w.action !== 'delete' && !(w.value instanceof Uint8Array)) {
+          throw new Error(
+            `space write value must be Uint8Array: ${w.collection}/${w.rkey}`,
+          );
+        }
+      }
+
+      let inSpace = records.get(space);
+      if (!inSpace) {
+        inSpace = new Map();
+        records.set(space, inSpace);
+      }
+      const ops = oplog.get(space) ?? [];
+
+      writes.forEach((w, idx) => {
+        const key = `${w.collection}/${w.rkey}`;
+        if (w.action === 'delete') {
+          inSpace.delete(key);
+        } else {
+          inSpace.set(key, {
+            collection: w.collection,
+            rkey: w.rkey,
+            cid: /** @type {string} */ (w.cid),
+            value: new Uint8Array(/** @type {Uint8Array} */ (w.value)),
+            repoRev: rev,
+            indexedAt,
+          });
+        }
+        ops.push({
+          rev,
+          idx,
+          action: w.action,
+          collection: w.collection,
+          rkey: w.rkey,
+          cid: w.cid,
+          prev: w.prev,
+        });
+      });
+
+      oplog.set(space, ops);
+      repos.set(space, { setHash: new Uint8Array(setHash), rev });
+    },
+
+    async getSpaceRepo(space) {
+      const repo = repos.get(space);
+      if (!repo) return null;
+      return {
+        setHash: repo.setHash ? new Uint8Array(repo.setHash) : null,
+        rev: repo.rev,
+      };
+    },
+
+    async listSpaceOps(space, since, limit) {
+      return (oplog.get(space) ?? [])
+        .filter((op) => (since === null ? true : op.rev > since))
+        .sort((a, b) =>
+          a.rev === b.rev ? a.idx - b.idx : a.rev < b.rev ? -1 : 1,
+        )
+        .slice(0, limit)
+        .map((op) => ({ ...op }));
+    },
+
+    async putSpaceWriter(space, did, rev, hash) {
+      let inSpace = writers.get(space);
+      if (!inSpace) {
+        inSpace = new Map();
+        writers.set(space, inSpace);
+      }
+      inSpace.set(did, { did, rev, hash: new Uint8Array(hash) });
+    },
+
+    async listSpaceWriters(space, cursor, limit) {
+      const inSpace = writers.get(space) ?? new Map();
+      const keys = [...inSpace.keys()].sort();
+      const { items, cursor: next } = page(keys, cursor, limit, (did) => {
+        const row = inSpace.get(did);
+        return { ...row, hash: new Uint8Array(row.hash) };
+      });
+      return { writers: items, cursor: next };
+    },
+
+    async putCredentialRecipient(
+      space,
+      serviceDid,
+      serviceEndpoint,
+      lastIssuedAt,
+    ) {
+      let inSpace = recipients.get(space);
+      if (!inSpace) {
+        inSpace = new Map();
+        recipients.set(space, inSpace);
+      }
+      inSpace.set(serviceDid, { serviceDid, serviceEndpoint, lastIssuedAt });
+    },
+
+    async listCredentialRecipients(space) {
+      const inSpace = recipients.get(space) ?? new Map();
+      return [...inSpace.keys()].sort().map((k) => ({ ...inSpace.get(k) }));
+    },
+  };
+}

package/src/path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @param {string} collection
+ * @param {string} rkey
+ * @returns {string}
+ */
+export declare function formatRecordPath(collection: string, rkey: string): string;
+/**
+ * @param {string} path
+ * @returns {{collection: string, rkey: string}}
+ */
+export declare function parseRecordPath(path: string): {
+    collection: string;
+    rkey: string;
+};
+/**
+ * The element a record contributes to a repo's set hash.
+ * @param {string} collection
+ * @param {string} rkey
+ * @param {string} cid
+ * @returns {string}
+ */
+export declare function formatSetHashElement(collection: string, rkey: string, cid: string): string;

package/src/path.js

@@ -0,0 +1,33 @@
+// @pdsjs/spaces/path - record path and set hash element formatting.
+
+/**
+ * @param {string} collection
+ * @param {string} rkey
+ * @returns {string}
+ */
+export function formatRecordPath(collection, rkey) {
+  return `${collection}/${rkey}`;
+}
+
+/**
+ * @param {string} path
+ * @returns {{collection: string, rkey: string}}
+ */
+export function parseRecordPath(path) {
+  const parts = path.split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`invalid record path: ${path}`);
+  }
+  return { collection: parts[0], rkey: parts[1] };
+}
+
+/**
+ * The element a record contributes to a repo's set hash.
+ * @param {string} collection
+ * @param {string} rkey
+ * @param {string} cid
+ * @returns {string}
+ */
+export function formatSetHashElement(collection, rkey, cid) {
+  return `${collection}/${rkey}/${cid}`;
+}

package/src/routes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @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
+ * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ *   injected so this package stays dependency-free
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
+ *   calls, so tests can observe them without a network
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export declare function createSpaceRoutes(ctx: {
+    spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    getDid: () => Promise<string | null>;
+    getSigner: () => Promise<{
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    }>;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+    fetch?: typeof fetch;
+}): import('@pdsjs/core/pds').Routes;

package/src/routes.js

@@ -0,0 +1,42 @@
+// @pdsjs/spaces/routes - the space route table.
+//
+// @pdsjs/core never imports this package. Instead a platform package builds the
+// table and passes it to the PDS as `spaceRoutes`, which merges it into its own
+// route map. With the feature off, the routes are simply absent and requests
+// fall through to the normal 404 — see spec section 3.
+
+import { createAuthRoutes } from './handlers/auth.js';
+import { createManageRoutes } from './handlers/manage.js';
+import { createReadRoutes } from './handlers/read.js';
+import { createWriteRoutes } from './handlers/write.js';
+
+/**
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @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
+ * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ *   injected so this package stays dependency-free
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
+ *   calls, so tests can observe them without a network
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export function createSpaceRoutes(ctx) {
+  if (!ctx?.spaceStorage) {
+    throw new Error('createSpaceRoutes requires a spaceStorage port');
+  }
+  if (!ctx.getDid || !ctx.getSigner) {
+    throw new Error('createSpaceRoutes requires getDid and getSigner');
+  }
+  if (!ctx.resolveDid || !ctx.verifier) {
+    throw new Error('createSpaceRoutes requires resolveDid and a verifier');
+  }
+  return {
+    ...createWriteRoutes(ctx),
+    ...createReadRoutes(ctx),
+    ...createAuthRoutes(ctx),
+    ...createManageRoutes(ctx),
+  };
+}

package/src/service-auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Verify a service-auth JWT presented to us.
+ *
+ * @param {Object} opts
+ * @param {string} opts.jwt
+ * @param {string} opts.aud - our own DID; the token must be addressed to us
+ * @param {string} opts.lxm - the method being called
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @returns {Promise<{iss: string}>}
+ */
+export declare function verifyServiceAuth({ jwt, aud, lxm, resolveDid, verifier, }: {
+    jwt: string;
+    aud: string;
+    lxm: string;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+}): Promise<{
+    iss: string;
+}>;
+/**
+ * Mint a service-auth JWT for an outbound call.
+ *
+ * Core has its own createServiceJwt, but it takes a CryptoKey; @pdsjs/spaces only
+ * ever holds a signer port, so that private key material never reaches this
+ * package.
+ *
+ * @param {Object} opts
+ * @param {string} opts.iss - our DID
+ * @param {string} opts.aud - the service we are calling
+ * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
+ * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @returns {Promise<string>}
+ */
+export declare function createServiceAuth({ iss, aud, lxm, signer }: {
+    iss: string;
+    aud: string;
+    lxm: string;
+    signer: {
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    };
+}): Promise<string>;

package/src/service-auth.js

@@ -0,0 +1,153 @@
+// @pdsjs/spaces/service-auth - verifying inter-service calls.
+//
+// notifyWrite and notifySpaceDeleted are server-to-server: a repo host tells an
+// authority its user wrote, an authority tells syncers a space is gone. Both are
+// authenticated with ordinary atproto service auth — a JWT signed by the
+// caller's #atproto key, addressed to us, naming the method it is calling.
+
+import { base64UrlEncode, bytesToHex } from '@pdsjs/core/crypto';
+import { atprotoSigningKey } from './authority.js';
+import { SpaceTokenError } from './token.js';
+
+const CLOCK_SKEW_SEC = 5;
+
+/**
+ * @param {string} b64
+ * @returns {any}
+ */
+function decodePart(b64) {
+  const pad = b64.replace(/-/g, '+').replace(/_/g, '/');
+  const bytes = Uint8Array.from(
+    atob(pad + '='.repeat((4 - (pad.length % 4)) % 4)),
+    (c) => c.charCodeAt(0),
+  );
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+/**
+ * @param {string} b64
+ * @returns {Uint8Array}
+ */
+function decodeSig(b64) {
+  const pad = b64.replace(/-/g, '+').replace(/_/g, '/');
+  return Uint8Array.from(
+    atob(pad + '='.repeat((4 - (pad.length % 4)) % 4)),
+    (c) => c.charCodeAt(0),
+  );
+}
+
+/**
+ * Verify a service-auth JWT presented to us.
+ *
+ * @param {Object} opts
+ * @param {string} opts.jwt
+ * @param {string} opts.aud - our own DID; the token must be addressed to us
+ * @param {string} opts.lxm - the method being called
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @returns {Promise<{iss: string}>}
+ */
+export async function verifyServiceAuth({
+  jwt,
+  aud,
+  lxm,
+  resolveDid,
+  verifier,
+}) {
+  const parts = typeof jwt === 'string' ? jwt.split('.') : [];
+  if (parts.length !== 3) {
+    throw new SpaceTokenError('malformed service token', 'BadJwt');
+  }
+  const [headerB64, payloadB64, sigB64] = parts;
+
+  /** @type {any} */
+  let payload;
+  try {
+    decodePart(headerB64);
+    payload = decodePart(payloadB64);
+  } catch {
+    throw new SpaceTokenError('could not parse service token', 'BadJwt');
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof payload.exp !== 'number' || now - CLOCK_SKEW_SEC >= payload.exp) {
+    throw new SpaceTokenError('service token expired', 'JwtExpired');
+  }
+  if (!payload.iss) {
+    throw new SpaceTokenError('missing service token "iss"', 'BadJwtIss');
+  }
+  if (payload.aud !== aud) {
+    throw new SpaceTokenError(
+      'service token is not addressed to this service',
+      'BadJwtAudience',
+    );
+  }
+  // An lxm claim scopes a token to one method, so a token minted for one call
+  // cannot be replayed against another. Absent, it would be usable anywhere.
+  if (payload.lxm !== lxm) {
+    throw new SpaceTokenError(
+      `service token is not scoped to ${lxm}`,
+      'BadJwtLexiconMethod',
+    );
+  }
+
+  const didDoc = await resolveDid(payload.iss);
+  if (!didDoc) {
+    throw new SpaceTokenError(
+      `could not resolve ${payload.iss}`,
+      'DidNotFound',
+    );
+  }
+  const didKey = atprotoSigningKey(didDoc, payload.iss);
+  const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+
+  let valid;
+  try {
+    valid = await verifier.verify(didKey, signingInput, decodeSig(sigB64));
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not verify service token: ${err instanceof Error ? err.message : String(err)}`,
+      'BadJwtSignature',
+    );
+  }
+  if (!valid) {
+    throw new SpaceTokenError(
+      'invalid service token signature',
+      'BadJwtSignature',
+    );
+  }
+
+  return { iss: payload.iss };
+}
+
+/**
+ * Mint a service-auth JWT for an outbound call.
+ *
+ * Core has its own createServiceJwt, but it takes a CryptoKey; @pdsjs/spaces only
+ * ever holds a signer port, so that private key material never reaches this
+ * package.
+ *
+ * @param {Object} opts
+ * @param {string} opts.iss - our DID
+ * @param {string} opts.aud - the service we are calling
+ * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
+ * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @returns {Promise<string>}
+ */
+export async function createServiceAuth({ iss, aud, lxm, signer }) {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { typ: 'JWT', alg: 'ES256' };
+  const payload = {
+    iss,
+    aud,
+    exp: now + 60,
+    iat: now,
+    jti: bytesToHex(crypto.getRandomValues(new Uint8Array(16))),
+    lxm,
+  };
+  const encode = (/** @type {object} */ o) =>
+    base64UrlEncode(new TextEncoder().encode(JSON.stringify(o)));
+  const signingInput = `${encode(header)}.${encode(payload)}`;
+  const sig = await signer.sign(new TextEncoder().encode(signingInput));
+  return `${signingInput}.${base64UrlEncode(sig)}`;
+}

package/src/space-row.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Build a SpaceRow from a space URI.
+ *
+ * `SpaceRow` carries `spaceDid` and `spaceType` alongside `uri` so the storage
+ * adapters can filter on indexed columns without parsing AT-URIs themselves
+ * (parsing is domain logic and lives here). Those fields are therefore
+ * redundant with `uri`, and nothing downstream re-checks that they agree — so
+ * every construction site goes through this function rather than assembling the
+ * object by hand.
+ *
+ * @param {string} uri - space AT-URI
+ * @param {Partial<Omit<import('@pdsjs/core/ports').SpaceRow, 'uri'|'spaceDid'|'spaceType'>>} [fields]
+ * @returns {import('@pdsjs/core/ports').SpaceRow}
+ */
+export declare function makeSpaceRow(uri: string, fields?: Partial<Omit<import('@pdsjs/core/ports').SpaceRow, 'uri' | 'spaceDid' | 'spaceType'>>): import('@pdsjs/core/ports').SpaceRow;