rcf-lite 0.0.1 → 0.8.0

package/src/verify/provision/index.js

@@ -0,0 +1,256 @@
+// Prerequisite provisioning (spec §6, amendment 2). Adversarial verification
+// usually can't start from nothing. One mechanism, three kinds of
+// prerequisite the chain's ACs may imply: auth accounts (common), third-party
+// service sandboxes/keys, and seeded test data.
+//
+// Hard rules this module enforces (each a §10 acceptance criterion):
+//  - the `zzverify-` prefix on ALL provisioned artefacts, so they are
+//    greppable and sweepable;
+//  - credentials/keys go ONLY to the --provision file, NEVER inline, NEVER
+//    echoed to logs or the report body (redactSecrets is the guard);
+//  - what cannot be provisioned is BLOCKED (naming the missing prerequisite)
+//    and its dependent ACs are marked BLOCKED — never silently skipped;
+//  - cleanup removes provisioned artefacts and the report states what it did.
+
+import { writeFile, readFile } from 'node:fs/promises';
+
+import { rcfError } from '#core/errors';
+import { matchServiceSignals } from '#core/patterns/services';
+
+/** Greppable prefix on every provisioned artefact (accounts + data alike). */
+export const ZZVERIFY_PREFIX = 'zzverify-';
+
+/** v1 auth provisioning stands up at least this many accounts (multi-user isolation journeys). */
+export const MIN_AUTH_ACCOUNTS = 2;
+
+/** Field names whose VALUES must never reach a log or the report body. */
+export const SECRET_FIELDS = Object.freeze(['password', 'token', 'secret', 'key', 'apiKey', 'credential', 'cookie']);
+
+const AUTH_PATTERNS = /\b(sign[\s-]?in|sign[\s-]?up|log[\s-]?in|logout|register|registration|authenticat|account|password|credential|session|onboard)/i;
+const SEEDDATA_PATTERNS = /\b(admin[\s-]?(created|seeded)|seeded|pre[\s-]?populated|existing (record|row|dataset)|another user|user b\b|other user)/i;
+
+/**
+ * Classify the prerequisite kind an AC implies (or null if none). Matches on
+ * the AC's given/when/then/description text. Heuristic — the honest hard part
+ * (§6): where the route can't be derived, the caller BLOCKS rather than skips.
+ *
+ * The `serviceSandbox` branch is delegated to core's shared pattern set
+ * (`#core/patterns/services`), the same seed data
+ * consumed by build's pre-flight scanner (verification-integrity-cluster-spec
+ * §5.3 / §8.4). Verify's original inline SERVICE_PATTERNS regex is
+ * superseded — a single shared source removes the class of drift that
+ * shipped the d-2026-07-30-142 "email channel" miss.
+ *
+ * @param {object} ac - a flattened AC ({acId, description, given, when, then})
+ * @returns {'authAccount'|'serviceSandbox'|'seedData'|null}
+ */
+export function classifyPrerequisite(ac) {
+  const text = [ac.description, ac.given, ac.when, ac.then, ac.title].filter(Boolean).join(' ');
+  if (matchServiceSignals(text).length > 0) return 'serviceSandbox';
+  if (SEEDDATA_PATTERNS.test(text)) return 'seedData';
+  if (AUTH_PATTERNS.test(text)) return 'authAccount';
+  return null;
+}
+
+/**
+ * Derive the provisioning plan from the chain's ACs: which prerequisite kinds
+ * are required, and which ACs depend on each. v1 automates authAccount against
+ * signup-exposing apps; serviceSandbox / seedData routes are honestly BLOCKED
+ * unless an out-of-band route is supplied (§6 v1 scope note).
+ *
+ * @param {Array<object>} acs
+ * @returns {{ required: string[], acsByKind: Record<string, string[]> }}
+ */
+export function deriveProvisioningPlan(acs = []) {
+  const acsByKind = {};
+  for (const ac of acs) {
+    const kind = classifyPrerequisite(ac);
+    if (!kind) continue;
+    (acsByKind[kind] ??= []).push(ac.acId);
+  }
+  return { required: Object.keys(acsByKind), acsByKind };
+}
+
+/**
+ * Deep-redact secret values for anything bound for a log or the report body.
+ * Returns a new object; input untouched. Any key in SECRET_FIELDS (case-
+ * insensitive) has its value replaced with '[redacted]'.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function redactSecrets(value) {
+  if (Array.isArray(value)) return value.map(redactSecrets);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = SECRET_FIELDS.some((f) => f.toLowerCase() === k.toLowerCase())
+        ? '[redacted]'
+        : redactSecrets(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Write provisioned credentials to the --provision file (spec §3 rule 3, §6).
+ * This is the ONLY sink for secrets. Never returns the secrets to the caller
+ * for logging.
+ *
+ * @param {string} provisionPath
+ * @param {object} data - full provisioning record including credentials
+ * @returns {Promise<import('#core/errors').RcfError | null>}
+ */
+export async function writeProvisionFile(provisionPath, data) {
+  if (typeof provisionPath !== 'string' || provisionPath.length === 0) {
+    return rcfError({ kind: 'usage', message: '--provision requires a file path', field: 'provision' });
+  }
+  try {
+    await writeFile(provisionPath, JSON.stringify(data, null, 2), 'utf8');
+    return null;
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `failed to write provision file: ${err.message}`, filePath: provisionPath, stack: err.stack });
+  }
+}
+
+/**
+ * Read a provisioning file (credentials/fixtures) back for a run/cleanup.
+ *
+ * @param {string} provisionPath
+ * @returns {Promise<object | import('#core/errors').RcfError>}
+ */
+export async function readProvisionFile(provisionPath) {
+  try {
+    return JSON.parse(await readFile(provisionPath, 'utf8'));
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `failed to read provision file: ${err.message}`, filePath: provisionPath, stack: err.stack });
+  }
+}
+
+/**
+ * Provision auth accounts against a signup-exposing app. The actual signup is
+ * app-specific and agent-driven — supplied via the injected `signup` function
+ * (the seam; §6 "the provisioning route is app-specific"). Without a signup
+ * route the whole kind is BLOCKED, honestly.
+ *
+ * @param {object} opts
+ * @param {string} opts.url
+ * @param {number} [opts.count]
+ * @param {((ctx: {url: string, username: string}) => Promise<object>)} [opts.signup]
+ *   - returns account credentials; may throw to signal an unprovisionable app
+ * @returns {Promise<{ provisioned: object[], blocked: object[], credentials: object[] }>}
+ */
+export async function provisionAuth({ url, count = MIN_AUTH_ACCOUNTS, signup } = {}) {
+  const provisioned = [];
+  const blocked = [];
+  const credentials = [];
+  if (typeof signup !== 'function') {
+    blocked.push({ kind: 'authAccount', reason: 'cannot provision: app exposes no derivable signup route (invite-only / admin-seeded / out-of-band). See §6 deferred.' });
+    return { provisioned, blocked, credentials };
+  }
+  const suffixes = 'abcdefghijklmnopqrstuvwxyz';
+  for (let i = 0; i < Math.max(count, MIN_AUTH_ACCOUNTS); i += 1) {
+    const ref = `${ZZVERIFY_PREFIX}${suffixes[i] ?? String(i)}`;
+    try {
+      const creds = await signup({ url, username: ref });
+      provisioned.push({ kind: 'authAccount', ref });
+      credentials.push({ ref, ...creds });
+    } catch (err) {
+      blocked.push({ kind: 'authAccount', reason: `cannot provision ${ref}: ${err.message}` });
+    }
+  }
+  return { provisioned, blocked, credentials };
+}
+
+/**
+ * Run provisioning end-to-end for a `run` (spec §6, run-internalised). Derives
+ * the plan, provisions auth where a signup route exists, BLOCKS every other
+ * required kind (naming the missing prerequisite), marks dependent ACs as
+ * BLOCKED, and writes credentials to the --provision file only.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.acs
+ * @param {string} opts.url
+ * @param {string} [opts.provisionPath]
+ * @param {'run'|'skip'} [opts.mode]
+ * @param {((ctx: object) => Promise<object>)} [opts.signup] - injected signup route
+ * @returns {Promise<{ provisioning: object, blockedAcs: object[] }>}
+ */
+export async function runProvisioning({ acs = [], url, provisionPath, mode = 'run', signup } = {}) {
+  const provisioning = { provisioned: [], blocked: [], cleanupRan: false, cleanupRemoved: [] };
+  const blockedAcs = [];
+
+  if (mode === 'skip') return { provisioning, blockedAcs };
+
+  const plan = deriveProvisioningPlan(acs);
+  const allCredentials = [];
+
+  for (const kind of plan.required) {
+    const dependentAcIds = plan.acsByKind[kind] ?? [];
+    if (kind === 'authAccount') {
+      const { provisioned, blocked, credentials } = await provisionAuth({ url, signup });
+      provisioning.provisioned.push(...provisioned);
+      provisioning.blocked.push(...blocked);
+      allCredentials.push(...credentials);
+      // If auth could not be provisioned at all, its dependent ACs are BLOCKED.
+      if (provisioned.length === 0) {
+        const reason = blocked[0]?.reason ?? 'cannot provision: authAccount';
+        for (const acId of dependentAcIds) blockedAcs.push({ acId, reason });
+      }
+    } else {
+      // serviceSandbox / seedData — v1 honest BLOCK unless an out-of-band route exists.
+      const reason = `cannot provision: ${kind} (out-of-band route required — §6 v1 deferred)`;
+      provisioning.blocked.push({ kind, reason });
+      for (const acId of dependentAcIds) blockedAcs.push({ acId, reason });
+    }
+  }
+
+  // Credentials go ONLY to the provision file — never into `provisioning`
+  // (which lands in the report body) and never returned for logging.
+  if (allCredentials.length > 0 && provisionPath) {
+    const writeErr = await writeProvisionFile(provisionPath, {
+      schemaVersion: '1',
+      url,
+      credentials: allCredentials,
+    });
+    // Surface the write failure as data instead of discarding it: a failed
+    // credential write means the run's provisioned accounts are unusable
+    // downstream, and silently swallowing it hid a real fault (w-2026-07-21-006).
+    // Only the message + path are recorded — never the credentials themselves.
+    if (writeErr) {
+      provisioning.provisionWriteError = { message: writeErr.message, filePath: writeErr.filePath ?? provisionPath };
+    }
+  }
+
+  return { provisioning, blockedAcs };
+}
+
+/**
+ * Tear down provisioned artefacts (spec §6 cleanup contract). The actual
+ * teardown is app-specific — supplied via the injected `teardown` function.
+ * Records what it removed for the report.
+ *
+ * @param {object} opts
+ * @param {object[]} [opts.provisioned] - [{kind, ref}]
+ * @param {((ref: string) => Promise<void>)} [opts.teardown]
+ * @returns {Promise<{ cleanupRan: boolean, cleanupRemoved: string[], cleanupBlocked: object[] }>}
+ */
+export async function cleanup({ provisioned = [], teardown } = {}) {
+  const cleanupRemoved = [];
+  const cleanupBlocked = [];
+  if (typeof teardown !== 'function') {
+    // No teardown route — report honestly rather than claim a clean sweep.
+    for (const p of provisioned) cleanupBlocked.push({ ref: p.ref, reason: 'no teardown route supplied' });
+    return { cleanupRan: false, cleanupRemoved, cleanupBlocked };
+  }
+  for (const p of provisioned) {
+    try {
+      await teardown(p.ref);
+      cleanupRemoved.push(p.ref);
+    } catch (err) {
+      cleanupBlocked.push({ ref: p.ref, reason: err.message });
+    }
+  }
+  return { cleanupRan: true, cleanupRemoved, cleanupBlocked };
+}

package/src/verify/report/index.js

@@ -0,0 +1,139 @@
+// Report artifact (spec §5.3). The report is NOT a dead-end artifact — it is
+// build-lite's next input (§5.4), so it is emitted chain-node-addressed and
+// camelCase, with `schemaVersion` from day one so build-lite's ingest can
+// version-gate. Credentials never appear in the report body (§10) — the
+// builder passes an already-clean provisioning record, and redactSecrets is a
+// defence-in-depth guard on top.
+
+import { rcfError } from '#core/errors';
+
+import { redactSecrets } from '../provision/index.js';
+import { PER_AC_VERDICTS, VERDICTS } from '../verdict/index.js';
+
+/** The report schema version. Present from day one for build-lite's version-gated ingest. */
+export const SCHEMA_VERSION = '1';
+
+const DEFAULT_PERSONA = 'generic-sceptic';
+
+/**
+ * Assemble the §5.3 report object. Pure — all runtime facts are passed in.
+ *
+ * @param {object} p
+ * @returns {object} the report artifact
+ */
+export function buildReport(p) {
+  const report = {
+    schemaVersion: SCHEMA_VERSION,
+    run: {
+      profile: p.profile,
+      url: p.url,
+      parityEnv: Boolean(p.parityEnv),
+      reachability: p.reachability ?? null,
+      chainRef: p.chainRef ?? null,
+      repo: p.repo ?? null,
+      persona: p.persona ?? DEFAULT_PERSONA,
+      startedAt: p.startedAt ?? null,
+      finishedAt: p.finishedAt ?? null,
+      verifierIsolation: p.verifierIsolation ?? { autoMemory: false, nonEssentialTraffic: false },
+      // Agent usage/timing from the --output-format json envelope (§5.3, additive).
+      // Omit-not-fake: null when the launcher could not report it.
+      runStats: p.runStats ?? null,
+    },
+    verdict: p.verdict,
+    verdictAuthority: p.verdictAuthority,
+    findings: Array.isArray(p.findings) ? p.findings : [],
+    blockedAcs: Array.isArray(p.blockedAcs) ? p.blockedAcs : [],
+    provisioning: p.provisioning ?? null,
+    // Present (non-null) only on a LAUNCH-FAILURE verdict: the agent could not
+    // run or its output could not be ingested. Carries the error + the path to
+    // the preserved raw transcript so the §5.4 fix loop has something to ingest.
+    launchFailure: p.launchFailure ?? null,
+  };
+  // 0.7.0 per-AC verdicts (verification-integrity-cluster-spec §5.2,
+  // ui-design-gate §8.7). Present-only when at least one entry has been
+  // derived from the chain — an older chain with no 0.7.0 fields produces
+  // no per-AC verdicts and the field is omitted so backward-compatible
+  // consumers (rcf finalise pre-0.7.0) do not see an unexpected field.
+  if (Array.isArray(p.perAcVerdicts) && p.perAcVerdicts.length > 0) {
+    report.perAcVerdicts = p.perAcVerdicts.map((v) => ({
+      acId: v.acId,
+      verdict: v.verdict,
+      ...(v.reason !== undefined ? { reason: v.reason } : {}),
+    }));
+  }
+  // Defence-in-depth: never let a secret reach the report body (§10).
+  return redactSecrets(report);
+}
+
+/**
+ * Serialise a report to the on-disk artifact string (camelCase JSON).
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function serialiseReport(report) {
+  return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+/**
+ * Parse a report artifact back (for `rcf-verify report`). Errors as data.
+ *
+ * @param {string} raw
+ * @returns {object | import('#core/errors').RcfError}
+ */
+export function parseReport(raw) {
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return rcfError({ kind: 'parseFailure', message: `report is not valid JSON: ${err.message}` });
+  }
+  const shapeErr = validateReportShape(doc);
+  if (shapeErr) return shapeErr;
+  return doc;
+}
+
+/**
+ * Minimal shape check on a report artifact.
+ *
+ * @param {object} doc
+ * @returns {import('#core/errors').RcfError | null}
+ */
+export function validateReportShape(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return rcfError({ kind: 'validation', message: 'report must be an object' });
+  }
+  if (doc.schemaVersion !== SCHEMA_VERSION) {
+    return rcfError({ kind: 'validation', message: `unsupported report schemaVersion: ${doc.schemaVersion ?? '(missing)'}`, field: 'schemaVersion' });
+  }
+  if (!VERDICTS.includes(doc.verdict)) {
+    return rcfError({ kind: 'validation', message: `unknown verdict: ${doc.verdict}`, field: 'verdict' });
+  }
+  if (doc.verdictAuthority !== 'ship' && doc.verdictAuthority !== 'correctness') {
+    return rcfError({ kind: 'validation', message: `verdictAuthority must be ship|correctness (got ${doc.verdictAuthority})`, field: 'verdictAuthority' });
+  }
+  if (!doc.run || typeof doc.run !== 'object') {
+    return rcfError({ kind: 'validation', message: 'report.run is required', field: 'run' });
+  }
+  // perAcVerdicts is optional (0.7.0 addition); when present every entry
+  // must carry an acId and a known per-AC verdict class. Unknown verdicts
+  // are rejected as data so a consumer never has to guess the class of an
+  // unfamiliar string.
+  if (doc.perAcVerdicts !== undefined) {
+    if (!Array.isArray(doc.perAcVerdicts)) {
+      return rcfError({ kind: 'validation', message: 'report.perAcVerdicts must be an array when present', field: 'perAcVerdicts' });
+    }
+    for (const entry of doc.perAcVerdicts) {
+      if (!entry || typeof entry !== 'object') {
+        return rcfError({ kind: 'validation', message: 'report.perAcVerdicts entries must be objects', field: 'perAcVerdicts' });
+      }
+      if (typeof entry.acId !== 'string' || entry.acId.length === 0) {
+        return rcfError({ kind: 'validation', message: 'report.perAcVerdicts[].acId is required', field: 'perAcVerdicts' });
+      }
+      if (!PER_AC_VERDICTS.includes(entry.verdict)) {
+        return rcfError({ kind: 'validation', message: `report.perAcVerdicts[].verdict must be one of ${PER_AC_VERDICTS.join('/')} (got ${entry.verdict})`, field: 'perAcVerdicts' });
+      }
+    }
+  }
+  return null;
+}

package/src/verify/report/renderer.js

@@ -0,0 +1,118 @@
+// Self-contained finding-renderer (spec §5.3, §7.2). v1 core is store + errors
+// + mcp-shell ONLY: the build `view/` layer is NOT a clean shell and is
+// firmly OUT of v1 core. So verify ships its OWN minimal, dependency-free human
+// render for `rcf-verify report`. Plain text, British English, ASCII hyphens,
+// mirroring build's help-surface conventions without importing any core view code.
+//
+// Honest-limit language (§9): the render NEVER says "fully verified" / "safe".
+
+/** One-line human summary of a verdict, including its ship implication. */
+const VERDICT_LINE = {
+  PASS: 'PASS: every AC verified against the running app; no defect above COSMETIC.',
+  BROKEN: 'BROKEN: one or more ACs fail on the running app. Blocks ship.',
+  DEGRADED: 'DEGRADED: app works but a criterion is materially weakened. Reported; may block per gate.',
+  COSMETIC: 'COSMETIC: hygiene only; no AC touched. Does not block.',
+  'NOT-DEPLOYED': 'NOT-DEPLOYED: deployed profile declared but no real deploy reachable. A refusal to issue a verdict, not a pass.',
+  BLOCKED: 'BLOCKED: a prerequisite could not be provisioned; dependent ACs were not exercisable.',
+  'LAUNCH-FAILURE': 'LAUNCH-FAILURE: the verifier agent could not run or its output could not be ingested. A refusal to issue a verdict, not a pass.',
+};
+
+/**
+ * Render a report artifact to a human-readable string.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const lines = [];
+  const run = report.run ?? {};
+  lines.push('RCF Verify: verification report');
+  lines.push('='.repeat(40));
+  lines.push(`Verdict:   ${report.verdict}  [authority: ${report.verdictAuthority}]`);
+  lines.push(`  ${VERDICT_LINE[report.verdict] ?? ''}`.trimEnd());
+  lines.push('');
+  lines.push('Runtime provenance');
+  lines.push(`  profile:   ${run.profile}`);
+  lines.push(`  url:       ${run.url}`);
+  lines.push(`  parityEnv: ${run.parityEnv === true}`);
+  if (run.reachability) {
+    lines.push(`  reachable: ${run.reachability.reachable}  looksLocal: ${run.reachability.looksLocal}`);
+  }
+  lines.push(`  chainRef:  ${run.chainRef ?? '(none)'}`);
+  lines.push(`  persona:   ${run.persona ?? '(default)'}`);
+  if (run.verifierIsolation) {
+    lines.push(`  isolation: autoMemory=${run.verifierIsolation.autoMemory} nonEssentialTraffic=${run.verifierIsolation.nonEssentialTraffic}`);
+  }
+  lines.push('');
+
+  const findings = report.findings ?? [];
+  lines.push(`Findings (${findings.length})`);
+  if (findings.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const f of findings) {
+      lines.push(`  [${f.severity}] ${f.acId}: ${f.journey}`);
+      for (const step of f.reproSteps ?? []) lines.push(`      - ${step}`);
+      if (f.evidence) {
+        const detail = f.evidence.detail ?? f.evidence.kind ?? JSON.stringify(f.evidence);
+        lines.push(`      evidence: ${detail}`);
+      }
+    }
+  }
+  lines.push('');
+
+  const blocked = report.blockedAcs ?? [];
+  if (blocked.length > 0) {
+    lines.push(`Blocked ACs (${blocked.length}), NOT exercisable, not silently skipped`);
+    for (const b of blocked) lines.push(`  ${b.acId}: ${b.reason}`);
+    lines.push('');
+  }
+
+  // 0.7.0 per-AC verdicts. Rendered as a dedicated section so an operator
+  // reading the human render sees the honest picture on any AC that came
+  // back mock-only / declared / UI-baseline-unmet, even when the top-level
+  // verdict is PASS. Present-only; pre-0.7.0 reports skip this block.
+  const perAc = Array.isArray(report.perAcVerdicts) ? report.perAcVerdicts : [];
+  if (perAc.length > 0) {
+    lines.push(`Per-AC verdicts (${perAc.length}), chain-derived alongside the run verdict`);
+    for (const v of perAc) {
+      lines.push(`  [${v.verdict}] ${v.acId}`);
+      if (v.reason) lines.push(`      ${v.reason}`);
+    }
+    lines.push('');
+  }
+
+  if (report.launchFailure) {
+    lines.push('Launch failure');
+    lines.push(`  ${report.launchFailure.message}`);
+    if (report.launchFailure.rawOutputPath) lines.push(`  raw transcript: ${report.launchFailure.rawOutputPath}`);
+    lines.push('');
+  }
+
+  if (run.runStats) {
+    const s = run.runStats;
+    const bits = [];
+    if (typeof s.durationMs === 'number') bits.push(`duration=${s.durationMs}ms`);
+    if (typeof s.numTurns === 'number') bits.push(`turns=${s.numTurns}`);
+    if (s.tokens) bits.push(`tokens in/out=${s.tokens.inputTokens ?? '?'}/${s.tokens.outputTokens ?? '?'}`);
+    if (typeof s.totalCostUsd === 'number') bits.push(`cost=$${s.totalCostUsd.toFixed(4)}`);
+    if (bits.length) {
+      lines.push(`Run stats: ${bits.join('  ')}`);
+      lines.push('');
+    }
+  }
+
+  const prov = report.provisioning;
+  if (prov) {
+    lines.push('Provisioning');
+    lines.push(`  provisioned: ${(prov.provisioned ?? []).map((p) => p.ref).join(', ') || '(none)'}`);
+    if ((prov.blocked ?? []).length) {
+      lines.push(`  blocked:     ${prov.blocked.map((b) => `${b.kind} (${b.reason})`).join('; ')}`);
+    }
+    lines.push(`  cleanupRan:  ${prov.cleanupRan === true}  removed: ${(prov.cleanupRemoved ?? []).join(', ') || '(none)'}`);
+    lines.push('');
+  }
+
+  lines.push('Note: this is an independent ship-readiness signal, not a correctness guarantee.');
+  return `${lines.join('\n')}\n`;
+}