@git-stunts/git-warp 10.7.0 → 11.2.1

package/src/domain/trust/TrustRecordService.js

@@ -0,0 +1,274 @@
+/**
+ * Trust V1 record service.
+ *
+ * Manages the append-only chain of signed trust records stored under
+ * `refs/warp/<graph>/trust/records`. Each record is a Git commit
+ * whose message carries CBOR-encoded record data.
+ *
+ * @module domain/trust/TrustRecordService
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 7
+ */
+
+import { buildTrustRecordRef } from '../utils/RefLayout.js';
+import { TrustRecordSchema } from './schemas.js';
+import { verifyRecordId } from './TrustCanonical.js';
+import TrustError from '../errors/TrustError.js';
+
+/**
+ * @typedef {Object} AppendOptions
+ * @property {boolean} [skipSignatureVerify=false] - Skip signature verification (for testing)
+ */
+
+export class TrustRecordService {
+  /**
+   * @param {Object} options
+   * @param {*} options.persistence - GraphPersistencePort adapter
+   * @param {*} options.codec - CodecPort adapter (CBOR)
+   */
+  constructor({ persistence, codec }) {
+    this._persistence = persistence;
+    this._codec = codec;
+  }
+
+  /**
+   * Appends a signed trust record to the chain.
+   *
+   * Validates:
+   * 1. Schema conformance
+   * 2. RecordId integrity (content-addressed)
+   * 3. Signature envelope completeness (alg + sig fields present)
+   * 4. Prev-link consistency (must match current tip's last recordId)
+   *
+   * Note: Full cryptographic signature verification (Ed25519 verify against
+   * issuer public key) is NOT performed here — it requires the trust state
+   * to resolve the issuer's key, which is a chicken-and-egg problem for
+   * genesis records. Crypto verification happens during `buildState()` /
+   * evaluation when the full key set is available.
+   *
+   * @param {string} graphName
+   * @param {Record<string, *>} record - Complete signed trust record
+   * @param {AppendOptions} [options]
+   * @returns {Promise<{commitSha: string, ref: string}>}
+   */
+  async appendRecord(graphName, record, options = {}) {
+    // 1. Schema validation
+    const parsed = TrustRecordSchema.safeParse(record);
+    if (!parsed.success) {
+      throw new TrustError(
+        `Trust record schema validation failed: ${parsed.error.message}`,
+        { code: 'E_TRUST_RECORD_INVALID' },
+      );
+    }
+
+    // 2. RecordId integrity
+    if (!verifyRecordId(record)) {
+      throw new TrustError(
+        'Trust record recordId does not match content',
+        { code: 'E_TRUST_RECORD_ID_MISMATCH' },
+      );
+    }
+
+    // 3. Signature envelope check (structural, not cryptographic)
+    if (!options.skipSignatureVerify) {
+      this._verifySignatureEnvelope(record);
+    }
+
+    // 4. Prev-link consistency
+    const ref = buildTrustRecordRef(graphName);
+    const { tipSha, recordId: currentTip } = await this._readTip(ref);
+
+    if (record.prev !== currentTip) {
+      throw new TrustError(
+        `Prev-link mismatch: record.prev=${record.prev}, chain tip=${currentTip}`,
+        { code: 'E_TRUST_PREV_MISMATCH' },
+      );
+    }
+
+    // 5. Persist as Git commit (passes tipSha to avoid re-reading ref)
+    const commitSha = await this._persistRecord(ref, record, tipSha);
+    return { commitSha, ref };
+  }
+
+  /**
+   * Reads all trust records from the chain, oldest first.
+   *
+   * @param {string} graphName
+   * @param {Object} [options]
+   * @param {string} [options.tip] - Override tip commit (for pinned reads)
+   * @returns {Promise<Array<Record<string, *>>>}
+   */
+  async readRecords(graphName, options = {}) {
+    const ref = buildTrustRecordRef(graphName);
+    let tip = options.tip ?? null;
+
+    if (!tip) {
+      try {
+        tip = await this._persistence.readRef(ref);
+      } catch {
+        return [];
+      }
+      if (!tip) {
+        return [];
+      }
+    }
+
+    const records = [];
+    let current = tip;
+
+    while (current) {
+      const info = await this._persistence.getNodeInfo(current);
+      const record = this._codec.decode(
+        await this._persistence.readBlob(
+          (await this._persistence.readTreeOids(
+            await this._persistence.getCommitTree(current),
+          ))['record.cbor'],
+        ),
+      );
+
+      records.unshift(record);
+
+      if (info.parents.length === 0) {
+        break;
+      }
+      current = info.parents[0];
+    }
+
+    return records;
+  }
+
+  /**
+   * Verifies the structural integrity of a record chain.
+   *
+   * Checks:
+   * - Prev-links form an unbroken chain
+   * - No duplicate recordIds
+   * - Each record passes schema validation
+   * - First record has prev=null
+   *
+   * @param {Array<Record<string, *>>} records - Records in chain order (oldest first)
+   * @returns {{valid: boolean, errors: Array<{index: number, error: string}>}}
+   */
+  verifyChain(records) {
+    /** @type {Array<{index: number, error: string}>} */
+    const errors = [];
+    const seenIds = new Set();
+
+    for (let i = 0; i < records.length; i++) {
+      const record = records[i];
+
+      // Schema validation
+      const parsed = TrustRecordSchema.safeParse(record);
+      if (!parsed.success) {
+        errors.push({ index: i, error: `Schema: ${parsed.error.message}` });
+        continue;
+      }
+
+      // RecordId integrity
+      if (!verifyRecordId(record)) {
+        errors.push({ index: i, error: 'RecordId does not match content' });
+      }
+
+      // Duplicate detection
+      if (seenIds.has(record.recordId)) {
+        errors.push({ index: i, error: `Duplicate recordId: ${record.recordId}` });
+      }
+      seenIds.add(record.recordId);
+
+      // Prev-link check
+      if (i === 0) {
+        if (record.prev !== null) {
+          errors.push({ index: i, error: `Genesis record must have prev=null, got ${record.prev}` });
+        }
+      } else {
+        const expectedPrev = records[i - 1].recordId;
+        if (record.prev !== expectedPrev) {
+          errors.push({
+            index: i,
+            error: `Prev-link mismatch: expected ${expectedPrev}, got ${record.prev}`,
+          });
+        }
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Validates that a record's signature envelope is structurally complete.
+   *
+   * Checks for presence of `alg` and `sig` fields. Does NOT perform
+   * cryptographic verification — that requires the issuer's public key
+   * from the trust state, which is resolved during evaluation.
+   *
+   * @param {Record<string, *>} record
+   * @throws {TrustError} if signature envelope is missing or malformed
+   * @private
+   */
+  _verifySignatureEnvelope(record) {
+    if (!record.signature || !record.signature.sig || !record.signature.alg) {
+      throw new TrustError(
+        'Trust record missing or malformed signature',
+        { code: 'E_TRUST_SIGNATURE_MISSING' },
+      );
+    }
+  }
+
+  /**
+   * Reads the tip commit SHA and its recordId.
+   * @param {string} ref
+   * @returns {Promise<{tipSha: string|null, recordId: string|null}>}
+   * @private
+   */
+  async _readTip(ref) {
+    let tipSha;
+    try {
+      tipSha = await this._persistence.readRef(ref);
+    } catch {
+      return { tipSha: null, recordId: null };
+    }
+    if (!tipSha) {
+      return { tipSha: null, recordId: null };
+    }
+
+    const treeOid = await this._persistence.getCommitTree(tipSha);
+    const entries = await this._persistence.readTreeOids(treeOid);
+    const blobOid = entries['record.cbor'];
+    if (!blobOid) {
+      return { tipSha, recordId: null };
+    }
+
+    const record = this._codec.decode(await this._persistence.readBlob(blobOid));
+    return { tipSha, recordId: record.recordId ?? null };
+  }
+
+  /**
+   * Persists a trust record as a Git commit.
+   * @param {string} ref
+   * @param {Record<string, *>} record
+   * @param {string|null} parentSha - Resolved tip SHA (null for genesis)
+   * @returns {Promise<string>} commit SHA
+   * @private
+   */
+  async _persistRecord(ref, record, parentSha) {
+    // Encode record as CBOR blob
+    const encoded = this._codec.encode(record);
+    const blobOid = await this._persistence.writeBlob(encoded);
+
+    // Create tree with single entry
+    const treeOid = await this._persistence.writeTree({ 'record.cbor': blobOid });
+
+    const parents = parentSha ? [parentSha] : [];
+    const message = `trust: ${record.recordType} ${record.recordId.slice(0, 12)}`;
+
+    const commitSha = await this._persistence.createCommit({
+      tree: treeOid,
+      parents,
+      message,
+    });
+
+    // CAS update ref — fails atomically if a concurrent append changed the tip
+    await this._persistence.compareAndSwapRef(ref, commitSha, parentSha);
+
+    return commitSha;
+  }
+}

package/src/domain/trust/TrustStateBuilder.js

@@ -0,0 +1,209 @@
+/**
+ * Trust V1 state builder.
+ *
+ * Pure function that walks an ordered sequence of trust records and
+ * accumulates the trust state: active/revoked keys and writer bindings.
+ *
+ * No I/O, no side effects, no infrastructure imports.
+ *
+ * @module domain/trust/TrustStateBuilder
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 11
+ */
+
+import { TrustRecordSchema } from './schemas.js';
+
+/**
+ * @typedef {Object} TrustState
+ * @property {Map<string, {publicKey: string, addedAt: string}>} activeKeys - keyId → key info
+ * @property {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
+ * @property {Map<string, {keyId: string, boundAt: string}>} writerBindings - "writerId\0keyId" → binding
+ * @property {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} revokedBindings
+ * @property {Array<{recordId: string, error: string}>} errors
+ * @property {number} recordsProcessed - Total number of records fed to the builder
+ */
+
+/**
+ * Builds trust state from an ordered sequence of trust records.
+ *
+ * Records MUST be in chain order (oldest first). The builder enforces:
+ * - Monotonic revocation: once a key is revoked, it cannot be re-added
+ * - Binding validity: WRITER_BIND_ADD requires the referenced key to be active
+ * - Schema validation: each record is validated against TrustRecordSchema
+ *
+ * @param {Array<Record<string, *>>} records - Trust records in chain order
+ * @returns {TrustState} Frozen trust state
+ */
+export function buildState(records) {
+  /** @type {Map<string, {publicKey: string, addedAt: string}>} */
+  const activeKeys = new Map();
+  /** @type {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} */
+  const revokedKeys = new Map();
+  /** @type {Map<string, {keyId: string, boundAt: string}>} */
+  const writerBindings = new Map();
+  /** @type {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} */
+  const revokedBindings = new Map();
+  /** @type {Array<{recordId: string, error: string}>} */
+  const errors = [];
+
+  for (const record of records) {
+    const parsed = TrustRecordSchema.safeParse(record);
+    if (!parsed.success) {
+      errors.push({
+        recordId: record.recordId ?? '(unknown)',
+        error: `Schema validation failed: ${parsed.error.message}`,
+      });
+      continue;
+    }
+
+    const rec = parsed.data;
+    processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBindings, errors);
+  }
+
+  return Object.freeze({ activeKeys, revokedKeys, writerBindings, revokedBindings, errors, recordsProcessed: records.length });
+}
+
+/**
+ * @param {*} rec
+ * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
+ * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
+ * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
+ * @param {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} revokedBindings
+ * @param {Array<{recordId: string, error: string}>} errors
+ */
+function processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBindings, errors) {
+  switch (rec.recordType) {
+    case 'KEY_ADD':
+      handleKeyAdd(rec, activeKeys, revokedKeys, errors);
+      break;
+    case 'KEY_REVOKE':
+      handleKeyRevoke(rec, activeKeys, revokedKeys, errors);
+      break;
+    case 'WRITER_BIND_ADD':
+      handleBindAdd(rec, activeKeys, revokedKeys, writerBindings, errors);
+      break;
+    case 'WRITER_BIND_REVOKE':
+      handleBindRevoke(rec, writerBindings, revokedBindings, errors);
+      break;
+    default:
+      errors.push({ recordId: rec.recordId, error: `Unknown recordType: ${rec.recordType}` });
+  }
+}
+
+/**
+ * @param {*} rec
+ * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
+ * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
+ * @param {Array<{recordId: string, error: string}>} errors
+ */
+function handleKeyAdd(rec, activeKeys, revokedKeys, errors) {
+  const { keyId, publicKey } = rec.subject;
+
+  if (revokedKeys.has(keyId)) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Cannot re-add revoked key: ${keyId}`,
+    });
+    return;
+  }
+
+  if (activeKeys.has(keyId)) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Duplicate KEY_ADD for already-active key: ${keyId}`,
+    });
+    return;
+  }
+
+  activeKeys.set(keyId, { publicKey, addedAt: rec.issuedAt });
+}
+
+/**
+ * @param {*} rec
+ * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
+ * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
+ * @param {Array<{recordId: string, error: string}>} errors
+ */
+function handleKeyRevoke(rec, activeKeys, revokedKeys, errors) {
+  const { keyId, reasonCode } = rec.subject;
+
+  if (revokedKeys.has(keyId)) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Key already revoked: ${keyId}`,
+    });
+    return;
+  }
+
+  const keyInfo = activeKeys.get(keyId);
+  if (!keyInfo) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Cannot revoke unknown key: ${keyId}`,
+    });
+    return;
+  }
+
+  activeKeys.delete(keyId);
+  revokedKeys.set(keyId, {
+    publicKey: keyInfo.publicKey,
+    revokedAt: rec.issuedAt,
+    reasonCode,
+  });
+}
+
+/**
+ * @param {*} rec
+ * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
+ * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
+ * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
+ * @param {Array<{recordId: string, error: string}>} errors
+ */
+function handleBindAdd(rec, activeKeys, revokedKeys, writerBindings, errors) {
+  const { writerId, keyId } = rec.subject;
+  const bindingKey = `${writerId}\0${keyId}`;
+
+  if (revokedKeys.has(keyId)) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Cannot bind writer to revoked key: ${keyId}`,
+    });
+    return;
+  }
+
+  if (!activeKeys.has(keyId)) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Cannot bind writer to unknown key: ${keyId}`,
+    });
+    return;
+  }
+
+  writerBindings.set(bindingKey, { keyId, boundAt: rec.issuedAt });
+}
+
+/**
+ * @param {*} rec
+ * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
+ * @param {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} revokedBindings
+ * @param {Array<{recordId: string, error: string}>} errors
+ */
+function handleBindRevoke(rec, writerBindings, revokedBindings, errors) {
+  const { writerId, keyId, reasonCode } = rec.subject;
+  const bindingKey = `${writerId}\0${keyId}`;
+
+  const binding = writerBindings.get(bindingKey);
+  if (!binding) {
+    errors.push({
+      recordId: rec.recordId,
+      error: `Cannot revoke non-existent binding: writer=${writerId} key=${keyId}`,
+    });
+    return;
+  }
+
+  writerBindings.delete(bindingKey);
+  revokedBindings.set(bindingKey, {
+    keyId,
+    revokedAt: rec.issuedAt,
+    reasonCode,
+  });
+}

package/src/domain/trust/canonical.js

@@ -0,0 +1,68 @@
+/**
+ * Trust V1 canonical serialization helpers.
+ *
+ * Domain separation constants and unsigned record extraction functions
+ * for recordId computation and signature payloads.
+ *
+ * @module domain/trust/canonical
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 6
+ */
+
+import { canonicalStringify } from '../utils/canonicalStringify.js';
+
+// ── Domain separation prefixes ──────────────────────────────────────────
+
+/** Domain prefix for recordId computation. */
+export const TRUST_RECORD_ID_DOMAIN = 'git-warp:trust-record:v1\0';
+
+/** Domain prefix for signature payload. */
+export const TRUST_SIGN_DOMAIN = 'git-warp:trust-sign:v1\0';
+
+// ── Unsigned record helpers ─────────────────────────────────────────────
+
+/**
+ * Returns the record payload used for recordId computation.
+ * Strips `recordId` and `signature` — these are derived, not inputs.
+ *
+ * @param {Record<string, *>} record
+ * @returns {Record<string, *>}
+ */
+export function unsignedRecordForId(record) {
+  const out = { ...record };
+  delete out.recordId;
+  delete out.signature;
+  return out;
+}
+
+/**
+ * Returns the record payload used for signature computation.
+ * Strips `signature` only — `recordId` is included in signed payload.
+ *
+ * @param {Record<string, *>} record
+ * @returns {Record<string, *>}
+ */
+export function unsignedRecordForSignature(record) {
+  const out = { ...record };
+  delete out.signature;
+  return out;
+}
+
+/**
+ * Computes the canonical string for recordId hashing.
+ *
+ * @param {Record<string, *>} record - Full record (recordId and signature will be stripped)
+ * @returns {string} Domain-separated canonical JSON string
+ */
+export function recordIdPayload(record) {
+  return TRUST_RECORD_ID_DOMAIN + canonicalStringify(unsignedRecordForId(record));
+}
+
+/**
+ * Computes the canonical string for signature verification.
+ *
+ * @param {Record<string, *>} record - Full record (signature will be stripped)
+ * @returns {string} Domain-separated canonical JSON string
+ */
+export function signaturePayload(record) {
+  return TRUST_SIGN_DOMAIN + canonicalStringify(unsignedRecordForSignature(record));
+}

package/src/domain/trust/reasonCodes.js

@@ -0,0 +1,64 @@
+/**
+ * Trust V1 reason code registry.
+ *
+ * Every trust explanation MUST include a reasonCode from this registry.
+ * Codes are stable — renaming or removing a code is a breaking change
+ * that requires a spec version bump.
+ *
+ * @module domain/trust/reasonCodes
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 15
+ */
+
+/** @type {Readonly<Record<string, string>>} */
+export const TRUST_REASON_CODES = Object.freeze({
+  // ── Positive ────────────────────────────────────────────────────────────
+  /** Writer has at least one active binding to an active key. */
+  WRITER_BOUND_TO_ACTIVE_KEY: 'WRITER_BOUND_TO_ACTIVE_KEY',
+
+  // ── Negative ────────────────────────────────────────────────────────────
+  /** Writer has no active bindings. */
+  WRITER_HAS_NO_ACTIVE_BINDING: 'WRITER_HAS_NO_ACTIVE_BINDING',
+  /** Writer's binding references a revoked key. */
+  WRITER_BOUND_KEY_REVOKED: 'WRITER_BOUND_KEY_REVOKED',
+  /** Writer's binding has been explicitly revoked. */
+  BINDING_REVOKED: 'BINDING_REVOKED',
+  /** Binding references a keyId not found in record log. */
+  KEY_UNKNOWN: 'KEY_UNKNOWN',
+
+  // ── System ──────────────────────────────────────────────────────────────
+  /** Trust record ref does not exist. */
+  TRUST_REF_MISSING: 'TRUST_REF_MISSING',
+  /** Pinned commit does not exist or is invalid. */
+  TRUST_PIN_INVALID: 'TRUST_PIN_INVALID',
+  /** Record fails schema validation. */
+  TRUST_RECORD_SCHEMA_INVALID: 'TRUST_RECORD_SCHEMA_INVALID',
+  /** Record signature verification failed. */
+  TRUST_SIGNATURE_INVALID: 'TRUST_SIGNATURE_INVALID',
+  /** Record chain linking is broken. */
+  TRUST_RECORD_CHAIN_INVALID: 'TRUST_RECORD_CHAIN_INVALID',
+  /** Policy value is unknown or unsupported. */
+  TRUST_POLICY_INVALID: 'TRUST_POLICY_INVALID',
+});
+
+/** @type {ReadonlySet<string>} */
+export const POSITIVE_CODES = Object.freeze(new Set([
+  TRUST_REASON_CODES.WRITER_BOUND_TO_ACTIVE_KEY,
+]));
+
+/** @type {ReadonlySet<string>} */
+export const NEGATIVE_CODES = Object.freeze(new Set([
+  TRUST_REASON_CODES.WRITER_HAS_NO_ACTIVE_BINDING,
+  TRUST_REASON_CODES.WRITER_BOUND_KEY_REVOKED,
+  TRUST_REASON_CODES.BINDING_REVOKED,
+  TRUST_REASON_CODES.KEY_UNKNOWN,
+]));
+
+/** @type {ReadonlySet<string>} */
+export const SYSTEM_CODES = Object.freeze(new Set([
+  TRUST_REASON_CODES.TRUST_REF_MISSING,
+  TRUST_REASON_CODES.TRUST_PIN_INVALID,
+  TRUST_REASON_CODES.TRUST_RECORD_SCHEMA_INVALID,
+  TRUST_REASON_CODES.TRUST_SIGNATURE_INVALID,
+  TRUST_REASON_CODES.TRUST_RECORD_CHAIN_INVALID,
+  TRUST_REASON_CODES.TRUST_POLICY_INVALID,
+]));