rcf-lite 0.0.1 → 0.8.0

package/src/verify/cli/run.js

@@ -0,0 +1,155 @@
+// `rcf-verify run` (spec §3 primary verb). Parses flags, runs the
+// verification orchestrator, writes the report artifact (always, regardless of
+// gate — §3 rule 5), and sets the process exit code from the severity gate
+// (§8.2: exit 0 below the gate, non-zero at/above it, and always non-zero for
+// NOT-DEPLOYED / BLOCKED). This is the exact call-path build-lite's finalise
+// step spawns (§8.2).
+
+import { writeFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '#core/errors';
+
+import { runVerification } from '../engine/index.js';
+import { serialiseReport } from '../report/index.js';
+import { gateTripped, FINDING_SEVERITIES } from '../verdict/index.js';
+
+const OPTION_SPEC = {
+  repo: { type: 'string' },
+  chain: { type: 'string' },
+  profile: { type: 'string' },
+  url: { type: 'string' },
+  'parity-env': { type: 'boolean' },
+  provision: { type: 'string' },
+  out: { type: 'string' },
+  'severity-gate': { type: 'string' },
+  'provision-mode': { type: 'string' },
+  persona: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf-verify run [options]
+
+Launch a fresh-context adversarial verifier against a running app and emit a
+structured verdict stamped with the runtime it ran against.
+
+Required:
+  --repo <path-or-ref>      RCF chain source (the acceptance contract)
+  --profile <p>             Runtime profile: deployed | ci | local-dev
+  --url <app-url>           The running app for this profile
+  --out <report-path>       Where to write the structured report artifact
+
+Optional:
+  --chain <PRD/ref>         Which PRD/chain to verify against (default: the repo's)
+  --parity-env              Assert this ci/local-dev runtime is edge-identical
+                            to prod — the only path to a SHIP verdict from a
+                            non-deployed profile. Logged in the report.
+  --provision <path>        Provisioning spec / prerequisite credentials FILE
+                            (never inline; secrets never echoed)
+  --severity-gate <sev>     Exit non-zero at/above this severity:
+                            PASS | COSMETIC | DEGRADED | BROKEN
+  --provision-mode <m>      run | skip (default: run)
+  --persona <name>          Adversarial persona flavour (default: generic-sceptic)
+  --help                    Print this help
+
+Exit codes:
+  0  report written, verdict below the severity gate
+  1  IO / unexpected runtime failure (e.g. the report could not be written)
+  2  usage error (missing/invalid flags)
+  3  chain could not be loaded (the acceptance contract is unreadable)
+  5  severity gate tripped, or NOT-DEPLOYED / BLOCKED / LAUNCH-FAILURE
+     (ship cannot be confirmed — a report is still written)
+`;
+
+function exitForError(err) {
+  switch (err.kind) {
+    case 'usage': return 2;
+    case 'missingFile':
+    case 'parseFailure':
+    case 'validation': return 3;
+    default: return 1; // ioFailure + anything unexpected
+  }
+}
+
+/**
+ * @param {string[]} argv - argv slice after `run`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const gate = flags['severity-gate'];
+  if (gate && !FINDING_SEVERITIES.includes(gate)) {
+    stderr.write(`[error] usage --severity-gate must be one of ${FINDING_SEVERITIES.join(' | ')}\n`);
+    return 2;
+  }
+  const provisionMode = flags['provision-mode'] ?? 'run';
+  if (provisionMode !== 'run' && provisionMode !== 'skip') {
+    stderr.write('[error] usage --provision-mode must be run | skip\n');
+    return 2;
+  }
+  if (!flags.out) {
+    stderr.write('[error] usage --out <report-path> is required\n');
+    return 2;
+  }
+  // Dash-footgun (§3 rule 3, mirrors build's --body-file discipline): a
+  // --provision value that looks like a flag is almost always a swallowed next
+  // option or an attempt to pass a credential inline. Refuse it — credentials
+  // are FILE-only, never inline, never echoed.
+  if (typeof flags.provision === 'string' && flags.provision.startsWith('-')) {
+    stderr.write('[error] usage --provision takes a file path, not a flag or inline value (credentials are never accepted inline)\n');
+    return 2;
+  }
+
+  const result = await runVerification({
+    repo: flags.repo,
+    chainRef: flags.chain,
+    profile: flags.profile,
+    url: flags.url,
+    parityEnv: Boolean(flags['parity-env']),
+    provision: flags.provision,
+    provisionMode,
+    persona: flags.persona,
+    severityGate: gate,
+  }, deps);
+
+  if (isRcfError(result)) {
+    stderr.write(`${formatError(result, { verbose: true })}\n`);
+    return exitForError(result);
+  }
+
+  const { report } = result;
+
+  // The report is written ALWAYS, regardless of the gate (§3 rule 5).
+  const outPath = resolvePath(cwd, flags.out);
+  const writer = deps.writeFile ?? writeFile;
+  try {
+    await writer(outPath, serialiseReport(report), 'utf8');
+  } catch (err) {
+    stderr.write(`[rcf-verify] unexpected failure: could not write report: ${err.message}\n`);
+    return 1;
+  }
+
+  stderr.write(`[rcf-verify] verdict ${report.verdict} [${report.verdictAuthority}] -> ${flags.out}\n`);
+
+  // Exit code is the gate (§8.2). NOT-DEPLOYED / BLOCKED always trip.
+  return gateTripped({ verdict: report.verdict, findings: report.findings, gate }) ? 5 : 0;
+}

package/src/verify/engine/brief.js

@@ -0,0 +1,87 @@
+// Adversarial brief composition (spec §5, §9 guarantee 4). Verify is thin: it
+// reads the chain and composes an adversarial brief from the ACs, then hands
+// that brief to a fresh isolated agent (engine/launcher.js). The stance is
+// DISPROOF — an adversarial walk derived independently from the ACs does not
+// inherit the build's framing. The brief NEVER references the source tree, the
+// build transcript, or a "this was verified" claim (§9 guarantee 1-2).
+
+/** Default adversarial persona flavour (spec §3 --persona default). */
+export const DEFAULT_PERSONA = 'generic-sceptic';
+
+/**
+ * Compose the adversarial brief the verifier agent is launched with. The brief
+ * is built purely from the acceptance contract (ACs) + the live URL — the only
+ * two inputs (§9 guarantee 2). Returned as structured data so tests can assert
+ * the ACs drove it and no build context leaked in.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.acs - flattened ACs from the chain
+ * @param {string} opts.url - the running app under test
+ * @param {string} [opts.persona]
+ * @param {string} [opts.chainRef]
+ * @returns {{ persona: string, url: string, chainRef: string, stance: string, acCount: number, journeys: object[], instructions: string }}
+ */
+export function composeBrief({ acs = [], url, persona = DEFAULT_PERSONA, chainRef } = {}) {
+  const testable = acs.filter((ac) => ac.testable !== false);
+  const journeys = testable.map((ac) => {
+    // Base disprove line — the AC-only framing verify has always shipped.
+    const parts = [
+      `Attempt to make the app FAIL "${ac.then}" starting from "${ac.given}" by doing "${ac.when}", and adversarial variations of it.`,
+    ];
+    // 0.7.0: service-attestation suffix (verification-integrity-cluster-spec
+    // §5.2). Prompt-only; the chain records the attestation and verify
+    // asks the agent to hunt for a delivery observable on the live URL.
+    // No source-tree reading — the observable is a browser-reachable
+    // artefact (admin log endpoint, receipt confirmation, delivery-log
+    // page) or its absence is the honest verdict.
+    const attestations = Array.isArray(ac.serviceAttestations) ? ac.serviceAttestations : [];
+    for (const a of attestations) {
+      if (!a || typeof a.serviceId !== 'string' || typeof a.attestationMode !== 'string') continue;
+      parts.push(
+        `If the AC depends on service \`${a.serviceId}\` attested \`${a.attestationMode}\`, verify a delivery observable exists on the running URL (e.g. an admin-log endpoint the browser can poll).`,
+      );
+    }
+    // 0.7.0: UI-invariant suffix (ui-design-gate-0.7.0-spec §8.7). Fires
+    // when the AC belongs to a UI-bearing FBS. Disproof-oriented; no
+    // source-tree read; the check runs against the served HTML.
+    if (ac.fbsUiBearing === true) {
+      parts.push(
+        'The FBS is UI-bearing; a shared nav bar must be present on every enumerated authenticated route, the theme toggle must be reachable, and the signed-in-as affordance must be visible when authenticated. Disprove any of these by observation.',
+      );
+    }
+    return {
+      acId: ac.acId,
+      usId: ac.usId,
+      journey: ac.title || ac.usId || ac.acId,
+      given: ac.given,
+      when: ac.when,
+      then: ac.then,
+      // The disproof prompt for THIS criterion: try to make `then` false,
+      // plus any 0.7.0 attestation / UI suffixes the chain contributes.
+      disprove: parts.join(' '),
+    };
+  });
+
+  const instructions = [
+    'You are an adversarial verifier. Your job is to DISPROVE the application against its acceptance criteria, not to confirm it works.',
+    'You have NOT seen how this app was built, its source, or any claim that it was verified. Judge only the running app against the contract below.',
+    `Drive the running app at ${url} through each journey using your browser tooling. For each acceptance criterion, actively try to break it: edge inputs, boundary conditions, isolation between users, error paths, and the exact security/quality floors the criterion promises.`,
+    'For every defect, record: the acId it maps to, the journey, exact reproduction steps against the live URL, and evidence (screenshot path, response body, or runtime error).',
+    'Classify each finding: BROKEN (a journey is dead or wrong), DEGRADED (works but a criterion is materially weakened / a false promise / a missed floor), or COSMETIC (hygiene, no AC touched). Report PASS only for criteria you actively tried and could not break.',
+    'Do NOT claim the app is "fully verified" or "safe"; you are producing an independent ship-readiness signal, not a correctness guarantee.',
+    '',
+    'OUTPUT CONTRACT (mandatory). After any analysis, the FINAL thing you emit must be a single JSON object of exactly this shape, and nothing after it:',
+    '{"findings":[{"severity":"BROKEN|DEGRADED|COSMETIC|PASS","acId":"<AC id>","journey":"<journey name>","reproSteps":["..."],"evidence":{"kind":"<http_response|runtimeError|screenshot|note>","detail":"..."}}]}',
+    'Emit exactly one finding per acceptance criterion (a PASS finding for any you tried and could not break). The object must be valid JSON on its own; the harness extracts the last {"findings":[...]} object from your reply, so make sure your final object is complete and well-formed.',
+  ].join('\n');
+
+  return {
+    persona,
+    url,
+    chainRef: chainRef ?? 'PRD-UNKNOWN',
+    stance: 'disprove',
+    acCount: testable.length,
+    journeys,
+    instructions,
+  };
+}

package/src/verify/engine/index.js

@@ -0,0 +1,177 @@
+// Verification orchestrator (spec §5, §8.2). Ties the pieces together in the
+// exact order build-lite's finalise step would drive them: resolve the runtime
+// profile → read the acceptance contract off the chain → (deployed) gate on
+// reachability → provision prerequisites → compose the adversarial brief →
+// launch the isolated verifier agent → validate/aggregate/stamp the verdict →
+// build the ingestible report. Every failure is returned as data (RcfError),
+// never a fabricated PASS (§9 false-confidence prohibition).
+
+import { rcfError, isRcfError } from '#core/errors';
+import { isolationProvenance } from '#core/isolation';
+
+import {
+  resolveProfile,
+  checkDeployedReachability,
+  isNotDeployed,
+  verdictAuthorityFor,
+} from '../profile/index.js';
+import { readChain as defaultReadChain } from '../chain/index.js';
+import { runProvisioning, cleanup as defaultCleanup } from '../provision/index.js';
+import { composeBrief } from './brief.js';
+import { resolveLauncher } from './launcher.js';
+import { aggregateVerdict, derivePerAcVerdicts, validateFinding } from '../verdict/index.js';
+import { buildReport } from '../report/index.js';
+
+/**
+ * Validate + normalise the raw findings an agent returned. A malformed finding
+ * is an error-as-data, not a silent drop — the report contract (§5.2) requires
+ * every finding to be chain-node-addressed.
+ *
+ * @param {unknown} rawFindings
+ * @returns {{ findings: object[] } | import('#core/errors').RcfError}
+ */
+export function normaliseFindings(rawFindings) {
+  if (!Array.isArray(rawFindings)) {
+    return rcfError({ kind: 'validation', message: 'verifier agent must return a findings array' });
+  }
+  const findings = [];
+  for (const raw of rawFindings) {
+    const err = validateFinding(raw);
+    if (err) return err;
+    findings.push({
+      severity: raw.severity,
+      acId: raw.acId,
+      journey: raw.journey,
+      reproSteps: raw.reproSteps,
+      evidence: raw.evidence,
+    });
+  }
+  return { findings };
+}
+
+/**
+ * Run a full verification. Returns `{ report }` on completion (including the
+ * NOT-DEPLOYED / BLOCKED refusals, which are legitimate reports), or an
+ * RcfError for usage / chain-load / agent failures the CLI maps to a non-zero
+ * exit.
+ *
+ * @param {object} opts - the CLI-parsed run options
+ * @param {object} [deps] - injectable seams (launchAgent, fetchImpl, signup, teardown, now, readChain)
+ * @returns {Promise<{ report: object } | import('#core/errors').RcfError>}
+ */
+export async function runVerification(opts = {}, deps = {}) {
+  const now = deps.now ?? (() => new Date().toISOString());
+  const readChain = deps.readChain ?? defaultReadChain;
+  const startedAt = now();
+
+  // 1. Resolve + validate the runtime declaration (§4).
+  const resolved = resolveProfile({ profile: opts.profile, url: opts.url, parityEnv: opts.parityEnv });
+  if (isRcfError(resolved)) return resolved;
+  const { profile, url, parityEnv } = resolved;
+
+  // 2. Read the acceptance contract off the chain (the ONLY structural input, §9).
+  const chain = await readChain({ repo: opts.repo, chainRef: opts.chainRef });
+  if (isRcfError(chain)) return chain;
+
+  const verdictAuthority = verdictAuthorityFor(profile, parityEnv);
+
+  // Per-AC verdicts (0.7.0). Derived from chain data — service attestations
+  // (Track A §5.2) and UI-bearing FBS × browserVerification[] (Track B §8.7)
+  // — before any structural refusal so the report always carries the
+  // honest chain-derived picture, not just the run-time findings. The
+  // finalise gate (build/src/finalise/ingest.js) reads this array and
+  // refuses `verified` on any MOCK-ONLY-DECLARED / BLOCKED-BY-DECLARATION
+  // entry regardless of the run-level verdict.
+  const perAcVerdicts = derivePerAcVerdicts({
+    acs: chain.acs,
+    browserVerification: chain.manifest?.browserVerification ?? [],
+  });
+
+  // 3. Deployed reachability gate (§4). Only consulted for profile==='deployed'.
+  let reachability = null;
+  if (profile === 'deployed') {
+    reachability = await checkDeployedReachability(url, { fetchImpl: deps.fetchImpl });
+    if (isNotDeployed(profile, reachability)) {
+      // Refusal to issue a verdict — never a soft pass (§4, §5.1).
+      const report = buildReport({
+        profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+        persona: opts.persona, startedAt, finishedAt: now(),
+        verifierIsolation: isolationProvenance(),
+        verdict: 'NOT-DEPLOYED', verdictAuthority,
+        findings: [], blockedAcs: [], provisioning: null,
+        perAcVerdicts,
+      });
+      return { report };
+    }
+  }
+
+  // 4. Provision prerequisites (§6). Unprovisionable → BLOCKED (named), dependent ACs BLOCKED.
+  const { provisioning, blockedAcs } = await runProvisioning({
+    acs: chain.acs,
+    url,
+    provisionPath: opts.provision,
+    mode: opts.provisionMode ?? 'run',
+    signup: deps.signup,
+  });
+
+  // 5. Compose the adversarial brief from the chain ACs (§5, §9 guarantee 4).
+  const brief = composeBrief({ acs: chain.acs, url, persona: opts.persona, chainRef: chain.chainRef });
+
+  // Cleanup runs whether or not the launch succeeds — provisioned artefacts
+  // must not be orphaned by a launch failure (§6 cleanup contract).
+  const runCleanup = async () => {
+    const cleanupFn = deps.cleanup ?? defaultCleanup;
+    const cleanupResult = await cleanupFn({ provisioned: provisioning.provisioned, teardown: deps.teardown });
+    provisioning.cleanupRan = cleanupResult.cleanupRan;
+    provisioning.cleanupRemoved = cleanupResult.cleanupRemoved;
+    if (cleanupResult.cleanupBlocked?.length) provisioning.cleanupBlocked = cleanupResult.cleanupBlocked;
+  };
+
+  // 6. Launch the isolated verifier agent (§7.3 isolation env, §9 fresh session).
+  let launchResult;
+  try {
+    const launchAgent = await resolveLauncher(deps);
+    launchResult = await launchAgent({ brief, url, profile });
+  } catch (err) {
+    // A verifier agent that could not run — or whose output could not be
+    // ingested — is NEVER a fabricated PASS (§9). But the report is still
+    // build-lite's next input (§5.4, §10 --out-always-written), so we build a
+    // LAUNCH-FAILURE report carrying the error + preserved-transcript path so
+    // the fix loop has something to ingest. Exit stays non-zero (gate trips).
+    await runCleanup();
+    const report = buildReport({
+      profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+      persona: opts.persona, startedAt, finishedAt: now(),
+      verifierIsolation: isolationProvenance(),
+      verdict: 'LAUNCH-FAILURE', verdictAuthority,
+      findings: [], blockedAcs, provisioning,
+      launchFailure: { message: err.message, rawOutputPath: err.rawOutputPath ?? null },
+      perAcVerdicts,
+    });
+    return { report };
+  }
+
+  // 7. Validate + stamp the findings (§5.2 chain-node addressing).
+  const normalised = normaliseFindings(launchResult?.findings);
+  if (isRcfError(normalised)) return normalised;
+  const { findings } = normalised;
+
+  // 8. Cleanup provisioned artefacts (§6 cleanup contract).
+  await runCleanup();
+
+  // 9. Aggregate the verdict — split, never averaged (§5.1).
+  const verdict = aggregateVerdict({ findings, blockedAcs, notDeployed: false });
+
+  // 10. Build the ingestible report (§5.3).
+  const report = buildReport({
+    profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+    persona: opts.persona, startedAt, finishedAt: now(),
+    verifierIsolation: isolationProvenance(),
+    verdict, verdictAuthority,
+    findings, blockedAcs, provisioning,
+    runStats: launchResult?.runStats ?? null,
+    perAcVerdicts,
+  });
+
+  return { report };
+}