@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.0

package/src/lineage/flow-grade.js

@@ -0,0 +1,221 @@
+//
+// flow-grade.js — FR-306 edge grading (Sub-project C, increment 6).
+//
+// Binding spec: DESIGN_PATH_PROVENANCE.md §16 (§16.1-§16.10; design + PoC
+// landed as Task 1, this is Task 2, the mechanical implementation). A
+// PURE grading function library: it consumes ONLY the fields a
+// `path-query.js` `Hop`/`Path` or a raw `path-store.js` edge already
+// carries. **Zero imports** — one step stricter than `path-query.js`'s own
+// `['./ids.js']` boundary (§16.1). Never `engine.js`/`summaries.js`/
+// `driver.js`, and never `path-store.js`/`path-query.js` either: grading
+// needs neither a path nor the store, since a hop is a denormalized copy
+// of its edge (proven by `C6/11`, over every edge of the 2-function
+// resolved-call fixture — grading a raw `PathStore` edge and grading the
+// `Hop` denormalized from it are byte-identical).
+//
+
+/**
+ * §16.2. The flow-evidence vocabulary, in CONFIDENCE order, most
+ * confident first. Deliberately NOT `protection.js`'s `EVIDENCE_GRADES`
+ * — see §16.2's rejection note (that enum grades the SOURCE of a
+ * protection verdict; this one grades how explicit a recorded data
+ * movement is, and every value here comes from the same evidence source).
+ *
+ * `implicit` is RESERVED: nothing in the engine emits a control-dependence
+ * reason today (§10.2 — "the engine models no implicit flow today; do not
+ * invent one"). It is present because FR-306 names it first and because
+ * §14.2's `origin` node kind set the precedent for keeping, and hand-
+ * testing, the exact shape a later increment will produce.
+ *
+ * `unassessed` is the empty-input answer only, mirroring
+ * `protection.js`'s `aggregateVerdicts` returning `'not_assessed'` for an
+ * empty array. Nothing ever grades a real hop `unassessed`.
+ */
+export const FLOW_EVIDENCE_GRADES = Object.freeze([
+  'explicit', 'widened', 'implicit', 'severed', 'ambiguous', 'unassessed',
+]);
+
+/**
+ * §16.4. Risk precedence for aggregation — lower index wins, exactly like
+ * `protection.js`'s own private `_PRECEDENCE`. This is the reverse of the
+ * confidence order above for the five real grades, with `unassessed` kept
+ * last so it survives an aggregation only when there is nothing else in it.
+ * Kept private, exactly as `protection.js` keeps its own — `C6/0` is the
+ * parity check that stops it drifting from `FLOW_EVIDENCE_GRADES`.
+ */
+const _PRECEDENCE = Object.freeze([
+  'ambiguous', 'severed', 'implicit', 'widened', 'explicit', 'unassessed',
+]);
+
+/**
+ * §16.3. Reason strings that mean "this hop is control-dependent, not a
+ * data assignment". Empty of anything the engine emits today, by design.
+ */
+export const IMPLICIT_FLOW_REASONS = Object.freeze(['control-dependence']);
+
+/** §16.5. Loss reasons that mean "an engine budget degraded this away". */
+export const DEGRADED_LOSS_REASONS = Object.freeze(['context-cap-degraded']);
+
+export function flowGradeRank(grade) {
+  const i = FLOW_EVIDENCE_GRADES.indexOf(grade);
+  if (i === -1) throw new Error(`flowGradeRank: unrecognized flow evidence grade "${grade}"`);
+  return i;
+}
+
+/**
+ * §16.4. Reduce hop grades to one path grade: the WORST wins. Never
+ * guesses — an empty array is `'unassessed'`, and an unrecognized grade
+ * throws rather than silently sorting last, verbatim `aggregateVerdicts`'
+ * own contract ("a typo here must not quietly rank as safest").
+ */
+export function aggregateFlowGrades(grades) {
+  if (!Array.isArray(grades) || grades.length === 0) return 'unassessed';
+  let worst = null;
+  let worstRank = Infinity;
+  for (const g of grades) {
+    const rank = _PRECEDENCE.indexOf(g);
+    if (rank === -1) throw new Error(`aggregateFlowGrades: unrecognized flow evidence grade "${g}"`);
+    if (rank < worstRank) { worstRank = rank; worst = g; }
+  }
+  return worst;
+}
+
+function _sortedUnion(...arrays) {
+  const s = new Set();
+  for (const a of arrays) for (const v of a ?? []) if (v != null) s.add(v);
+  return [...s].sort();
+}
+
+/**
+ * §16.3. Grade ONE hop. Accepts either a `path-query.js` `Hop` or a raw
+ * `path-store.js` EDGE — they carry the same grading fields, a hop being a
+ * denormalized copy of its edge (proven by C6/11).
+ *
+ * **The annotation rule (§16.5), and it is load-bearing:** `widenReasons`
+ * and `lossReasons` are read as the UNION of the hop's own top-level
+ * arrays AND every `annotations[].widenReason` / `.lossReason`. §2.2
+ * classifies a null-`fromPath`, null-`peerScope` in-half as an annotation
+ * on the edges its siblings form, so a genuine widening recorded at an
+ * expression-internal construct lands ONLY in `annotations[]` — measured
+ * on three real fixtures (C6/5). A grader reading only the top-level
+ * arrays grades those flows `explicit`, which is FR-306's own literal
+ * prohibition.
+ *
+ * `crossScope` is carried as a FACTOR and never affects `grade` (§16.6).
+ */
+export function gradeHop(hop) {
+  const annotations = Array.isArray(hop.annotations) ? hop.annotations : [];
+  const topWiden = Array.isArray(hop.widenReasons) ? hop.widenReasons : [];
+  const topLoss = Array.isArray(hop.lossReasons) ? hop.lossReasons : [];
+  const widenAll = _sortedUnion(topWiden, annotations.map((a) => a.widenReason));
+  const lossAll = _sortedUnion(topLoss, annotations.map((a) => a.lossReason));
+
+  // A control-dependence reason is not a widening — it selects the
+  // `implicit` tier and is removed from `widenReasons` so it never
+  // double-counts.
+  //
+  // §16.3: the subtraction is applied to the WIDEN side ONLY, deliberately
+  // (fix round 1, nitpick 8). Applying it to `lossAll` too would let a
+  // future `lossReason: 'control-dependence'` be silently UPGRADED from
+  // `severed` to the more-confident `implicit` tier — a grade moving in
+  // the optimistic direction because a new reason string was added
+  // elsewhere. Unreachable today (no loss reason is in the set), and kept
+  // unreachable by construction rather than by luck.
+  const isImplicit = (r) => IMPLICIT_FLOW_REASONS.includes(r);
+  const implicitReasons = widenAll.filter(isImplicit).sort();
+  const widenReasons = widenAll.filter((r) => !isImplicit(r));
+  const lossReasons = [...lossAll];
+
+  // Exactly which reasons would have been invisible to a top-level-only
+  // reader. Named, not merely folded — §18.4's transparency requirement
+  // applied to the grade's own inputs.
+  const annotationOnly = [
+    ...widenAll.filter((r) => !topWiden.includes(r)).map((r) => `widen:${r}`),
+    ...lossAll.filter((r) => !topLoss.includes(r)).map((r) => `loss:${r}`),
+  ].sort();
+
+  const ambiguousCorrelation = hop.ambiguousCorrelation === true;
+  const truncated = hop.truncated === true;
+  const crossScope = hop.crossScope === true;
+
+  const grade = ambiguousCorrelation ? 'ambiguous'
+    : lossReasons.length > 0 ? 'severed'
+      : implicitReasons.length > 0 ? 'implicit'
+        : widenReasons.length > 0 ? 'widened'
+          : 'explicit';
+
+  const factors = [
+    ...widenReasons.map((r) => `widen:${r}`),
+    ...lossReasons.map((r) => `loss:${r}`),
+    ...implicitReasons.map((r) => `implicit:${r}`),
+    ...(ambiguousCorrelation ? ['ambiguous-correlation'] : []),
+    ...(truncated ? ['analysis-truncated'] : []),
+    ...(crossScope ? ['cross-scope'] : []),
+  ].sort();
+
+  const degraded = lossAll.some((r) => DEGRADED_LOSS_REASONS.includes(r));
+  return {
+    grade,
+    rank: flowGradeRank(grade),
+    factors,
+    widenReasons,
+    lossReasons,
+    implicitReasons,
+    annotationOnly,
+    ambiguousCorrelation,
+    degraded,
+    truncated,
+    crossScope,
+    incomplete: grade === 'severed' || degraded || truncated,
+  };
+}
+
+/**
+ * §16.4. Grade one reconstructed `Path`. The path's grade is the WORST of
+ * its hops' — `protection.js`'s `aggregateVerdicts` risk-precedence
+ * reduction, applied to the one axis FR-306 governs.
+ *
+ * Counts are recomputed from `gradeHop`, deliberately NOT read off the
+ * Path's own `widenedHopCount`/`lossHopCount`. `path-query.js`'s own
+ * `materialize()` now computes those fields annotation-aware too (§16.7
+ * Finding 1 / §16.8 item 7), so as of this module the two sources agree —
+ * but `gradePath` still computes its own union rather than re-coupling
+ * itself to `Path`'s fields: grading is what OWNS this union by design
+ * (§16.5), and a caller that can grade a raw `PathStore` edge with no
+ * `Path` at all (`C6/11`) must not depend on a `Path`-shaped count that
+ * doesn't exist for that input.
+ */
+export function gradePath(path) {
+  const hops = Array.isArray(path.hops) ? path.hops : [];
+  const hopGrades = hops.map((h) => gradeHop(h));
+  const grade = aggregateFlowGrades(hopGrades.map((g) => g.grade));
+  const complete = path.complete === true;
+  const analysisTruncated = path.analysisTruncated === true;
+  const factors = _sortedUnion(
+    hopGrades.flatMap((g) => g.factors),
+    complete ? [] : ['partial-path'],
+    analysisTruncated ? ['analysis-truncated'] : [],
+  );
+  return {
+    grade,
+    rank: flowGradeRank(grade),
+    // §16.4 (fix round 1, finding 3): the FULL `HopGrade` objects, in path
+    // order — not a parallel array of bare grade strings. A bare-string
+    // array loses per-hop CAUSE, forcing every caller that wants to render
+    // FR-306's "visually distinct" half to re-invoke `gradeHop` per hop and
+    // re-derive what this function already computed.
+    hops: hopGrades,
+    worstHopIndex: hopGrades.findIndex((g) => g.grade === grade),
+    factors,
+    widenedHopCount: hopGrades.filter((g) => g.widenReasons.length > 0).length,
+    lossHopCount: hopGrades.filter((g) => g.lossReasons.length > 0).length,
+    implicitHopCount: hopGrades.filter((g) => g.implicitReasons.length > 0).length,
+    ambiguousHopCount: hopGrades.filter((g) => g.ambiguousCorrelation).length,
+    degradedHopCount: hopGrades.filter((g) => g.degraded).length,
+    truncatedHopCount: hopGrades.filter((g) => g.truncated).length,
+    degraded: hopGrades.some((g) => g.degraded),
+    truncated: analysisTruncated || hopGrades.some((g) => g.truncated),
+    complete,
+    incomplete: !complete || analysisTruncated || hopGrades.some((g) => g.incomplete),
+  };
+}

package/src/lineage/governance-edit.js

@@ -0,0 +1,169 @@
+// governance-edit.js — M5 deliverable #5 (PRD line 1324's 5-part write
+// contract: preview, validation, backup/version guard, confirmation,
+// audit event). A CLI-only workflow for proposing a validated,
+// reviewable edit to recipient-profiles.json — the one governance
+// config file this codebase already has real, tested per-entry
+// validation for (isValidRecipientConfigEntry, recipient-registry.js).
+//
+// Deliberately narrower than the PRD's own richer "interactive review/
+// approve UI" vision — the HTTP-server-side interactive write surface
+// (new routes, CSRF protection, a write-authorization mechanism beyond
+// the existing read-only session token) is real, separately-scoped
+// future work, not attempted here. See this sub-project's own scoping
+// doc for the full reasoning: no PRD acceptance criterion gates this
+// deliverable at all, and every M4/M5 deliverable this session has
+// shipped has been CLI-first with zero UI/HTTP-write work.
+//
+// This module is pure — no file I/O, no fs access. The CLI layer
+// (bin/agentic-security.js's cmdGovernancePropose) owns reading the
+// current file, writing the backup, writing the new content, and
+// calling auditCall.
+
+import { isValidRecipientConfigEntry } from './recipient-registry.js';
+
+// Validates the top-level `{recipients: {...}}` container shape — used
+// for BOTH the current on-disk config and the --patch file. A patch is
+// user input the command's whole job is to validate, so it gets no
+// tolerant degradation (fixes I2/I3: previously a patch missing
+// `recipients` entirely, or with `recipients` as an array, degraded
+// silently to an empty no-op write). The CURRENT config gets the same
+// check for a different reason: if its top-level shape is unrecognized
+// (e.g. a typo'd `Recipients` key), the tool must refuse rather than
+// silently treating "no recognizable data" as "start from empty" and
+// overwriting whatever WAS there (this was B1's second live repro —
+// the whole file being replaced under a misspelled key).
+function _validateContainerShape(recipients, label) {
+  if (recipients === undefined) {
+    return [{ key: '(top-level)', message: `${label} is missing a "recipients" object` }];
+  }
+  if (recipients === null || typeof recipients !== 'object' || Array.isArray(recipients)) {
+    return [{ key: '(top-level)', message: `${label}'s "recipients" must be a plain object, not ${Array.isArray(recipients) ? 'an array' : recipients === null ? 'null' : typeof recipients}` }];
+  }
+  const errors = [];
+  for (const key of Object.keys(recipients)) {
+    if (key.length === 0) errors.push({ key, message: `${label} contains an empty-string recipient key, which is never valid` });
+    if (key === '__proto__') errors.push({ key, message: `${label} contains a "__proto__" recipient key, which is never valid` });
+  }
+  return errors;
+}
+
+function _validateEntries(patchRecipients) {
+  const errors = [];
+  for (const [key, entry] of Object.entries(patchRecipients)) {
+    if (entry === null) continue; // explicit deletion marker, not a config entry
+    if (!isValidRecipientConfigEntry(entry)) {
+      errors.push({ key, message: `recipient "${key}" is not a valid recipient-profile-shaped config entry` });
+    }
+  }
+  return errors;
+}
+
+// RFC-7396-style merge patch at the recipient-key level: a non-null
+// patch value REPLACES that key's entire entry; a null value DELETES
+// it; a key the patch never mentions is left untouched. This is the
+// fix for a real data-loss bug (found by this task's own review,
+// live-reproduced): the prior design treated `patch.recipients` as
+// the ENTIRE new recipients object, so omitting a key silently
+// deleted it — a reasonable operator adding one vendor had no reason
+// to expect every other vendor's compliance facts to vanish.
+function _mergeRecipients(currentRecipients, patchRecipients) {
+  const merged = { ...currentRecipients };
+  for (const [key, value] of Object.entries(patchRecipients)) {
+    if (value === null) delete merged[key];
+    else merged[key] = value;
+  }
+  return merged;
+}
+
+// Canonical (key-order-independent) JSON serialization for change
+// detection — mirrors ids.js's own _canon precedent. A hand-authored
+// patch file has no reason to preserve the stored config's own key
+// order, so a raw JSON.stringify comparison would spuriously flag a
+// semantically-unchanged recipient as "changed" (found by the task
+// review, reproduced live). Arrays keep their own order (order is
+// semantically meaningful there — e.g. subprocessorChain); only OBJECT
+// key order is normalized.
+function _canonicalize(value) {
+  if (Array.isArray(value)) return value.map(_canonicalize);
+  if (value && typeof value === 'object') {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) sorted[key] = _canonicalize(value[key]);
+    return sorted;
+  }
+  return value;
+}
+
+function _diffRecipients(currentRecipients, patchRecipients) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  const currentKeys = new Set(Object.keys(currentRecipients));
+  for (const [key, value] of Object.entries(patchRecipients)) {
+    if (value === null) {
+      if (currentKeys.has(key)) removed.push(key);
+      // deleting a key that never existed is a no-op, not reported
+      continue;
+    }
+    if (!currentKeys.has(key)) { added.push(key); continue; }
+    if (JSON.stringify(_canonicalize(currentRecipients[key])) !== JSON.stringify(_canonicalize(value))) {
+      changed.push({ key, before: currentRecipients[key], after: value });
+    }
+  }
+  added.sort();
+  removed.sort();
+  changed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return { added, removed, changed };
+}
+
+/**
+ * Propose a patch to a recipient-profiles.json-shaped config. Pure,
+ * never throws, never touches the filesystem. `currentConfig`/`patch`
+ * are both expected to be `{recipients: {...}}`-shaped — a malformed
+ * top-level shape on EITHER side (missing `recipients`, `recipients`
+ * not a plain object, or an empty-string/`__proto__` recipient key) is
+ * a validation failure (`valid: false`, `merged: null`), never a
+ * silent empty-object fallback. The stored config gets this treatment
+ * so an unrecognized shape (e.g. a typo'd top-level key) refuses to
+ * write rather than being silently treated as "nothing here yet" and
+ * overwritten; the patch gets it because it is user input the command's
+ * whole job is to validate.
+ *
+ * `patch.recipients` is an RFC-7396-style JSON MERGE PATCH against
+ * `currentConfig.recipients`, keyed at the recipient level — never a
+ * full replacement of the whole object: a key present with a non-null
+ * value REPLACES that key's entire entry (never deep-merged within
+ * itself); a key present with value `null` DELETES it (the only way to
+ * remove a recipient); a key the patch never mentions is left
+ * untouched in the merged result. Every OTHER top-level key on the
+ * current config (e.g. `$schema`, `version`) is preserved verbatim into
+ * `merged` — only `recipients` itself is merged.
+ *
+ * Returns `{valid, errors, diff, merged}` — `diff`/`merged` are always
+ * computed when both container shapes are valid, even when `valid` is
+ * false due to a per-entry error, so an operator can see what they
+ * attempted before fixing a validation error. `merged` is `null` only
+ * when there is no safe merge base to compute (a container-shape
+ * failure on either side). `merged`, when non-null, is the full
+ * config-shaped result the caller should write — never the raw patch.
+ */
+export function proposeGovernanceEdit(currentConfig, patch) {
+  const currentContainerErrors = _validateContainerShape(currentConfig?.recipients, 'the current config file');
+  const patchContainerErrors = _validateContainerShape(patch?.recipients, 'the --patch file');
+  if (currentContainerErrors.length || patchContainerErrors.length) {
+    return {
+      valid: false,
+      errors: [...currentContainerErrors, ...patchContainerErrors],
+      diff: { added: [], removed: [], changed: [] },
+      merged: null,
+    };
+  }
+  const currentRecipients = currentConfig.recipients;
+  const patchRecipients = patch.recipients;
+  const entryErrors = _validateEntries(patchRecipients);
+  const diff = _diffRecipients(currentRecipients, patchRecipients);
+  const mergedRecipients = _mergeRecipients(currentRecipients, patchRecipients);
+  // Preserve every OTHER top-level key from the current config verbatim
+  // (e.g. $schema, version) — only `recipients` itself is merged.
+  const merged = { ...(currentConfig && typeof currentConfig === 'object' ? currentConfig : {}), recipients: mergedRecipients };
+  return { valid: entryErrors.length === 0, errors: entryErrors, diff, merged };
+}