@pdsjs/spaces 1.0.0

package/src/space-row.js

@@ -0,0 +1,33 @@
+// @pdsjs/spaces/space-row - the one place a SpaceRow is constructed.
+
+import { parseSpaceUri } from './uri.js';
+
+/**
+ * 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 function makeSpaceRow(uri, fields = {}) {
+  const { spaceDid, spaceType } = parseSpaceUri(uri);
+  return {
+    uri,
+    spaceDid,
+    spaceType,
+    isOwner: fields.isOwner ?? false,
+    policy: fields.policy ?? 'member-list',
+    managingApp: fields.managingApp ?? null,
+    appAccessType: fields.appAccessType ?? 'open',
+    appAllowed: fields.appAllowed ? [...fields.appAllowed] : [],
+    createdAt: fields.createdAt ?? new Date().toISOString(),
+    deletedAt: fields.deletedAt ?? null,
+  };
+}

package/src/token.d.ts

@@ -0,0 +1,95 @@
+export declare const SPACE_TOKEN_TYPES: {
+    delegation: {
+        typ: string;
+        kid: string;
+        expiresInSec: number;
+        requireAud: boolean;
+    };
+    credential: {
+        typ: string;
+        kid: string;
+        expiresInSec: number;
+        requireAud: boolean;
+    };
+    clientAttestation: {
+        typ: string;
+        kid: undefined;
+        expiresInSec: number;
+        requireAud: boolean;
+    };
+};
+export declare class SpaceTokenError extends Error {
+    code: string;
+    /**
+     * @param {string} message
+     * @param {string} [code] - machine-readable error name for the XRPC response
+     */
+    constructor(message: string, code?: string);
+}
+export type SpaceTokenPayload = {
+    iss: string;
+    /**
+     * - the space URI, or the client_id for an attestation
+     */
+    sub: string;
+    aud?: string;
+    iat: number;
+    exp: number;
+    jti: string;
+};
+export type SpaceTokenHeader = {
+    alg: string;
+    typ: string;
+    kid?: string;
+};
+/**
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {{iss: string, sub: string, aud?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
+ * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @returns {Promise<string>}
+ */
+export declare function createSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, opts: {
+    iss: string;
+    sub: string;
+    aud?: string;
+    expiresInSec?: number;
+    kid?: string;
+    alg?: string;
+}, signer: {
+    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+}): Promise<string>;
+/**
+ * Structural validation only, no signature check. This is as far as we go for
+ * client attestations, whose key comes from the client's JWKS rather than a DID
+ * document.
+ *
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {string} jwt
+ * @returns {{header: SpaceTokenHeader, payload: SpaceTokenPayload, signingInput: Uint8Array, sig: Uint8Array}}
+ */
+export declare function parseSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jwt: string): {
+    header: SpaceTokenHeader;
+    payload: SpaceTokenPayload;
+    signingInput: Uint8Array;
+    sig: Uint8Array;
+};
+/**
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {string} jwt
+ * @param {Object} opts
+ * @param {(iss: string, kid?: string) => Promise<string>} opts.getSigningKey
+ *   - resolves the issuer to a did:key. Given `kid` so it can honour the key id.
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @param {string} [opts.aud] - required audience, when the caller knows it
+ * @param {string} [opts.sub] - required subject, when the caller knows it
+ * @returns {Promise<{header: SpaceTokenHeader, payload: SpaceTokenPayload}>}
+ */
+export declare function verifySpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jwt: string, opts: {
+    getSigningKey: (iss: string, kid?: string) => Promise<string>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+    aud?: string;
+    sub?: string;
+}): Promise<{
+    header: SpaceTokenHeader;
+    payload: SpaceTokenPayload;
+}>;

package/src/token.js

@@ -0,0 +1,223 @@
+// @pdsjs/spaces/token - the three space JWTs.
+//
+// A delegation token proves the user delegated to an app; a client attestation
+// proves which app is acting; a space credential is what the authority issues in
+// exchange, and is what repo hosts actually accept.
+//
+// They share a wire shape and differ only in who signs, who they address, and
+// how long they live — so they are data, not three implementations.
+
+import { base64UrlDecode, base64UrlEncode, bytesToHex } from '@pdsjs/core/crypto';
+
+export const SPACE_TOKEN_TYPES = {
+  delegation: {
+    typ: 'atproto-space-delegation+jwt',
+    kid: '#atproto',
+    expiresInSec: 60,
+    requireAud: true,
+  },
+  credential: {
+    typ: 'atproto-space-credential+jwt',
+    kid: '#atproto_space',
+    // Multi-use across repo hosts until it expires, so it carries no aud.
+    expiresInSec: 7200,
+    requireAud: false,
+  },
+  clientAttestation: {
+    typ: 'atproto-client-attestation+jwt',
+    kid: undefined,
+    expiresInSec: 60,
+    requireAud: true,
+  },
+};
+
+const CLOCK_SKEW_SEC = 5;
+
+export class SpaceTokenError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code] - machine-readable error name for the XRPC response
+   */
+  constructor(message, code = 'InvalidToken') {
+    super(message);
+    this.name = 'SpaceTokenError';
+    this.code = code;
+  }
+}
+
+/**
+ * @typedef {Object} SpaceTokenPayload
+ * @property {string} iss
+ * @property {string} sub - the space URI, or the client_id for an attestation
+ * @property {string} [aud]
+ * @property {number} iat
+ * @property {number} exp
+ * @property {string} jti
+ */
+
+/**
+ * @typedef {Object} SpaceTokenHeader
+ * @property {string} alg
+ * @property {string} typ
+ * @property {string} [kid]
+ */
+
+/**
+ * @param {Record<string, unknown>} json
+ * @returns {string}
+ */
+function jsonToB64Url(json) {
+  return base64UrlEncode(new TextEncoder().encode(JSON.stringify(json)));
+}
+
+/**
+ * @param {string} b64
+ * @param {string} part
+ * @returns {any}
+ */
+function decodeJsonPart(b64, part) {
+  try {
+    return JSON.parse(new TextDecoder().decode(base64UrlDecode(b64)));
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not parse token ${part}: ${err instanceof Error ? err.message : String(err)}`,
+      'BadJwt',
+    );
+  }
+}
+
+/**
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {{iss: string, sub: string, aud?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
+ * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @returns {Promise<string>}
+ */
+export async function createSpaceToken(type, opts, signer) {
+  const spec = SPACE_TOKEN_TYPES[type];
+  if (spec.requireAud && !opts.aud) {
+    throw new SpaceTokenError(`a ${type} token requires an "aud"`);
+  }
+
+  const iat = Math.floor(Date.now() / 1000);
+  /** @type {SpaceTokenHeader} */
+  const header = { alg: opts.alg ?? 'ES256', typ: spec.typ };
+  const kid = opts.kid ?? spec.kid;
+  if (kid) header.kid = kid;
+
+  /** @type {SpaceTokenPayload} */
+  const payload = {
+    iss: opts.iss,
+    sub: opts.sub,
+    ...(opts.aud ? { aud: opts.aud } : undefined),
+    iat,
+    exp: iat + (opts.expiresInSec ?? spec.expiresInSec),
+    jti: bytesToHex(crypto.getRandomValues(new Uint8Array(16))),
+  };
+
+  const signingInput = `${jsonToB64Url(header)}.${jsonToB64Url(payload)}`;
+  const sig = await signer.sign(new TextEncoder().encode(signingInput));
+  return `${signingInput}.${base64UrlEncode(sig)}`;
+}
+
+/**
+ * Structural validation only, no signature check. This is as far as we go for
+ * client attestations, whose key comes from the client's JWKS rather than a DID
+ * document.
+ *
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {string} jwt
+ * @returns {{header: SpaceTokenHeader, payload: SpaceTokenPayload, signingInput: Uint8Array, sig: Uint8Array}}
+ */
+export function parseSpaceToken(type, jwt) {
+  const spec = SPACE_TOKEN_TYPES[type];
+
+  const parts = typeof jwt === 'string' ? jwt.split('.') : [];
+  if (parts.length !== 3) {
+    throw new SpaceTokenError('malformed token: expected 3 parts', 'BadJwt');
+  }
+  const [headerB64, payloadB64, sigB64] = parts;
+
+  const header = decodeJsonPart(headerB64, 'header');
+  const payload = decodeJsonPart(payloadB64, 'payload');
+
+  if (header.typ !== spec.typ) {
+    throw new SpaceTokenError(
+      `wrong token type: expected "${spec.typ}", got "${header.typ}"`,
+      'BadJwtType',
+    );
+  }
+  if (typeof header.alg !== 'string' || !header.alg) {
+    throw new SpaceTokenError('missing token "alg"', 'BadJwt');
+  }
+  if (!payload.iss)
+    throw new SpaceTokenError('missing token "iss"', 'BadJwtIss');
+  if (!payload.sub)
+    throw new SpaceTokenError('missing token "sub"', 'BadJwtSub');
+  if (typeof payload.exp !== 'number') {
+    throw new SpaceTokenError('missing token "exp"', 'BadJwt');
+  }
+  if (spec.requireAud && !payload.aud) {
+    throw new SpaceTokenError('missing token "aud"', 'BadJwtAudience');
+  }
+  if (type === 'clientAttestation' && payload.iss !== payload.sub) {
+    throw new SpaceTokenError(
+      'client attestation "iss" and "sub" must both be the client_id',
+      'BadJwtIss',
+    );
+  }
+
+  return {
+    header,
+    payload,
+    signingInput: new TextEncoder().encode(`${headerB64}.${payloadB64}`),
+    sig: base64UrlDecode(sigB64),
+  };
+}
+
+/**
+ * @param {keyof typeof SPACE_TOKEN_TYPES} type
+ * @param {string} jwt
+ * @param {Object} opts
+ * @param {(iss: string, kid?: string) => Promise<string>} opts.getSigningKey
+ *   - resolves the issuer to a did:key. Given `kid` so it can honour the key id.
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @param {string} [opts.aud] - required audience, when the caller knows it
+ * @param {string} [opts.sub] - required subject, when the caller knows it
+ * @returns {Promise<{header: SpaceTokenHeader, payload: SpaceTokenPayload}>}
+ */
+export async function verifySpaceToken(type, jwt, opts) {
+  const { header, payload, signingInput, sig } = parseSpaceToken(type, jwt);
+
+  const now = Math.floor(Date.now() / 1000);
+  if (now - CLOCK_SKEW_SEC >= payload.exp) {
+    throw new SpaceTokenError('token expired', 'JwtExpired');
+  }
+  if (opts.aud !== undefined && payload.aud !== opts.aud) {
+    throw new SpaceTokenError(
+      'token audience does not match this service',
+      'BadJwtAudience',
+    );
+  }
+  if (opts.sub !== undefined && payload.sub !== opts.sub) {
+    throw new SpaceTokenError(
+      'token subject does not match the requested space',
+      'BadJwtSub',
+    );
+  }
+
+  const didKey = await opts.getSigningKey(payload.iss, header.kid);
+  let valid;
+  try {
+    valid = await opts.verifier.verify(didKey, signingInput, sig);
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not verify token signature: ${err instanceof Error ? err.message : String(err)}`,
+      'BadJwtSignature',
+    );
+  }
+  if (!valid) {
+    throw new SpaceTokenError('invalid token signature', 'BadJwtSignature');
+  }
+
+  return { header, payload };
+}

package/src/uri.d.ts

@@ -0,0 +1,32 @@
+export declare const SPACE_MARKER = "space";
+/**
+ * @param {{spaceDid: string, spaceType: string, skey: string,
+ *          authorDid?: string|null, collection?: string|null, rkey?: string|null}} parts
+ * @returns {string}
+ */
+export declare function formatSpaceUri(parts: {
+    spaceDid: string;
+    spaceType: string;
+    skey: string;
+    authorDid?: string | null;
+    collection?: string | null;
+    rkey?: string | null;
+}): string;
+/**
+ * @param {string} uri
+ * @returns {boolean}
+ */
+export declare function isSpaceUri(uri: string): boolean;
+/**
+ * @param {string} uri
+ * @returns {{spaceDid: string, spaceType: string, skey: string,
+ *            authorDid: string|null, collection: string|null, rkey: string|null}}
+ */
+export declare function parseSpaceUri(uri: string): {
+    spaceDid: string;
+    spaceType: string;
+    skey: string;
+    authorDid: string | null;
+    collection: string | null;
+    rkey: string | null;
+};

package/src/uri.js

@@ -0,0 +1,89 @@
+// @pdsjs/spaces/uri - permissioned space AT-URI addressing.
+//
+//   at://{spaceDid}/space/{spaceType}/{skey}[/{authorDid}/{collection}/{rkey}]
+//
+// Space URIs are distinguished from public ones by the literal `space` segment,
+// which contains no dots, whereas a collection NSID always contains at least two.
+
+export const SPACE_MARKER = 'space';
+
+/**
+ * @param {{spaceDid: string, spaceType: string, skey: string,
+ *          authorDid?: string|null, collection?: string|null, rkey?: string|null}} parts
+ * @returns {string}
+ */
+export function formatSpaceUri(parts) {
+  const { spaceDid, spaceType, skey, authorDid, collection, rkey } = parts;
+  const optionalCount = [authorDid, collection, rkey].filter(Boolean).length;
+  if (optionalCount !== 0 && optionalCount !== 3) {
+    throw new Error(
+      'authorDid, collection, and rkey must be all present or all absent',
+    );
+  }
+  let uri = `at://${spaceDid}/${SPACE_MARKER}/${spaceType}/${skey}`;
+  if (authorDid) uri += `/${authorDid}`;
+  if (collection) uri += `/${collection}`;
+  if (rkey) uri += `/${rkey}`;
+  return uri;
+}
+
+/**
+ * @param {string} uri
+ * @returns {boolean}
+ */
+export function isSpaceUri(uri) {
+  const segments = splitUri(uri);
+  return segments !== null && segments[1] === SPACE_MARKER;
+}
+
+/**
+ * @param {string} uri
+ * @returns {{spaceDid: string, spaceType: string, skey: string,
+ *            authorDid: string|null, collection: string|null, rkey: string|null}}
+ */
+export function parseSpaceUri(uri) {
+  const segments = splitUri(uri);
+  if (segments === null || segments[1] !== SPACE_MARKER) {
+    throw new Error(`not a space URI: ${uri}`);
+  }
+  const [spaceDid, , spaceType, skey, authorDid, collection, rkey] = segments;
+  if (segments.length !== 4 && segments.length !== 7) {
+    throw new Error(`invalid space URI: ${uri}`);
+  }
+  if (!spaceDid.startsWith('did:')) {
+    throw new Error(`space authority must be a DID: ${uri}`);
+  }
+  if (!spaceType.includes('.')) {
+    throw new Error(`space type must be an NSID: ${uri}`);
+  }
+  if (!skey) throw new Error(`invalid space URI: ${uri}`);
+  if (segments.length === 4) {
+    return {
+      spaceDid,
+      spaceType,
+      skey,
+      authorDid: null,
+      collection: null,
+      rkey: null,
+    };
+  }
+  if (!authorDid.startsWith('did:')) {
+    throw new Error(`space record author must be a DID: ${uri}`);
+  }
+  if (!collection.includes('.')) {
+    throw new Error(`collection must be an NSID: ${uri}`);
+  }
+  if (!rkey) throw new Error(`invalid space URI: ${uri}`);
+  return { spaceDid, spaceType, skey, authorDid, collection, rkey };
+}
+
+/**
+ * @param {string} uri
+ * @returns {string[]|null} host followed by path segments, or null if not an at:// URI
+ */
+function splitUri(uri) {
+  if (!uri.startsWith('at://')) return null;
+  const segments = uri.slice('at://'.length).split('/');
+  if (segments.length < 2 || segments.some((s) => s === '')) return null;
+  return segments;
+}

package/src/verifier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @param {string} didKey - did:key:z… (the did: prefix is optional)
+ * @returns {{curve: 'p256'|'secp256k1', publicKey: Uint8Array}}
+ */
+export declare function parseDidKey(didKey: string): {
+    curve: 'p256' | 'secp256k1';
+    publicKey: Uint8Array;
+};
+/**
+ * @param {{secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>}} [opts]
+ * @returns {import('@pdsjs/core/ports').SignatureVerifierPort}
+ */
+export declare function createVerifier(opts?: {
+    secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>;
+}): import('@pdsjs/core/ports').SignatureVerifierPort;

package/src/verifier.js

@@ -0,0 +1,74 @@
+// @pdsjs/spaces/verifier - signature verification port.
+//
+// P-256 ships built in on crypto.subtle. secp256k1 is injected: hand-rolling
+// ECDSA verification is a different risk class from hand-rolling a hash, since
+// a subtle bug means accepting a forged credential rather than a failing test.
+// Without an injected verifier, spaces interoperate only with P-256 accounts.
+
+import { base58btcDecode, P256_MULTICODEC } from '@pdsjs/core/plc';
+
+const SECP256K1_MULTICODEC = [0xe7, 0x01];
+
+/**
+ * @param {string} didKey - did:key:z… (the did: prefix is optional)
+ * @returns {{curve: 'p256'|'secp256k1', publicKey: Uint8Array}}
+ */
+export function parseDidKey(didKey) {
+  const value = didKey.startsWith('did:key:') ? didKey.slice(8) : didKey;
+  if (!value.startsWith('z')) {
+    throw new Error(`expected a did:key multibase value, got: ${didKey}`);
+  }
+  const bytes = base58btcDecode(value.slice(1));
+  if (bytes[0] === P256_MULTICODEC[0] && bytes[1] === P256_MULTICODEC[1]) {
+    return { curve: 'p256', publicKey: bytes.slice(2) };
+  }
+  if (
+    bytes[0] === SECP256K1_MULTICODEC[0] &&
+    bytes[1] === SECP256K1_MULTICODEC[1]
+  ) {
+    return { curve: 'secp256k1', publicKey: bytes.slice(2) };
+  }
+  throw new Error(`unsupported did:key multicodec: ${didKey}`);
+}
+
+/**
+ * @param {{secp256k1?: (publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array) => Promise<boolean>}} [opts]
+ * @returns {import('@pdsjs/core/ports').SignatureVerifierPort}
+ */
+export function createVerifier(opts = {}) {
+  return {
+    async verify(didKey, data, sig) {
+      const { curve, publicKey } = parseDidKey(didKey);
+      if (curve === 'p256') return verifyP256(publicKey, data, sig);
+      if (!opts.secp256k1) {
+        throw new Error(
+          'secp256k1 verification requires an injected verifier; ' +
+            'this deployment supports P-256 keys only',
+        );
+      }
+      return opts.secp256k1(publicKey, data, sig);
+    },
+  };
+}
+
+/**
+ * @param {Uint8Array} publicKey - 33-byte compressed point
+ * @param {Uint8Array} data
+ * @param {Uint8Array} sig - 64-byte raw r||s
+ * @returns {Promise<boolean>}
+ */
+async function verifyP256(publicKey, data, sig) {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    /** @type {BufferSource} */ (publicKey),
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['verify'],
+  );
+  return crypto.subtle.verify(
+    { name: 'ECDSA', hash: 'SHA-256' },
+    key,
+    /** @type {BufferSource} */ (sig),
+    /** @type {BufferSource} */ (data),
+  );
+}

package/src/writer.d.ts

@@ -0,0 +1,77 @@
+export declare const MAX_WRITES_PER_COMMIT = 200;
+export declare class SpaceWriteError extends Error {
+    code: string;
+    /**
+     * @param {string} message
+     * @param {string} code - machine-readable error name for the XRPC response
+     */
+    constructor(message: string, code: string);
+}
+export declare class SpaceRecordNotFoundError extends SpaceWriteError {
+    /** @param {string} collection @param {string} rkey */
+    constructor(collection: string, rkey: string);
+}
+export declare class SpaceRecordAlreadyExistsError extends SpaceWriteError {
+    /** @param {string} collection @param {string} rkey */
+    constructor(collection: string, rkey: string);
+}
+export type SpaceWriteInput = {
+    action: 'create' | 'update' | 'put' | 'delete';
+    collection: string;
+    rkey: string;
+    /**
+     * - required for everything but delete
+     */
+    record?: Object;
+};
+export type SpaceWriteResult = {
+    action: 'create' | 'update' | 'delete';
+    collection: string;
+    rkey: string;
+    /**
+     * - null for deletes
+     */
+    cid: string | null;
+    /**
+     * - null for creates
+     */
+    prev: string | null;
+};
+/**
+ * @typedef {Object} SpaceWriteInput
+ * @property {'create'|'update'|'put'|'delete'} action
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {Object} [record] - required for everything but delete
+ */
+/**
+ * @typedef {Object} SpaceWriteResult
+ * @property {'create'|'update'|'delete'} action
+ * @property {string} collection
+ * @property {string} rkey
+ * @property {string|null} cid - null for deletes
+ * @property {string|null} prev - null for creates
+ */
+/**
+ * Apply a batch of writes to a permissioned repo as one commit.
+ *
+ * Writes resolve in order against the state the batch has built up, not just
+ * what was stored on entry, so a batch can create then update a record and a
+ * repeated create is still caught rather than double-counted in the set hash.
+ *
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} storage
+ * @param {Object} opts
+ * @param {string} opts.space - space AT-URI
+ * @param {SpaceWriteInput[]} opts.writes
+ * @param {string} [opts.now] - ISO timestamp, for deterministic tests
+ * @returns {Promise<{rev: string, setHash: Uint8Array, results: SpaceWriteResult[]}>}
+ */
+export declare function applyWrites(storage: import('@pdsjs/core/ports').SpaceStoragePort, { space, writes, now }: {
+    space: string;
+    writes: SpaceWriteInput[];
+    now?: string;
+}): Promise<{
+    rev: string;
+    setHash: Uint8Array;
+    results: SpaceWriteResult[];
+}>;