knosky 0.4.1 → 0.6.0

package/core/freshness.mjs

@@ -0,0 +1,194 @@
+// KnoSky ledger-anchored freshness attestation (SAT-444, SAT-474).
+//
+// Closes the clock-skew / key-resurrection gap by basing freshness on the
+// repository's commit count rather than wall-clock time.  A `ledger_seq`
+// is a monotone integer — the number of commits reachable from HEAD —
+// which cannot be fabricated by adjusting the system clock and can only
+// decrease when history is rewritten (the ledger-truncation attack caught
+// by the high-water-mark guard in core/ledger.mjs).
+//
+// SAT-474: validateFreshnessWithHwm() routes through the *persisted*
+// checkAndAdvance() guard (core/ledger.mjs) so that the rollback defence
+// survives process restarts.  validateFreshness() is retained for callers
+// that manage their own in-memory lastSeq (e.g. protocol-spec validation).
+// Pure Node stdlib, ESM — no third-party dependencies.
+
+import { execFileSync } from 'node:child_process';
+import { checkAndAdvance } from './ledger.mjs';
+import { MAX_PLAUSIBLE_LEDGER_SEQ } from './constants.mjs';
+
+// ---------------------------------------------------------------------------
+// extractLedgerSeq — read the ledger_seq stored in a city envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the `ledger_seq` from a city envelope or any artifact that carries
+ * one.  Returns null when absent, not a non-negative integer, or implausibly
+ * large (see MAX_PLAUSIBLE_LEDGER_SEQ).
+ *
+ * @param {object} obj  City envelope or comparable artifact object.
+ * @returns {number|null}
+ */
+export function extractLedgerSeq(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  const seq = obj.ledger_seq;
+  if (typeof seq !== 'number' || !Number.isInteger(seq) || seq < 0) return null;
+  if (seq > MAX_PLAUSIBLE_LEDGER_SEQ) return null;
+  return seq;
+}
+
+// ---------------------------------------------------------------------------
+// computeLedgerSeq — derive a ledger_seq from a git repo on disk
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the ledger_seq for `root` by counting all commits reachable from
+ * HEAD (`git rev-list --count HEAD`).  Returns 0 when git is unavailable or
+ * the directory has no commit history (e.g. a brand-new repo with no commits).
+ *
+ * @param {string} root  Absolute path to the git working tree.
+ * @returns {number}  Non-negative integer commit count.
+ */
+export function computeLedgerSeq(root) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['rev-list', '--count', 'HEAD'],
+      { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    const n = parseInt(out, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+  } catch {
+    // No git / no commits / non-repo directory → 0  (safe: sequence starts fresh)
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// checkHighWaterMark — V13 guard against ledger-truncation attack
+// ---------------------------------------------------------------------------
+
+/**
+ * High-water-mark guard (V13).
+ *
+ * Returns `{ ok: true }` when `newSeq` is strictly greater than `lastSeq`,
+ * meaning the city has advanced — its ledger has grown (or this is the first
+ * load, indicated by `lastSeq === null`).
+ *
+ * Returns `{ ok: false, reason }` when `newSeq` is ≤ `lastSeq`, which means
+ * the ledger has been truncated or replayed — a potential key-resurrection or
+ * rollback attack.  Callers MUST treat stale/equal as suspicious.
+ *
+ * @param {number|null} lastSeq  Previously accepted ledger_seq, or null on
+ *                               first load (unconditionally accepted).
+ * @param {number|null} newSeq   Ledger_seq from the incoming artifact, or
+ *                               null when absent (treated as 0 — conservative).
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function checkHighWaterMark(lastSeq, newSeq) {
+  // Treat missing seq as 0 — conservative: an artifact with no ledger anchoring
+  // is as trustworthy as a brand-new repo.
+  const effective = (typeof newSeq === 'number' && Number.isInteger(newSeq) && newSeq >= 0)
+    ? newSeq
+    : 0;
+
+  // First load: no last seq to compare against — unconditionally accept.
+  if (lastSeq === null || lastSeq === undefined) {
+    return { ok: true };
+  }
+
+  if (typeof lastSeq !== 'number' || !Number.isInteger(lastSeq) || lastSeq < 0) {
+    // Corrupt lastSeq — treat it as 0 (reset the watermark)
+    return { ok: true };
+  }
+
+  if (effective > lastSeq) {
+    return { ok: true };
+  }
+
+  // equal: rolled back to same point (replay) or no new commits
+  // less: ledger truncation — history was rewritten
+  const direction = effective < lastSeq ? 'ledger truncated' : 'ledger not advanced';
+  return {
+    ok: false,
+    reason:
+      direction +
+      ': incoming ledger_seq ' + effective +
+      ' is not greater than last accepted ' + lastSeq +
+      ' — possible rollback or key-resurrection attack',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateFreshness — full attestation check for an incoming artifact
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the freshness of an incoming artifact against an optional stored
+ * high-water mark.
+ *
+ * Combines:
+ *  (1) structural check: `ledger_seq` is present and a non-negative integer
+ *  (2) V13 high-water-mark guard: `ledger_seq` must exceed the last accepted
+ *      value (pass `null` on first load to skip this check)
+ *
+ * @param {object}      artifact  City envelope or protocol artifact.
+ * @param {number|null} lastSeq   Last accepted ledger_seq (null = first load).
+ * @returns {{ ok: boolean, ledger_seq: number|null, errors: string[] }}
+ */
+export function validateFreshness(artifact, lastSeq = null) {
+  const errors = [];
+  const seq = extractLedgerSeq(artifact);
+
+  if (seq === null) {
+    errors.push('ledger_seq is missing or not a non-negative integer');
+  }
+
+  const hwm = checkHighWaterMark(lastSeq, seq);
+  if (!hwm.ok) {
+    errors.push(hwm.reason);
+  }
+
+  return { ok: errors.length === 0, ledger_seq: seq, errors };
+}
+
+// ---------------------------------------------------------------------------
+// validateFreshnessWithHwm — persisted-HWM variant (SAT-474)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate freshness through the **persisted** high-water-mark guard
+ * (`core/ledger.mjs` `checkAndAdvance`).
+ *
+ * Unlike `validateFreshness`, this function reads and updates the HWM from
+ * `hwmPath` on disk, so the rollback defence is durable across process
+ * restarts.  Callers that previously maintained an in-memory `lastSeq` and
+ * passed it to `validateFreshness` should migrate to this function and a
+ * stable `hwmPath` in their data directory.
+ *
+ * Semantics of the persisted guard (from `checkAndAdvance`):
+ *   - seq STRICTLY LESS than HWM → rejected (anti-truncation guard)
+ *   - seq EQUAL to HWM           → accepted (idempotent replay)
+ *   - seq GREATER than HWM       → accepted and HWM advanced
+ *
+ * @param {object} artifact  City envelope or protocol artifact.
+ * @param {string} hwmPath   Path to the independently-persisted HWM file.
+ * @returns {{ ok: boolean, ledger_seq: number|null, errors: string[] }}
+ */
+export function validateFreshnessWithHwm(artifact, hwmPath) {
+  const errors = [];
+  const seq = extractLedgerSeq(artifact);
+
+  if (seq === null) {
+    errors.push('ledger_seq is missing or not a non-negative integer');
+    // Cannot call checkAndAdvance with a null seq — return early.
+    return { ok: false, ledger_seq: null, errors };
+  }
+
+  const result = checkAndAdvance(seq, hwmPath);
+  if (!result.ok) {
+    errors.push(result.error);
+  }
+
+  return { ok: errors.length === 0, ledger_seq: seq, errors };
+}

package/core/fs-indexer.mjs

@@ -7,11 +7,15 @@ import { execSync } from 'node:child_process';
 import { SCHEMA_VERSION, IGNORE_DEFAULTS, deriveCategories, serializeNode, validateCity, setRedactTerms, findSecrets } from './contract.mjs';
 import { extractImportSpecifiers, resolveSpec } from './edges.mjs';
 import { gitChurn } from './churn.mjs';
+import { computeLedgerSeq } from './freshness.mjs';
 
 const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
 const ROOT = args.root && path.resolve(args.root);
 const OUT = args.out || null;
-const MAX = parseInt(args.max || '6000', 10);
+// Validate --max: a non-numeric/zero/negative value must NOT silently disable the
+// cap (NaN comparisons are always false, so `scanned > MAX` would never trip) —
+// that's a resource-exhaustion opening on a hostile/malformed CI invocation.
+const MAX = (() => { const n = parseInt(args.max || '6000', 10); return (Number.isFinite(n) && n > 0) ? n : 6000; })();
 const SHARE_SAFE = process.argv.includes('--share-safe');
 const INCLUDE_ABS = process.argv.includes('--include-absolute-root');
 const ALLOW_LEAKS = process.argv.includes('--allow-leaks');
@@ -160,10 +164,15 @@ const preList = preHits.map(h => h[0] + ':' + h[1]).join(', ');
 const nodes = raw.map(serializeNode);
 const catIds = [...new Set(nodes.map(n => n.category))].sort();
 const categories = deriveCategories(catIds);
+// Ledger-anchored freshness (SAT-444): monotone commit count, used as a
+// replay-resistant sequence number.  Consumers compare against the last
+// accepted ledger_seq (V13 high-water-mark guard) to detect rollbacks.
+const ledger_seq = computeLedgerSeq(ROOT);
 const city = {
   schema_version: SCHEMA_VERSION,
   generated_at: new Date().toISOString(),
   source: { kind: 'fs', ref: INCLUDE_ABS ? ROOT : path.basename(ROOT), rev: REV },
+  ledger_seq,
   categories, node_count: nodes.length, nodes,
 };
 

package/core/key-store.mjs

@@ -0,0 +1,348 @@
+// KnoSky signing-key rotation/revocation lifecycle (SAT-446 / Hardening Addendum 2).
+// In-process HMAC-SHA256 key store — local-first, no external KMS, no telemetry.
+// Callers own persistence; this module is pure in-memory state + crypto.
+// Pure Node stdlib, ESM — no third-party dependencies.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Generate a random 16-byte key id as a 32-char lowercase hex string. */
+function newKeyId() {
+  return randomBytes(16).toString('hex');
+}
+
+/**
+ * Compute HMAC-SHA256 over a canonical JSON serialisation of `payload`.
+ * "Canonical" = top-level keys sorted alphabetically before serialisation.
+ * Returns a lowercase 64-char hex string.
+ *
+ * @param {Buffer} keyBuf
+ * @param {object} payload
+ * @returns {string}
+ */
+function hmacPayload(keyBuf, payload) {
+  const sorted = Object.fromEntries(
+    Object.keys(payload).sort().map(k => [k, payload[k]]),
+  );
+  return createHmac('sha256', keyBuf).update(JSON.stringify(sorted)).digest('hex');
+}
+
+/**
+ * Strip `key_id` and `sig` from a manifest object to get the signing payload.
+ * These two fields are metadata added *after* signing and must not be part
+ * of the signed content.
+ *
+ * @param {object} manifest
+ * @returns {object}
+ */
+function signingPayload(manifest) {
+  const out = {};
+  for (const [k, v] of Object.entries(manifest)) {
+    if (k === 'key_id' || k === 'sig') continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// createKeyStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new in-memory key store with a single initial active key.
+ *
+ * The returned object has the following shape:
+ * ```
+ * {
+ *   keys:        Map<key_id, KeyEntry>,
+ *   activeKeyId: string | null,
+ * }
+ * ```
+ *
+ * where each `KeyEntry` is:
+ * ```
+ * { key_id: string, status: 'active'|'rotated'|'revoked', created_at: string, raw: Buffer }
+ * ```
+ *
+ * @returns {{ keys: Map<string, object>, activeKeyId: string }}
+ */
+export function createKeyStore() {
+  const ks = { keys: new Map(), activeKeyId: null };
+  _issueKey(ks);
+  return ks;
+}
+
+/**
+ * @internal
+ * Issue a new active key.  Demotes the current active key to `'rotated'` if
+ * one exists (rotated keys remain verifiable; only revoked ones are rejected).
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @returns {string}  The newly-issued key_id.
+ */
+function _issueKey(ks) {
+  // Demote any current active key → 'rotated' (still usable for verification).
+  if (ks.activeKeyId !== null) {
+    const prev = ks.keys.get(ks.activeKeyId);
+    if (prev && prev.status === 'active') prev.status = 'rotated';
+  }
+  const key_id = newKeyId();
+  ks.keys.set(key_id, {
+    key_id,
+    status: 'active',
+    created_at: new Date().toISOString(),
+    raw: randomBytes(32),
+  });
+  ks.activeKeyId = key_id;
+  return key_id;
+}
+
+// ---------------------------------------------------------------------------
+// rotateKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Rotate the signing key: demote the current active key to `'rotated'` and
+ * issue a fresh one.
+ *
+ * Manifests already signed with the old (now `'rotated'`) key remain
+ * verifiable.  Only `'revoked'` keys are rejected by {@link verifyManifest}.
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @returns {string}  The new active key_id.
+ */
+export function rotateKey(ks) {
+  return _issueKey(ks);
+}
+
+// ---------------------------------------------------------------------------
+// revokeKey / makeRevocationApproval
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical payload that approval signers HMAC to authorise a revocation.
+ * Keys are sorted alphabetically (matching {@link hmacPayload}).
+ *
+ * @param {string} targetKeyId
+ * @returns {{ action: string, target_key_id: string }}
+ */
+function revocationPayload(targetKeyId) {
+  // Return in key-sorted order so hmacPayload produces a deterministic digest.
+  return { action: 'revoke_key', target_key_id: targetKeyId };
+}
+
+/**
+ * Produce a revocation-approval token signed by `signingKeyId`.
+ *
+ * The token is an `{ key_id, sig }` object that can be collected from multiple
+ * non-revoked keys and passed as the `approvals` array to {@link revokeKey}
+ * to satisfy the quorum requirement.
+ *
+ * Throws if `signingKeyId` is unknown, already revoked, or equal to
+ * `targetKeyId` (a key may not approve its own revocation).
+ *
+ * @param {{ keys: Map<string,object> }} ks
+ * @param {string} signingKeyId
+ * @param {string} targetKeyId
+ * @returns {{ key_id: string, sig: string }}
+ */
+export function makeRevocationApproval(ks, signingKeyId, targetKeyId) {
+  if (signingKeyId === targetKeyId) {
+    throw new Error('makeRevocationApproval: signing key and target key must differ');
+  }
+  const entry = ks.keys.get(signingKeyId);
+  if (!entry) {
+    throw new Error(`makeRevocationApproval: unknown key_id ${JSON.stringify(signingKeyId)}`);
+  }
+  if (entry.status === 'revoked') {
+    throw new Error(`makeRevocationApproval: signing key ${JSON.stringify(signingKeyId)} is revoked`);
+  }
+  const sig = hmacPayload(entry.raw, revocationPayload(targetKeyId));
+  return { key_id: signingKeyId, sig };
+}
+
+/**
+ * Revoke a key by id.
+ *
+ * After revocation {@link verifyManifest} rejects any manifest that was
+ * signed with the revoked key.  Revocation is permanent within a key-store
+ * instance.  The operation is idempotent — revoking an already-revoked key
+ * is a no-op.
+ *
+ * If the revoked key was the active signing key, `activeKeyId` is cleared to
+ * `null`; callers must {@link rotateKey} to obtain a new active key.
+ *
+ * **Authorization / quorum gate (SAT-472)**
+ *
+ * Let `M` be the number of non-revoked keys other than `keyId`.  The
+ * required quorum is `Math.floor(M / 2) + 1` (strict majority of peers).
+ * When `M === 0` (the target is the only remaining key) no approvals are
+ * needed.  Each approval in the `approvals` array must be a valid
+ * {@link makeRevocationApproval} token signed by a distinct, non-revoked key
+ * that is not `keyId` itself.
+ *
+ * This ensures a single compromised key cannot unilaterally revoke all
+ * others: it can only contribute one approval, which is always less than
+ * the strict majority needed when `M >= 2`.
+ *
+ * Throws if `keyId` is not present in the store or if the quorum is not met.
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {string} keyId
+ * @param {{ key_id: string, sig: string }[]} [approvals=[]]
+ */
+export function revokeKey(ks, keyId, approvals = []) {
+  if (!ks.keys.has(keyId)) {
+    throw new Error(`revokeKey: unknown key_id ${JSON.stringify(keyId)}`);
+  }
+  const entry = ks.keys.get(keyId);
+  if (entry.status === 'revoked') return; // idempotent
+
+  // Count non-revoked peer keys (all keys except the revocation target).
+  const peers = [...ks.keys.values()].filter(
+    e => e.key_id !== keyId && e.status !== 'revoked',
+  );
+  const required = peers.length > 0 ? Math.floor(peers.length / 2) + 1 : 0;
+
+  if (required > 0) {
+    // Validate each approval token over the canonical revocation payload.
+    const payload = revocationPayload(keyId);
+    const seen = new Set();
+    let valid = 0;
+
+    for (const approval of approvals) {
+      const { key_id: aKeyId, sig } = approval ?? {};
+      if (!aKeyId || !sig) continue;
+      if (aKeyId === keyId) continue;      // target cannot self-approve
+      if (seen.has(aKeyId)) continue;      // deduplicate per signer
+
+      const aEntry = ks.keys.get(aKeyId);
+      if (!aEntry || aEntry.status === 'revoked') continue;
+
+      const expected = hmacPayload(aEntry.raw, payload);
+      if (typeof sig !== 'string' || sig.length !== expected.length) continue;
+
+      let match = false;
+      try {
+        match = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
+      } catch { match = false; }
+
+      if (match) {
+        seen.add(aKeyId);
+        valid++;
+      }
+    }
+
+    if (valid < required) {
+      throw new Error(
+        `revokeKey: quorum not met — ${required} approval(s) required from peer keys, got ${valid}`,
+      );
+    }
+  }
+
+  entry.status = 'revoked';
+  // If the active key was just revoked, clear the active pointer.
+  if (ks.activeKeyId === keyId) ks.activeKeyId = null;
+}
+
+// ---------------------------------------------------------------------------
+// signManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a manifest with the store's current active key.
+ *
+ * Returns a shallow copy of `manifest` with two new fields appended:
+ * - `key_id` — identifies the signing key for later verification.
+ * - `sig`    — lowercase hex HMAC-SHA256 over the canonical signing payload
+ *              (all manifest fields except `key_id` and `sig` themselves,
+ *              with top-level keys sorted alphabetically).
+ *
+ * Throws if there is no active key in the store (e.g. after revoking the
+ * active key without rotating first).
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {object} manifest   Typically the result of {@link makeIntentManifest}.
+ * @returns {object}          Manifest copy decorated with `key_id` and `sig`.
+ */
+export function signManifest(ks, manifest) {
+  const entry = ks.activeKeyId != null ? ks.keys.get(ks.activeKeyId) : null;
+  if (!entry || entry.status !== 'active') {
+    throw new Error('signManifest: no active key in store — rotate to obtain one');
+  }
+  const payload = signingPayload(manifest);
+  const sig = hmacPayload(entry.raw, payload);
+  return { ...manifest, key_id: entry.key_id, sig };
+}
+
+// ---------------------------------------------------------------------------
+// verifyManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a signed manifest.
+ *
+ * Returns `{ ok: true }` when the signature is valid and the signing key is
+ * present and not revoked.  Otherwise returns `{ ok: false, reason }`.
+ *
+ * Never throws on malformed input — treats it as a verification failure.
+ *
+ * | `reason`          | Meaning                                             |
+ * |-------------------|-----------------------------------------------------|
+ * | `'missing_key_id'`| `key_id` field absent from the manifest.            |
+ * | `'unknown_key'`   | `key_id` is not registered in this store.           |
+ * | `'key_revoked'`   | The key exists but has been revoked.                |
+ * | `'bad_signature'` | HMAC did not match — data was tampered or wrong key.|
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {object} signedManifest
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function verifyManifest(ks, signedManifest) {
+  const { key_id, sig } = signedManifest;
+
+  if (!key_id) return { ok: false, reason: 'missing_key_id' };
+
+  const entry = ks.keys.get(key_id);
+  if (!entry) return { ok: false, reason: 'unknown_key' };
+  if (entry.status === 'revoked') return { ok: false, reason: 'key_revoked' };
+
+  const payload = signingPayload(signedManifest);
+  const expected = hmacPayload(entry.raw, payload);
+
+  // Use timingSafeEqual to prevent timing-side-channel leaks.
+  // Both buffers must have the same length; a length mismatch is a sig failure.
+  const eBuf = Buffer.from(expected, 'hex');
+  if (typeof sig !== 'string' || sig.length !== expected.length) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  const aBuf = Buffer.from(sig, 'hex');
+  let match;
+  try {
+    match = timingSafeEqual(eBuf, aBuf);
+  } catch {
+    match = false;
+  }
+  return match ? { ok: true } : { ok: false, reason: 'bad_signature' };
+}
+
+// ---------------------------------------------------------------------------
+// getKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the metadata for a registered key (without the raw key material).
+ * Returns `null` if `keyId` is not in the store.
+ *
+ * @param {{ keys: Map<string,object> }} ks
+ * @param {string} keyId
+ * @returns {{ key_id: string, status: string, created_at: string } | null}
+ */
+export function getKey(ks, keyId) {
+  const entry = ks.keys.get(keyId);
+  if (!entry) return null;
+  // Never expose the raw key material to callers.
+  return { key_id: entry.key_id, status: entry.status, created_at: entry.created_at };
+}