@ijfw/memory-server 1.4.4 → 1.5.0

package/src/lib/playwright-baseline.js

@@ -0,0 +1,205 @@
+// playwright-baseline.js -- v1.5.0 audit-MED-design-#6.
+//
+// Visual-regression baseline for the ijfw-ui-auditor pipeline.  Stores
+// reference screenshots under `.planning/visual-baseline/<phase>/<surface>.png`
+// and compares subsequent snapshots against them.
+//
+// Playwright is treated as an optional peer.  IJFW core stays zero-dep, so this
+// file works in three modes:
+//
+//   1. capture(): caller passes a Buffer (PNG bytes).  We just write it to disk
+//      with atomic rename.  No Playwright needed.
+//
+//   2. compare(): caller passes the new Buffer (or path).  We byte-diff against
+//      baseline.  Returns {diffPercent: 0|100, status: 'identical'|'changed'|...}
+//      when no perceptual diff peer is installed.  If `opts.pixelmatch` is
+//      injected (callers can require pixelmatch + pngjs themselves), we use the
+//      real per-pixel ratio.
+//
+//   3. createBaseline()/compareToBaseline(): high-level helpers used by the
+//      auditor agent.  Auto-derive the baseline path from {phase, surface}.
+//
+// Graceful no-op without Playwright: createBaseline() simply records "no
+// snapshot supplied -- baseline deferred"; compareToBaseline() returns
+// {pass: null, reason: 'no-snapshot'} so the auditor can mark FLAG instead of
+// hard-failing.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+
+const DEFAULT_BASELINE_ROOT = '.planning/visual-baseline';
+const DEFAULT_DIFF_THRESHOLD = 1.0; // % of differing pixels above which fail
+
+/**
+ * Resolve the baseline path for a (phase, surface) pair.
+ *
+ * @param {object} opts
+ * @param {string} opts.phase
+ * @param {string} opts.surface
+ * @param {string} [opts.root]          default .planning/visual-baseline
+ * @param {string} [opts.projectRoot]   default cwd
+ */
+export function baselinePath(opts) {
+  const phase = sanitizeSegment(opts.phase || 'unspecified');
+  const surface = sanitizeSegment(opts.surface || 'default');
+  const root = opts.root || DEFAULT_BASELINE_ROOT;
+  const projectRoot = opts.projectRoot || process.cwd();
+  return join(projectRoot, root, phase, `${surface}.png`);
+}
+
+/**
+ * Write a baseline screenshot.  Caller is responsible for capturing the bytes
+ * (e.g. via `await page.screenshot()` in Playwright).
+ *
+ * @param {object} opts
+ * @param {Buffer|null} opts.png        PNG bytes; null = "Playwright unavailable, skip"
+ * @param {string} opts.phase
+ * @param {string} opts.surface
+ * @param {string} [opts.root]
+ * @param {string} [opts.projectRoot]
+ * @returns {{ok: boolean, path: string|null, reason: string}}
+ */
+export function createBaseline(opts) {
+  const target = baselinePath(opts);
+  if (!opts.png || !(opts.png instanceof Uint8Array)) {
+    return { ok: false, path: target, reason: 'no-snapshot' };
+  }
+  try {
+    if (!existsSync(dirname(target))) mkdirSync(dirname(target), { recursive: true, mode: 0o755 });
+    // Binary-safe atomic write: tmp file + rename.  We can't use writeAtomic
+    // from lib/atomic-io.js because it JSON-stringifies non-string payloads.
+    const tmp = `${target}.tmp.${randomBytes(6).toString('hex')}`;
+    try {
+      writeFileSync(tmp, opts.png, { mode: 0o644 });
+      renameSync(tmp, target);
+    } catch (e) {
+      try { unlinkSync(tmp); } catch { /* */ }
+      throw e;
+    }
+    return { ok: true, path: target, reason: 'baseline-written' };
+  } catch (e) {
+    return { ok: false, path: target, reason: `write-failed: ${e.code || e.message}` };
+  }
+}
+
+/**
+ * Compare a candidate PNG against the stored baseline.
+ *
+ * @param {object} opts
+ * @param {Buffer|null} opts.png            Candidate bytes.
+ * @param {string} opts.phase
+ * @param {string} opts.surface
+ * @param {string} [opts.root]
+ * @param {string} [opts.projectRoot]
+ * @param {number} [opts.threshold]         Allowed diff %; default 1.0.
+ * @param {Function} [opts.pixelmatch]      Optional injected pixelmatch fn.
+ * @param {Function} [opts.pngParser]       Optional injected PNG parser (e.g. require('pngjs').PNG.sync.read)
+ * @returns {{pass: boolean|null, diffPercent: number|null, baselinePath: string, reason: string}}
+ */
+export function compareToBaseline(opts) {
+  const baseline = baselinePath(opts);
+  const threshold = typeof opts.threshold === 'number' ? opts.threshold : DEFAULT_DIFF_THRESHOLD;
+
+  if (!opts.png || !(opts.png instanceof Uint8Array)) {
+    return { pass: null, diffPercent: null, baselinePath: baseline, reason: 'no-snapshot' };
+  }
+  if (!existsSync(baseline)) {
+    return { pass: null, diffPercent: null, baselinePath: baseline, reason: 'baseline-missing' };
+  }
+
+  let baselineBytes;
+  try {
+    baselineBytes = readFileSync(baseline);
+  } catch (e) {
+    return { pass: null, diffPercent: null, baselinePath: baseline, reason: `baseline-read-failed: ${e.code || e.message}` };
+  }
+
+  // Fast path: byte-identical.
+  if (bytesEqual(baselineBytes, opts.png)) {
+    return { pass: true, diffPercent: 0, baselinePath: baseline, reason: 'identical' };
+  }
+
+  // Hash path: hashes differ → at least 1 byte differs → 100% naive diff.
+  // Unless a real per-pixel differ is injected.
+  if (typeof opts.pixelmatch === 'function' && typeof opts.pngParser === 'function') {
+    try {
+      const baseImg = opts.pngParser(baselineBytes);
+      const candImg = opts.pngParser(opts.png);
+      if (baseImg.width !== candImg.width || baseImg.height !== candImg.height) {
+        return {
+          pass: false,
+          diffPercent: 100,
+          baselinePath: baseline,
+          reason: `dimension-mismatch: ${baseImg.width}x${baseImg.height} vs ${candImg.width}x${candImg.height}`,
+        };
+      }
+      const diffBuffer = new Uint8Array(baseImg.data.length);
+      const diffPixels = opts.pixelmatch(
+        baseImg.data,
+        candImg.data,
+        diffBuffer,
+        baseImg.width,
+        baseImg.height,
+        { threshold: 0.1 },
+      );
+      const total = baseImg.width * baseImg.height;
+      const diffPercent = total === 0 ? 0 : (diffPixels / total) * 100;
+      const pass = diffPercent <= threshold;
+      return {
+        pass,
+        diffPercent: Math.round(diffPercent * 100) / 100,
+        baselinePath: baseline,
+        reason: pass ? 'within-threshold' : `diff ${diffPercent.toFixed(2)}% > threshold ${threshold}%`,
+      };
+    } catch {
+      // Fall through to hash-based fallback.
+    }
+  }
+
+  // Hash fallback.
+  const baseHash = createHash('sha256').update(baselineBytes).digest('hex');
+  const candHash = createHash('sha256').update(opts.png).digest('hex');
+  return {
+    pass: false,
+    diffPercent: 100,
+    baselinePath: baseline,
+    reason: `hash-mismatch (no per-pixel differ installed): ${baseHash.slice(0, 8)} vs ${candHash.slice(0, 8)}`,
+  };
+}
+
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function sanitizeSegment(s) {
+  return String(s)
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unspecified';
+}
+
+/**
+ * Build the auditor prompt fragment for the snapshot capture step.
+ */
+export function playwrightCapturePromptFor(url, phase, surface) {
+  return [
+    'Playwright (optional peer): if installed, run',
+    "  npx playwright screenshot " + JSON.stringify(url) + " /tmp/<surface>.png --full-page",
+    `Then call createBaseline({ phase: '${phase}', surface: '${surface}', png: <bytes> })`,
+    'from mcp-server/src/lib/playwright-baseline.js.',
+    'If Playwright is missing, leave the baseline unset; the auditor will FLAG',
+    'rather than BLOCK on missing-snapshot.',
+  ].join('\n');
+}

package/src/lib/rekor-bridge.js

@@ -0,0 +1,221 @@
+/**
+ * rekor-bridge.js — IJFW v1.5.0 audit-H5.7 Sigstore Rekor transparency log.
+ *
+ * Closes the meta-key-compromise gap from v1.4.1. When the optional
+ * `@sigstore/rekor` peer dep is present (or `IJFW_REKOR_URL` is set for a
+ * self-hosted Rekor instance), the registry signer pushes the
+ * `{payload, signature, publicKey}` triple to Rekor's append-only public
+ * transparency log on sign. Downstream verifiers cross-check the registry's
+ * embedded Rekor entry against the live log on verify — an attacker who
+ * swaps the meta-key cannot backdate a Rekor entry, so the swap is detectable.
+ *
+ * Three principles:
+ *   1. Graceful no-op. If the peer dep is missing, every function returns null
+ *      or false in a way the caller can ignore. Ed25519 signature verification
+ *      remains the primary trust check.
+ *   2. Never throw. submitToRekor and verifyRekorEntry catch all errors,
+ *      emit a stderr advisory, and return null. The caller decides whether
+ *      to proceed.
+ *   3. Backcompat. Unsigned-by-Rekor registries (signed before this lift) still
+ *      verify on the Ed25519 check alone — the cross-check fires only when
+ *      both a `rekor` field is embedded AND a local Rekor client is available.
+ *
+ * Threat model (v1.4.1 → v1.5.0):
+ *   v1.4.1 shipped Ed25519 publisher signing + meta-key rotation. But if an
+ *   attacker compromises the meta-key, downstream installs cannot detect the
+ *   swap — there is no append-only third-party witness. Rekor provides that
+ *   witness: every legitimate registry sign is also pushed to a public log,
+ *   so an attacker who later swaps the meta-key would have to either
+ *   (a) push a tampered registry to Rekor with an entry that doesn't
+ *       match any prior entry — clients see the registry's rekor field
+ *       contains a uuid that resolves to a payload not matching the
+ *       served registry, OR
+ *   (b) try to backdate Rekor entries, which is cryptographically
+ *       impossible (Merkle tree append-only).
+ *
+ * @see https://docs.sigstore.dev/rekor/overview/
+ */
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Client cache: avoid re-importing the peer dep on every call.
+// __setRekorClientForTest replaces the cache for unit tests; resolveClient
+// honors the test override before attempting the real import.
+// ---------------------------------------------------------------------------
+
+let _cachedClient = undefined; // undefined = not-yet-probed, null = unavailable
+let _testClient = null;        // explicit test-only override
+
+/**
+ * Test-only seam: inject a stub Rekor client.
+ *
+ * The stub must implement:
+ *   - createEntry({ payload, signature, publicKey }) → Promise<{ uuid, logIndex, integratedTime }>
+ *   - getEntry({ uuid }) → Promise<{ payloadHash: string }>
+ *
+ * Where `payloadHash` is the sha256-hex of the payload that was originally
+ * submitted to Rekor (so verifyRekorEntry can compare hashes without re-fetching
+ * the entire payload from the log).
+ *
+ * Pass `null` to clear the override and resume normal probe behavior.
+ *
+ * @param {object|null} stub
+ */
+export function __setRekorClientForTest(stub) {
+  _testClient = stub;
+  // Reset cache so the next call re-resolves through the test override.
+  _cachedClient = undefined;
+}
+
+/**
+ * Resolve a Rekor client, preferring (in order):
+ *   1. The explicit test override (`__setRekorClientForTest`).
+ *   2. A dynamic import of `@sigstore/rekor` if it's installed as a peer dep.
+ *   3. null when neither is available.
+ *
+ * The result is cached for the process lifetime (test overrides bust the cache).
+ *
+ * @returns {Promise<object|null>}
+ */
+async function resolveClient() {
+  if (_testClient !== null) return _testClient;
+  if (_cachedClient !== undefined) return _cachedClient;
+  try {
+    const mod = await import('@sigstore/rekor');
+    // Accept either a named `RekorClient` constructor or a default export.
+    const ClientCtor =
+      (mod && (mod.RekorClient || (mod.default && mod.default.RekorClient))) || null;
+    if (typeof ClientCtor !== 'function') {
+      _cachedClient = null;
+      return null;
+    }
+    const baseURL =
+      typeof process.env.IJFW_REKOR_URL === 'string' && process.env.IJFW_REKOR_URL.length > 0
+        ? process.env.IJFW_REKOR_URL
+        : 'https://rekor.sigstore.dev';
+    _cachedClient = new ClientCtor({ baseURL });
+    return _cachedClient;
+  } catch {
+    _cachedClient = null;
+    return null;
+  }
+}
+
+/**
+ * Whether a Rekor client is available. Synchronous in spec but the underlying
+ * resolution is async (dynamic import); we expose an async probe that the
+ * caller awaits. Returns true when either the peer dep is installed or a
+ * test stub has been injected.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function hasRekorClient() {
+  const client = await resolveClient();
+  return client !== null;
+}
+
+/**
+ * Submit a `{payload, signature, publicKey}` triple to the configured Rekor
+ * instance. The payload is the canonical signing bytes that the upstream
+ * Ed25519 signature was computed over (NOT the serialized registry).
+ *
+ * Returns the Rekor entry handle on success, or null on any failure
+ * (no client, network error, malformed response, unexpected exception).
+ * NEVER throws.
+ *
+ * Stderr advisory is emitted on failure so operators see when a sign-time
+ * Rekor anchor was attempted but skipped — important for audit trails when
+ * a registry ships without a `rekor` field.
+ *
+ * @param {object} args
+ * @param {Buffer|string} args.payload canonical bytes of the signed body
+ * @param {string} args.signature Ed25519 signature string (e.g. "ed25519:<b64>")
+ * @param {string} args.publicKey PEM-encoded SPKI public key
+ * @returns {Promise<{ uuid: string, logIndex: number, integratedTime: number } | null>}
+ */
+export async function submitToRekor({ payload, signature, publicKey } = {}) {
+  const client = await resolveClient();
+  if (client === null) return null;
+  if (payload === undefined || signature === undefined || publicKey === undefined) {
+    advise('rekor: submit called without payload/signature/publicKey — skipping');
+    return null;
+  }
+  try {
+    const entry = await client.createEntry({ payload, signature, publicKey });
+    if (
+      !entry ||
+      typeof entry.uuid !== 'string' ||
+      typeof entry.logIndex !== 'number' ||
+      typeof entry.integratedTime !== 'number'
+    ) {
+      advise('rekor: createEntry returned malformed response — skipping anchor');
+      return null;
+    }
+    return {
+      uuid: entry.uuid,
+      logIndex: entry.logIndex,
+      integratedTime: entry.integratedTime,
+    };
+  } catch (err) {
+    advise(`rekor: submit failed — ${err.message || 'unknown error'}`);
+    return null;
+  }
+}
+
+/**
+ * Verify that a Rekor entry's recorded payload hash matches the locally
+ * canonicalized payload. This is the detection mechanism for meta-key
+ * compromise: if an attacker swaps the meta-key but re-uses an old Rekor
+ * uuid, the payload hashes will not match and verification fails.
+ *
+ * Return values:
+ *   - true  — entry exists in Rekor AND its payload hash matches.
+ *   - false — entry exists but payload hash MISMATCH (tamper detected, REJECT).
+ *   - null  — client unavailable OR entry lookup failed. Caller should fall
+ *             back to the Ed25519 check alone (backcompat).
+ *
+ * NEVER throws.
+ *
+ * @param {object} args
+ * @param {string} args.uuid Rekor entry uuid (from registry's embedded rekor field)
+ * @param {Buffer|string} args.payload canonical bytes the entry should attest to
+ * @returns {Promise<boolean|null>}
+ */
+export async function verifyRekorEntry({ uuid, payload } = {}) {
+  const client = await resolveClient();
+  if (client === null) return null;
+  if (typeof uuid !== 'string' || uuid.length === 0 || payload === undefined) {
+    advise('rekor: verify called without uuid/payload — skipping');
+    return null;
+  }
+  let entry;
+  try {
+    entry = await client.getEntry({ uuid });
+  } catch (err) {
+    advise(`rekor: getEntry failed — ${err.message || 'unknown error'}`);
+    return null;
+  }
+  if (!entry || typeof entry.payloadHash !== 'string' || entry.payloadHash.length === 0) {
+    advise('rekor: getEntry returned no payloadHash — cannot cross-check');
+    return null;
+  }
+  const localHash = createHash('sha256')
+    .update(typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload)
+    .digest('hex');
+  return localHash === entry.payloadHash.toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Internal: stderr advisory. Always one-shot, never duplicated. Silenceable
+// via IJFW_REKOR_QUIET=1 for noisy test environments.
+// ---------------------------------------------------------------------------
+
+function advise(message) {
+  if (process.env.IJFW_REKOR_QUIET === '1') return;
+  try {
+    process.stderr.write(`[ijfw] ${message}\n`);
+  } catch {
+    /* best-effort */
+  }
+}