@pdsjs/spaces 1.0.0

package/src/commit.d.ts

@@ -0,0 +1,109 @@
+import { LtHash } from './lthash.js';
+export type SignedCommit = {
+    ver: number;
+    hash: Uint8Array;
+    ikm: Uint8Array;
+    sig: Uint8Array;
+    mac: Uint8Array;
+    rev: string;
+};
+/**
+ * @typedef {Object} SignedCommit
+ * @property {number} ver
+ * @property {Uint8Array} hash
+ * @property {Uint8Array} ikm
+ * @property {Uint8Array} sig
+ * @property {Uint8Array} mac
+ * @property {string} rev
+ */
+export declare class RepoCommit {
+    setHash: LtHash;
+    /** @param {LtHash} [setHash] */
+    constructor(setHash?: LtHash);
+    /** @param {Uint8Array|null|undefined} state */
+    static fromState(state: Uint8Array | null | undefined): RepoCommit;
+    /** @param {Iterable<{collection: string, rkey: string, cid: string}>} records */
+    static fromRecords(records: Iterable<{
+        collection: string;
+        rkey: string;
+        cid: string;
+    }>): RepoCommit;
+    /**
+     * Fold in every record an index describes, to compare against a commit.
+     * @param {Record<string, string>} index - "{collection}/{rkey}" to CID
+     */
+    static fromIndex(index: Record<string, string>): RepoCommit;
+    /**
+     * @param {string} collection
+     * @param {string} rkey
+     * @param {string} cid
+     * @returns {this}
+     */
+    add(collection: string, rkey: string, cid: string): this;
+    /**
+     * @param {string} collection
+     * @param {string} rkey
+     * @param {string} cid
+     * @returns {this}
+     */
+    remove(collection: string, rkey: string, cid: string): this;
+    /** @param {{collection: string, rkey: string, cid: string|null, prev: string|null}} op */
+    applyOp(op: {
+        collection: string;
+        rkey: string;
+        cid: string | null;
+        prev: string | null;
+    }): this;
+    /**
+     * @param {Iterable<{collection: string, rkey: string, cid: string|null, prev: string|null}>} ops
+     * @returns {this}
+     */
+    applyOps(ops: Iterable<{
+        collection: string;
+        rkey: string;
+        cid: string | null;
+        prev: string | null;
+    }>): this;
+    state(): Uint8Array<ArrayBufferLike>;
+    /**
+     * Whether this repo's contents match a signed commit. Verify the commit first —
+     * on its own this says nothing about authenticity.
+     * @param {SignedCommit} commit
+     */
+    matches(commit: SignedCommit): Promise<boolean>;
+    /**
+     * Sign a commit over the current contents.
+     *
+     * The signature covers only the ctx, never the digest, so a leaked commit
+     * proves nothing about what the author wrote. The digest is bound to the ctx
+     * by a symmetric MAC instead: readers get integrity, third parties get
+     * nothing. A fresh ikm per commit means each reader receives a distinct one.
+     *
+     * @param {{space: string, author: string, rev: string}} ctx
+     * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+     * @returns {Promise<SignedCommit>}
+     */
+    sign(ctx: {
+        space: string;
+        author: string;
+        rev: string;
+    }, signer: {
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    }): Promise<SignedCommit>;
+}
+/**
+ * Verify a commit's signature (authenticity) and MAC (integrity). Once this
+ * passes, `hash` is trusted as the author's claim about their repo, which is
+ * what makes RepoCommit#matches meaningful.
+ *
+ * @param {SignedCommit} commit
+ * @param {{space: string, author: string, rev: string}} ctx
+ * @param {string} didKey
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} verifier
+ * @returns {Promise<boolean>}
+ */
+export declare function verifyCommit(commit: SignedCommit, ctx: {
+    space: string;
+    author: string;
+    rev: string;
+}, didKey: string, verifier: import('@pdsjs/core/ports').SignatureVerifierPort): Promise<boolean>;

package/src/commit.js

@@ -0,0 +1,152 @@
+// @pdsjs/spaces/commit - permissioned repo commits with deniable signatures.
+
+import { LtHash } from './lthash.js';
+import {
+  bytesEqual,
+  COMMIT_VERSION,
+  computeMac,
+  encodeCommitCtx,
+} from './mac.js';
+import { formatSetHashElement } from './path.js';
+
+/**
+ * @typedef {Object} SignedCommit
+ * @property {number} ver
+ * @property {Uint8Array} hash
+ * @property {Uint8Array} ikm
+ * @property {Uint8Array} sig
+ * @property {Uint8Array} mac
+ * @property {string} rev
+ */
+
+export class RepoCommit {
+  /** @param {LtHash} [setHash] */
+  constructor(setHash = new LtHash()) {
+    this.setHash = setHash;
+  }
+
+  /** @param {Uint8Array|null|undefined} state */
+  static fromState(state) {
+    return new RepoCommit(new LtHash(state ?? null));
+  }
+
+  /** @param {Iterable<{collection: string, rkey: string, cid: string}>} records */
+  static fromRecords(records) {
+    const commit = new RepoCommit();
+    for (const { collection, rkey, cid } of records) {
+      commit.add(collection, rkey, cid);
+    }
+    return commit;
+  }
+
+  /**
+   * Fold in every record an index describes, to compare against a commit.
+   * @param {Record<string, string>} index - "{collection}/{rkey}" to CID
+   */
+  static fromIndex(index) {
+    const commit = new RepoCommit();
+    for (const [path, cid] of Object.entries(index)) {
+      commit.setHash.add(`${path}/${cid}`);
+    }
+    return commit;
+  }
+
+  /**
+   * @param {string} collection
+   * @param {string} rkey
+   * @param {string} cid
+   * @returns {this}
+   */
+  add(collection, rkey, cid) {
+    this.setHash.add(formatSetHashElement(collection, rkey, cid));
+    return this;
+  }
+
+  /**
+   * @param {string} collection
+   * @param {string} rkey
+   * @param {string} cid
+   * @returns {this}
+   */
+  remove(collection, rkey, cid) {
+    this.setHash.remove(formatSetHashElement(collection, rkey, cid));
+    return this;
+  }
+
+  /** @param {{collection: string, rkey: string, cid: string|null, prev: string|null}} op */
+  applyOp(op) {
+    if (op.prev) this.remove(op.collection, op.rkey, op.prev);
+    if (op.cid) this.add(op.collection, op.rkey, op.cid);
+    return this;
+  }
+
+  /**
+   * @param {Iterable<{collection: string, rkey: string, cid: string|null, prev: string|null}>} ops
+   * @returns {this}
+   */
+  applyOps(ops) {
+    for (const op of ops) this.applyOp(op);
+    return this;
+  }
+
+  state() {
+    return this.setHash.state();
+  }
+
+  /**
+   * Whether this repo's contents match a signed commit. Verify the commit first —
+   * on its own this says nothing about authenticity.
+   * @param {SignedCommit} commit
+   */
+  async matches(commit) {
+    return bytesEqual(await this.setHash.digest(), commit.hash);
+  }
+
+  /**
+   * Sign a commit over the current contents.
+   *
+   * The signature covers only the ctx, never the digest, so a leaked commit
+   * proves nothing about what the author wrote. The digest is bound to the ctx
+   * by a symmetric MAC instead: readers get integrity, third parties get
+   * nothing. A fresh ikm per commit means each reader receives a distinct one.
+   *
+   * @param {{space: string, author: string, rev: string}} ctx
+   * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+   * @returns {Promise<SignedCommit>}
+   */
+  async sign(ctx, signer) {
+    const hash = await this.setHash.digest();
+    const ikm = crypto.getRandomValues(new Uint8Array(32));
+    const ctxBytes = encodeCommitCtx(ctx, ikm);
+    return {
+      ver: COMMIT_VERSION,
+      hash,
+      ikm,
+      mac: await computeMac(ikm, ctxBytes, hash),
+      sig: await signer.sign(ctxBytes),
+      rev: ctx.rev,
+    };
+  }
+}
+
+/**
+ * Verify a commit's signature (authenticity) and MAC (integrity). Once this
+ * passes, `hash` is trusted as the author's claim about their repo, which is
+ * what makes RepoCommit#matches meaningful.
+ *
+ * @param {SignedCommit} commit
+ * @param {{space: string, author: string, rev: string}} ctx
+ * @param {string} didKey
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} verifier
+ * @returns {Promise<boolean>}
+ */
+export async function verifyCommit(commit, ctx, didKey, verifier) {
+  if (commit.ver !== COMMIT_VERSION) return false;
+  if (commit.rev !== ctx.rev) return false;
+
+  const ctxBytes = encodeCommitCtx(ctx, commit.ikm);
+  const mac = await computeMac(commit.ikm, ctxBytes, commit.hash);
+  if (!bytesEqual(mac, commit.mac)) return false;
+
+  return verifier.verify(didKey, ctxBytes, commit.sig);
+}

package/src/handlers/auth.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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
+ * @param {typeof fetch} [ctx.fetch]
+ * @returns {import('@pdsjs/core/pds').Routes}
+ */
+export declare function createAuthRoutes(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;
+/**
+ * Verify a space credential presented to a repo host.
+ *
+ * @param {Object} opts
+ * @param {string} opts.credential - the raw JWT
+ * @param {string} opts.space - the space the request targets
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
+ * @returns {Promise<{iss: string}>}
+ */
+export declare function verifySpaceCredential({ credential, space, resolveDid, verifier, }: {
+    credential: string;
+    space: string;
+    resolveDid: (did: string) => Promise<any>;
+    verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+}): Promise<{
+    iss: string;
+}>;
+/**
+ * Ask a space's managing app whether to authorize a user.
+ *
+ * Fails closed: anything short of an explicit `authorized: true` is a refusal,
+ * so an app being down denies access rather than granting it.
+ *
+ * @param {Object} opts
+ * @param {string|null} opts.managingApp - a `did#serviceId` identifier
+ * @param {string} opts.authorityDid
+ * @param {string} opts.space
+ * @param {string} opts.userDid
+ * @param {string|undefined} opts.clientId
+ * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} opts.getSigner
+ * @param {typeof fetch} [opts.fetch]
+ * @returns {Promise<boolean>}
+ */
+export declare function checkUserAccess({ managingApp, authorityDid, space, userDid, clientId, resolveDid, getSigner, fetch: doFetch, }: {
+    managingApp: string | null;
+    authorityDid: string;
+    space: string;
+    userDid: string;
+    clientId: string | undefined;
+    resolveDid: (did: string) => Promise<any>;
+    getSigner: () => Promise<{
+        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    }>;
+    fetch?: typeof fetch;
+}): Promise<boolean>;