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

package/src/lineage/recipient-registry.js

@@ -0,0 +1,394 @@
+// recipient-registry.js — Milestone 4 sub-project: FR-506 ("Third-Party
+// and Cross-Border Intelligence"), Task 2. Resolves a real
+// `RecipientProfile` (Task 1's own extension-contract module,
+// `recipient-profile.js`) from the only two real sources this codebase has
+// for these facts:
+//
+//   1. A small, curated technical-provider catalog, CODE-derived — "what
+//      does the code actually call, and what hostname does the resolved
+//      destination literally name" (`resolveTechnicalProvider`).
+//   2. An operator-declared config file — facts no code path can ever
+//      determine on its own (legal entity, jurisdiction, DPA status, ...)
+//      (`loadRecipientConfig`).
+//
+// `buildRecipientProfile` combines the two into one record, per-field
+// `fieldEvidence` intact, and returns `null` when neither source produced
+// anything for a given sink site — a site with genuinely zero recipient
+// information is not worth minting an all-null record for.
+//
+// ── The curated catalog — precision over recall (disclosed, not guessed) ──
+//
+// Mirrors `transform-catalog.js`'s own established discipline: a short,
+// correct list beats a padded, guessed one. Seeded from real signals only:
+//
+//   - `anthropic` / `openai` — the ONLY two `framework` values in
+//     `dataflow/catalog.js` naming a real AI-provider technical service
+//     (confirmed by reading that file directly: `js-anthropic-messages-
+//     create`, `js-openai-chat-completions-create`,
+//     `js-openai-responses-create`). Matched via BOTH `frameworkNames`
+//     (an exact match against the sink site's own `framework`) and real,
+//     well-known hostnames for each company (not catalog-derived — no
+//     literal hostname string exists anywhere in `catalog.js`/
+//     `privacy-catalog.js`, confirmed by grep; these are ordinary,
+//     well-known, real-world hostnames for real companies).
+//   - Google Cloud Pub/Sub — `privacy-catalog.js`'s `privacy-js-queue-
+//     publish` entry carries `framework: 'pubsub'`, and that value is used
+//     by EXACTLY ONE catalog entry (confirmed by grep) — unambiguous, so
+//     it is matched via `frameworkNames` too.
+//   - Amazon S3 — `privacy-catalog.js`'s `privacy-js-s3-putObject` entry
+//     carries `category: 's3Upload'` (which `sink-registry.js`'s own
+//     `PRIVACY_CATEGORY_MAP` reclassifies to `object-storage`), a real,
+//     already-matched signal for a real external recipient. Matched via
+//     `hostnamePatterns` ONLY, deliberately NOT via `frameworkNames`:
+//     that entry's `framework` value is `'aws-sdk'`, and the IDENTICAL
+//     `'aws-sdk'` value is ALSO used by `privacy-js-queue-sendMessage`
+//     (Amazon SQS) — genuinely ambiguous, since one `framework` string
+//     names two different AWS services with two different `serviceType`s.
+//     A `frameworkNames: ['aws-sdk']` catalog entry would silently
+//     mislabel whichever of {S3, SQS} it didn't intend, so this module
+//     never keys on it at all. No SQS catalog entry is added either — the
+//     brief names only S3 as worth considering, and adding a second AWS
+//     entry off the same disclosed ambiguity would be scope creep beyond
+//     what was actually verified.
+//
+// Disclosed gaps, not guessed at: `mongodb` (storage) and `nodemailer`
+// (email) are genuinely ambiguous — either could be self-hosted or a
+// third-party managed service, and neither entry's own `framework` value
+// reliably names ONE external company the way `anthropic`/`openai`/
+// `pubsub` do — so both are left out. Google Cloud Storage
+// (`storage.googleapis.com`) is also left out: no catalog entry anywhere
+// in this codebase names it (confirmed by grep), so a hostname pattern for
+// it would be an invented signal, not a real one. Stripe/Sentry/Datadog/
+// etc. appear only inside `privacy-js-analytics-track`/`-identify`'s
+// `receiverTypeIn` regex alternation, all sharing ONE `framework` value
+// (`'analytics'`) that cannot distinguish which specific company matched
+// at a given call site — too coarse to use.
+//
+// ── Reuse boundary ──────────────────────────────────────────────────────
+//
+// Imports ONLY `node:fs`, `./recipient-profile.js` (the enums this module
+// validates operator config entries against), `./ids.js`
+// (`recipientProfileId`), and `./export-json.js` (`computeGraphDigest`,
+// the SAME `graph?.graphId ?? null` / `computeGraphDigest(graph)` pattern
+// `obligation-predicates.js`'s `buildObligationMappingFromGraphPredicate`
+// already establishes for a §10.10 extension record). Never
+// `dataflow/engine.js`, never `dataflow/summaries.js` — this module reads
+// only the already-resolved `site`/`graph` shapes other modules hand it.
+
+import * as fs from 'node:fs';
+import {
+  RECIPIENT_PROCESSOR_ROLES,
+  RECIPIENT_DPA_STATUSES,
+  RECIPIENT_CONFIDENCE_LEVELS,
+} from './recipient-profile.js';
+import { recipientProfileId } from './ids.js';
+import { computeGraphDigest } from './export-json.js';
+
+export const RECIPIENT_CONFIG_FILENAME = 'recipient-profiles.json';
+
+// =========================================================================
+// The curated technical-provider catalog.
+// =========================================================================
+
+// Each pattern is tested against the BARE HOSTNAME extracted from
+// `literalValue` via `_bareHostname` (fix-round-1, I4 — testing the RAW
+// literal string let a path/query-embedded lookalike like
+// 'https://attacker.io/anthropic.com' incorrectly match) via
+// `new RegExp(p, 'i').test(...)`, so every pattern anchors on a domain
+// BOUNDARY (`(^|[./])`, start-of-string or a literal dot) before the
+// hostname and a domain terminator (`(?=[:/]|$)`, a port/path separator
+// or end-of-string) after it — never a bare `$'` end anchor, which would
+// only ever match a bareHost string containing nothing but the hostname
+// (still correct against a bare host, since that's exactly what it is
+// now).
+export const TECHNICAL_PROVIDER_CATALOG = Object.freeze([
+  Object.freeze({
+    provider: 'anthropic',
+    serviceType: 'ai-model-provider',
+    hostnamePatterns: ['(^|[./])anthropic\\.com(?=[:/]|$)'],
+    frameworkNames: ['anthropic'],
+  }),
+  Object.freeze({
+    provider: 'openai',
+    serviceType: 'ai-model-provider',
+    hostnamePatterns: ['(^|[./])openai\\.com(?=[:/]|$)'],
+    frameworkNames: ['openai'],
+  }),
+  Object.freeze({
+    provider: 'Google Cloud Pub/Sub',
+    serviceType: 'message-queue',
+    hostnamePatterns: ['(^|[./])pubsub\\.googleapis\\.com(?=[:/]|$)'],
+    frameworkNames: ['pubsub'],
+  }),
+  Object.freeze({
+    provider: 'Amazon S3',
+    serviceType: 'object-storage',
+    // Hostname-only, deliberately — see the header comment's explanation
+    // of why 'aws-sdk' is never used as a frameworkNames match. Covers
+    // the plain (`s3.amazonaws.com`), region-qualified
+    // (`s3.us-west-2.amazonaws.com` / `s3-us-west-2.amazonaws.com`), and
+    // bucket-prefixed virtual-hosted (`my-bucket.s3[...].amazonaws.com`)
+    // real URL shapes in one pattern.
+    hostnamePatterns: ['(^|[./])s3([.-][a-z0-9-]+)?\\.amazonaws\\.com(?=[:/]|$)'],
+    frameworkNames: [],
+  }),
+]);
+
+/**
+ * `resolveTechnicalProvider({framework, literalValue}) ->
+ * {provider, serviceType} | null` — never throws. Matches EITHER a
+ * catalog entry's own `frameworkNames` (exact match against the sink
+ * site's own `framework`, checked first) OR a `hostnamePatterns` regex
+ * test against `literalValue` (when a framework match didn't already
+ * resolve it). Returns `null` on no match — never a guess.
+ */
+export function resolveTechnicalProvider(input) {
+  try {
+    const framework = input && typeof input === 'object' ? input.framework : undefined;
+    const literalValue = input && typeof input === 'object' ? input.literalValue : undefined;
+
+    if (typeof framework === 'string' && framework.length > 0) {
+      const byFramework = TECHNICAL_PROVIDER_CATALOG.find((e) => e.frameworkNames.includes(framework));
+      if (byFramework) return { provider: byFramework.provider, serviceType: byFramework.serviceType };
+    }
+
+    if (typeof literalValue === 'string' && literalValue.length > 0) {
+      // fix-round-1, I4: match against the BARE HOSTNAME, never the raw
+      // literal — testing the whole string let
+      // 'https://attacker.io/anthropic.com' (a path, not a host) and
+      // 'https://attacker.io/proxy?to=https://api.anthropic.com' (a query
+      // value) both incorrectly match the Anthropic pattern, attaching a
+      // real company's operator-declared legal/DPA facts to a flow whose
+      // actual destination is attacker.io. `_bareHostname` is defined
+      // below in this same file and hoisted, so it's callable from here.
+      const bareHost = _bareHostname(literalValue) ?? '';
+      const byHost = TECHNICAL_PROVIDER_CATALOG.find((e) =>
+        e.hostnamePatterns.some((p) => new RegExp(p, 'i').test(bareHost)));
+      if (byHost) return { provider: byHost.provider, serviceType: byHost.serviceType };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// =========================================================================
+// A tiny, local bare-hostname extractor — no URL-parsing dependency, per
+// this codebase's established zero-new-dependencies precedent. Handles a
+// scheme-prefixed URL, a bare host, and strips a trailing path/query/
+// fragment/port. Not a general URL parser — good enough for the one thing
+// this module needs it for (a `recipientKey` fallback).
+// =========================================================================
+
+function _bareHostname(literalValue) {
+  if (typeof literalValue !== 'string' || literalValue.length === 0) return null;
+  const withoutScheme = literalValue.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, '');
+  const host = withoutScheme.split(/[/?#]/)[0].split(':')[0].trim();
+  return host.length > 0 ? host.toLowerCase() : null;
+}
+
+// =========================================================================
+// loadRecipientConfig — mirrors drift-policy.js's loadDriftPolicies
+// EXACTLY: never throws; a missing file degrades to the empty shape; a
+// malformed-JSON file logs a warning and degrades to the empty shape; each
+// individual recipient entry is validated loosely, and a malformed one is
+// SKIPPED IN ITS ENTIRETY (never just one bad field) with a warning naming
+// the count — mirroring loadDriftPolicies' own per-entry (not per-field)
+// skip discipline. `recipients` is an OBJECT keyed by recipientKey (not an
+// array like `policies`), so this iterates `Object.entries` rather than
+// `.filter()`s an array — the fail-closed philosophy is identical.
+// =========================================================================
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isStringOrNull(v) { return v === null || v === undefined || typeof v === 'string'; }
+function _isStringArray(v) { return Array.isArray(v) && v.every((x) => typeof x === 'string'); }
+function _isCountryArray(v) { return Array.isArray(v) && v.every((c) => typeof c === 'string' && /^[A-Z]{2}$/.test(c)); }
+
+// The complete set of operator-declarable fields, per the task brief's own
+// config shape — a 1:1 mapping onto RecipientProfile fields this module
+// can ONLY ever fill from operator config (the fact fields) plus the five
+// record-level metadata fields (confidence/owner/reviewDate/conflicts/
+// expiration), which need no fieldEvidence of their own (see
+// recipient-profile.js's own header comment on why those five are
+// excluded from RECIPIENT_FACT_FIELDS).
+// fix-round-1, M7: `servicePurpose`/`observedRegion` were both real
+// RECIPIENT_FACT_FIELDS (recipient-profile.js) and both real fields
+// `buildRecipientProfile`'s own `facts` object initializes below, but were
+// missing from this list — an operator declaring either in
+// recipient-profiles.json had it silently ignored (never validated, never
+// copied into the built profile).
+const _RECIPIENT_CONFIG_FACT_FIELDS = Object.freeze([
+  'legalEntity', 'processorRole', 'servicePurpose', 'subprocessorChain', 'processingCountries',
+  'dataResidencyCommitment', 'observedRegion', 'dpaStatus', 'transferMechanism',
+  'transferImpactReviewStatus', 'retentionCommitment',
+]);
+// The remaining five operator-declarable fields — confidence/owner/
+// reviewDate/conflicts/expiration — are record-level metadata, copied
+// directly in buildRecipientProfile's own return literal below with no
+// fieldEvidence entry, per recipient-profile.js's own header comment.
+
+/**
+ * Validates one recipient-config entry against Task 1's own real enums.
+ * Fail-closed per the brief's own instruction: a malformed value on ANY
+ * field skips the WHOLE entry (never just that one field) — the simpler,
+ * more conservative of the two options the brief names, and the one that
+ * mirrors `loadDriftPolicies`' own "validate the whole shape, skip the
+ * whole entry on a defect" discipline most closely.
+ */
+export function isValidRecipientConfigEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+  if (!_isStringOrNull(entry.legalEntity)) return false;
+  if (entry.processorRole != null && !RECIPIENT_PROCESSOR_ROLES.includes(entry.processorRole)) return false;
+  if (!_isStringOrNull(entry.servicePurpose)) return false;
+  if (entry.subprocessorChain != null && !_isStringArray(entry.subprocessorChain)) return false;
+  if (entry.processingCountries != null && !_isCountryArray(entry.processingCountries)) return false;
+  if (!_isStringOrNull(entry.dataResidencyCommitment)) return false;
+  if (!_isStringOrNull(entry.observedRegion)) return false;
+  if (entry.dpaStatus != null && !RECIPIENT_DPA_STATUSES.includes(entry.dpaStatus)) return false;
+  if (!_isStringOrNull(entry.transferMechanism)) return false;
+  if (!_isStringOrNull(entry.transferImpactReviewStatus)) return false;
+  if (!_isStringOrNull(entry.retentionCommitment)) return false;
+  if (entry.confidence != null && !RECIPIENT_CONFIDENCE_LEVELS.includes(entry.confidence)) return false;
+  if (!_isStringOrNull(entry.owner)) return false;
+  if (!_isStringOrNull(entry.reviewDate)) return false;
+  if (entry.conflicts != null && !_isStringArray(entry.conflicts)) return false;
+  if (!_isStringOrNull(entry.expiration)) return false;
+  return true;
+}
+
+export function loadRecipientConfig(configFilePath) {
+  const EMPTY = { recipients: {} };
+  if (!configFilePath) return EMPTY;
+
+  let raw = null;
+  try {
+    raw = JSON.parse(fs.readFileSync(configFilePath, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      console.error(`agentic-security: bad JSON in recipient config file (${configFilePath}) — falling back to no recipients (${e.message})`);
+    }
+    return EMPTY;
+  }
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !raw.recipients || typeof raw.recipients !== 'object' || Array.isArray(raw.recipients)) {
+    console.error(`agentic-security: recipient config file ${configFilePath} has no "recipients" object — falling back to no recipients (expected {"recipients": {...}})`);
+    return EMPTY;
+  }
+
+  const recipients = {};
+  let skipped = 0;
+  for (const [key, entry] of Object.entries(raw.recipients)) {
+    if (!_isNonEmptyString(key) || !isValidRecipientConfigEntry(entry)) {
+      skipped += 1;
+      continue;
+    }
+    recipients[key] = entry;
+  }
+  if (skipped > 0) {
+    console.error(`agentic-security: skipped ${skipped} malformed recipient-config entr${skipped === 1 ? 'y' : 'ies'} in ${configFilePath} (each must be a valid recipient-profile-shaped object)`);
+  }
+  return { recipients };
+}
+
+// =========================================================================
+// buildRecipientProfile — the real resolution function.
+// =========================================================================
+
+/**
+ * `buildRecipientProfile(site, graph, opts) -> RecipientProfile | null`.
+ *
+ * `site` is the shape `graph-builder.js`'s `enumerateSinkSites` produces:
+ * `{file, qid, nodeId, line, calleeExpr, args, entry, decision, ambiguity,
+ * destination?}` — `entry` is the RAW catalog entry (where `framework`
+ * actually lives, `site.entry.framework`, never `site.framework`);
+ * `destination`, when present, is `resolve-destination.js`'s own
+ * `{resolutionStatus, raw, literalValue, blockingExpression}` shape and
+ * may be `undefined` if resolution was never attempted.
+ *
+ * `graph` is a built `DataFlowGraph v1` document (or `graphAfter` in a
+ * diff context) — used only for `graphId`/`graphDigest`, mirroring
+ * `obligation-predicates.js`'s own `graph?.graphId ?? null` /
+ * `graph ? computeGraphDigest(graph) : null` pattern exactly. `graph` may
+ * be omitted/null; the record still builds, honestly labeled `'(no
+ * graph)'` (that same precedent's own fallback literal).
+ *
+ * `opts.recipientConfig` is `loadRecipientConfig`'s own return shape
+ * (`{recipients: {...}}`) — omitted/malformed degrades to "no operator
+ * declarations", never a throw.
+ */
+export function buildRecipientProfile(site, graph, opts = {}) {
+  if (!site || typeof site !== 'object') return null;
+
+  const framework = site.entry && typeof site.entry === 'object' ? site.entry.framework : undefined;
+  const destination = site.destination && typeof site.destination === 'object' ? site.destination : null;
+  const literalValue = destination && destination.resolutionStatus === 'literal' && typeof destination.literalValue === 'string'
+    ? destination.literalValue
+    : null;
+
+  const techMatch = resolveTechnicalProvider({ framework, literalValue });
+
+  let recipientKey = null;
+  if (techMatch && typeof techMatch.provider === 'string' && techMatch.provider.length > 0) {
+    recipientKey = techMatch.provider;
+  } else {
+    recipientKey = _bareHostname(literalValue);
+  }
+  if (!recipientKey) return null; // no key, no profile — never fabricate one
+
+  const recipients = opts && opts.recipientConfig && typeof opts.recipientConfig === 'object' && opts.recipientConfig.recipients
+    && typeof opts.recipientConfig.recipients === 'object'
+    ? opts.recipientConfig.recipients
+    : null;
+  const configEntry = recipients ? recipients[recipientKey] : null;
+
+  if (!techMatch && !configEntry) return null; // genuinely nothing to say about this site
+
+  const fieldEvidence = {};
+  const facts = {
+    technicalEndpoint: null, provider: null, serviceType: null, legalEntity: null,
+    processorRole: null, servicePurpose: null, subprocessorChain: [],
+    processingCountries: [], dataResidencyCommitment: null, observedRegion: null,
+    dpaStatus: null, transferMechanism: null, transferImpactReviewStatus: null,
+    retentionCommitment: null,
+  };
+
+  if (techMatch) {
+    facts.provider = techMatch.provider;
+    facts.serviceType = techMatch.serviceType;
+    fieldEvidence.provider = { factType: 'code_inferred', source: 'recipient-registry:catalog' };
+    fieldEvidence.serviceType = { factType: 'code_inferred', source: 'recipient-registry:catalog' };
+    if (literalValue) {
+      facts.technicalEndpoint = literalValue;
+      fieldEvidence.technicalEndpoint = { factType: 'code_inferred', source: 'recipient-registry:catalog' };
+    }
+  }
+
+  if (configEntry) {
+    for (const field of _RECIPIENT_CONFIG_FACT_FIELDS) {
+      const value = configEntry[field];
+      const populated = Array.isArray(value) ? value.length > 0 : (value !== null && value !== undefined);
+      if (!populated) continue;
+      facts[field] = value;
+      fieldEvidence[field] = { factType: 'declared', source: RECIPIENT_CONFIG_FILENAME };
+    }
+  }
+
+  const graphId = graph && typeof graph === 'object' ? (graph.graphId ?? null) : null;
+  const graphDigest = graph && typeof graph === 'object' ? computeGraphDigest(graph) : null;
+
+  return {
+    id: recipientProfileId({ graphId: graphId ?? '', graphDigest: graphDigest ?? '', recipientKey }),
+    graphId: graphId ?? '(no graph)',
+    graphDigest: graphDigest ?? '(no graph)',
+    recipientKey,
+    ...facts,
+    fieldEvidence,
+    contributingGraphIds: [],
+    confidence: configEntry && configEntry.confidence != null ? configEntry.confidence : null,
+    owner: configEntry && configEntry.owner != null ? configEntry.owner : null,
+    reviewDate: configEntry && configEntry.reviewDate != null ? configEntry.reviewDate : null,
+    conflicts: configEntry && Array.isArray(configEntry.conflicts) ? configEntry.conflicts : [],
+    expiration: configEntry && configEntry.expiration != null ? configEntry.expiration : null,
+  };
+}

package/src/lineage/redact-graph.js

@@ -0,0 +1,224 @@
+// redact-graph.js — Milestone 4. Shared redaction logic for the
+// DataFlowGraph v1 artifact, extracted from the MCP-tools sub-project's
+// own dataflow-tools.js (where a whole-branch security review found and
+// fixed the real gap this logic closes — see that sub-project's own
+// CLAUDE.md section, "Dataflow-tools redaction scope"). Any export path
+// that returns graph content to a consumer outside the scan process must
+// reuse this module rather than re-deriving redaction logic — that is
+// exactly the "two near-identical copies" bug class this extraction
+// exists to prevent (the same bug class M3-UX-Filters' own
+// `rowMatchesFilters` duplication hit once already this session).
+
+import { redactString } from '../mcp/redact.js';
+
+// Redacts every scanned-source-derived string field on a COPY of the data
+// being returned — never mutates the loaded graph object, which may be
+// reused across calls within the same process lifetime by other callers.
+//
+// Real source-derived surfaces, confirmed by reading the graph pipeline
+// directly (the destination/evidence findings are from the MCP-tools
+// sub-project's own follow-up security review; the blockingExpression,
+// queueDetail/storeDetail, and coverageReason findings are from the
+// JSON/CSV export sub-project's own final whole-branch review AND its own
+// scoped re-review — the re-review found `coverageReason` carrying the
+// SAME unredacted string as an already-redacted `blockingExpression` on
+// the same object, the identical bug class surviving one review round
+// after the first fix, on a different field — do not repeat that
+// mistake a third time; re-verify against the real pipeline before
+// trusting this list again in the future):
+//   - `node.destination.raw`/`.literalValue`/`.blockingExpression` —
+//     resolve-destination.js's `resolveDestination()` lifts these straight
+//     out of scanned call-site arguments (`renderExpr(arg0)` /
+//     `String(arg0.value)`); a hardcoded connection string, webhook URL,
+//     or API-key literal used as a destination argument lands here
+//     verbatim. `blockingExpression` is NOT a derived/summary field — for
+//     a `'dynamic'` resolution, `resolve-destination.js` sets it to the
+//     IDENTICAL string as `raw` (confirmed by direct read), so omitting it
+//     was a real, exploitable redaction bypass (the whole-branch review's
+//     own repro: `raw` redacted, `blockingExpression` carrying the same
+//     un-redacted secret verbatim on the very same object).
+//   - `node.queueDetail.topic` — `graph-builder.js`'s `extractQueueDetail`
+//     lifts this verbatim from a scanned call-site's own object-literal
+//     argument (`QueueUrl`/`TopicArn`/`topic`/`queueName`), the identical
+//     "literal argument value" shape `destination.literalValue` already
+//     covers, just on a different node field.
+//   - `node.storeDetail.table`/`.columns` — `graph-builder.js`'s ORM-write
+//     extraction lifts these from a scanned receiver identifier and
+//     object-literal property keys. Lower risk than the fields above (an
+//     identifier/property name, not typically a secret-shaped literal),
+//     but still genuinely scanned-source text — redacted defensively for
+//     the same reason `evidence[].snippet` is, even though no known
+//     producer currently emits a secret-shaped table/column name.
+//   - `node.coverageReason` — `sink-registry.js`'s FR-203 branch builds
+//     this as `` `destination could not be statically resolved: ${blockingExpression}` ``
+//     (confirmed at sink-registry.js's own FR-203 reason-string site,
+//     threaded through coverage.js/graph-builder.js to `node.coverageReason`
+//     at mint time) — the SAME secret content `destination.blockingExpression`
+//     already carries, copied verbatim into a second, unrelated-looking
+//     field on the same node. A caller who trusts `destination` alone is
+//     redacted correctly still gets the identical secret back via this
+//     field. Proven live by the scoped re-review that found this gap.
+//   - `graph.recipientProfiles[].technicalEndpoint`/`.legalEntity`/
+//     `.retentionCommitment`/`.transferMechanism` — fix-round-1 finding B1
+//     (Milestone 4, FR-506): `technicalEndpoint` is lifted verbatim from a
+//     resolved destination literal by `recipient-registry.js`'s
+//     `buildRecipientProfile`, the SAME "literal URL/hostname lifted from
+//     scanned code" shape `node.destination.literalValue` already
+//     redacts, so it reached `dataflow_get_graph` unredacted for a whole
+//     review round before this was caught. The other three fields are
+//     operator-declared free text, covered defensively.
+//   - `evidence[].claim` — composed from resolved values in
+//     graph-builder.js; can echo the same literal content.
+//   - `evidence[].location.note` / `.snippet` — schema-declared free-text
+//     fields; `.note` is fixture-only today (the real emitter uses
+//     `{file,line}`, never `{note}`) and `.snippet` is always null today,
+//     but both are declared string fields a future evidence producer could
+//     populate with raw source text, so both stay defensively redacted
+//     rather than trusting today's producers to never change.
+function _redactDestination(d) {
+  if (!d) return d;
+  const hasRedactable = typeof d.raw === 'string' || typeof d.literalValue === 'string' || typeof d.blockingExpression === 'string';
+  if (!hasRedactable) return d;
+  return {
+    ...d,
+    raw: typeof d.raw === 'string' ? redactString(d.raw) : d.raw,
+    literalValue: typeof d.literalValue === 'string' ? redactString(d.literalValue) : d.literalValue,
+    blockingExpression: typeof d.blockingExpression === 'string' ? redactString(d.blockingExpression) : d.blockingExpression,
+  };
+}
+
+function _redactQueueDetail(q) {
+  if (!q || typeof q.topic !== 'string') return q;
+  return { ...q, topic: redactString(q.topic) };
+}
+
+function _redactStoreDetail(s) {
+  if (!s) return s;
+  return {
+    ...s,
+    table: typeof s.table === 'string' ? redactString(s.table) : s.table,
+    columns: Array.isArray(s.columns) ? s.columns.map((c) => (typeof c === 'string' ? redactString(c) : c)) : s.columns,
+  };
+}
+
+export function _redactNode(node) {
+  const hasRedactable = node?.destination || node?.queueDetail || node?.storeDetail || typeof node?.coverageReason === 'string';
+  if (!hasRedactable) return node;
+  const out = { ...node };
+  // Only overwrite a key that was actually present on the input — never
+  // inject a `key: undefined` own-property onto a node that never had it
+  // (found by the scoped re-review: unconditionally writing `destination`/
+  // `queueDetail`/`storeDetail` added an own `undefined` value even when
+  // absent from the source node, which JSON.stringify silently drops but
+  // which could still trip a `hasOwnProperty` structural check elsewhere,
+  // e.g. validate.js's own storeDetail.columns guard).
+  if ('destination' in node) out.destination = _redactDestination(node.destination);
+  if ('queueDetail' in node) out.queueDetail = _redactQueueDetail(node.queueDetail);
+  if ('storeDetail' in node) out.storeDetail = _redactStoreDetail(node.storeDetail);
+  if (typeof node.coverageReason === 'string') out.coverageReason = redactString(node.coverageReason);
+  return out;
+}
+
+export function _redactEvidence(evidence) {
+  if (!Array.isArray(evidence)) return evidence;
+  return evidence.map((e) => {
+    if (!e || typeof e !== 'object') return e;
+    return {
+      ...e,
+      claim: typeof e.claim === 'string' ? redactString(e.claim) : e.claim,
+      snippet: typeof e.snippet === 'string' ? redactString(e.snippet) : e.snippet,
+      location: e.location?.note
+        ? { ...e.location, note: redactString(e.location.note) }
+        : e.location,
+    };
+  });
+}
+
+// Milestone 4, fix-round 1, B1: `graph.recipientProfiles[]` (FR-506) is a
+// real scanned-source-derived surface `_redactGraph` never touched —
+// `technicalEndpoint` is lifted verbatim from a resolved destination
+// literal by `recipient-registry.js`'s `buildRecipientProfile` (the exact
+// same "literal URL/hostname lifted from scanned code" shape
+// `node.destination.literalValue` already redacts above), so it can
+// carry an embedded credential/token just as easily. `legalEntity`/
+// `retentionCommitment`/`transferMechanism` are operator-declared free
+// text from `recipient-profiles.json`, not scanned-source-derived — but
+// `redactString` is pattern-based and a safe no-op on ordinary text
+// (confirmed by reading `mcp/redact.js`), so covering them defensively
+// costs nothing. Not exported: called only from `_redactGraph` below,
+// the same "internal helper" precedent `_redactDestination`/
+// `_redactQueueDetail`/`_redactStoreDetail` already establish in this
+// file (unlike `_redactNode`/`_redactEvidence`, which ARE exported
+// because callers outside this module invoke them directly).
+function _redactRecipientProfile(p) {
+  if (!p) return p;
+  const hasRedactable = typeof p.technicalEndpoint === 'string'
+    || typeof p.legalEntity === 'string'
+    || typeof p.retentionCommitment === 'string'
+    || typeof p.transferMechanism === 'string';
+  if (!hasRedactable) return p;
+  return {
+    ...p,
+    technicalEndpoint: typeof p.technicalEndpoint === 'string' ? redactString(p.technicalEndpoint) : p.technicalEndpoint,
+    legalEntity: typeof p.legalEntity === 'string' ? redactString(p.legalEntity) : p.legalEntity,
+    retentionCommitment: typeof p.retentionCommitment === 'string' ? redactString(p.retentionCommitment) : p.retentionCommitment,
+    transferMechanism: typeof p.transferMechanism === 'string' ? redactString(p.transferMechanism) : p.transferMechanism,
+  };
+}
+
+// CrossRepoLink redaction (final whole-branch review, M5 deliverable
+// #8, B2; extended in a second fix round after the round-1 re-review
+// found `remote.sourceFile`/`declaredBy` still leaking). Two DIFFERENT
+// treatments for two DIFFERENT kinds of field:
+//   - `rationale`/`remote.repository` are genuine operator-declared free
+//     text — `redactString` (pattern-based secret scrubbing) is the
+//     correct, established treatment, same precedent
+//     `_redactRecipientProfile` already uses for similarly-shaped
+//     fields; a safe no-op on ordinary text.
+//   - `remote.sourceFile` (a real local filesystem path) and
+//     `declaredBy` (a real OS username, from `process.env.USER`/
+//     `USERNAME`) are STRUCTURALLY guaranteed to carry machine-layout/
+//     identity information regardless of content — no secret PATTERN
+//     to match, so `redactString` is a no-op on them by construction,
+//     which is exactly the round-1 mistake this round fixes. These two
+//     get UNCONDITIONAL full-token replacement whenever present, never
+//     partial pattern-based scrubbing — there is no "clean" version of
+//     a local path or username worth preserving in an exported artifact
+//     (the REAL value is still needed internally by `federate list`
+//     re-validation, which reads the stored `cross-repo-links.json`
+//     directly, never this redacted export view).
+function _redactCrossRepoLink(link) {
+  if (!link) return link;
+  const hasRedactable = typeof link.rationale === 'string'
+    || typeof link.declaredBy === 'string'
+    || (link.remote && typeof link.remote.sourceFile === 'string')
+    || (link.remote && typeof link.remote.repository === 'string');
+  if (!hasRedactable) return link;
+  return {
+    ...link,
+    rationale: typeof link.rationale === 'string' ? redactString(link.rationale) : link.rationale,
+    declaredBy: typeof link.declaredBy === 'string' ? '[REDACTED:username]' : link.declaredBy,
+    remote: link.remote ? {
+      ...link.remote,
+      sourceFile: typeof link.remote.sourceFile === 'string' ? '[REDACTED:local-path]' : link.remote.sourceFile,
+      repository: typeof link.remote.repository === 'string' ? redactString(link.remote.repository) : link.remote.repository,
+    } : link.remote,
+  };
+}
+
+// Full-graph redaction: every node's destination, the top-level evidence
+// array, (fix-round 1, B1) recipientProfiles[], and (final review, M5 #8
+// B2) crossRepoLinks[]. Edges/flows carry only evidenceRefs (id strings
+// into graph.evidence), never embedded evidence objects or
+// destination-shaped fields — confirmed against dataflow-graph.schema.json
+// — so they need no redaction pass of their own here.
+export function _redactGraph(data) {
+  if (!data) return data;
+  return {
+    ...data,
+    nodes: Array.isArray(data.nodes) ? data.nodes.map(_redactNode) : data.nodes,
+    evidence: _redactEvidence(data.evidence),
+    recipientProfiles: Array.isArray(data.recipientProfiles) ? data.recipientProfiles.map(_redactRecipientProfile) : data.recipientProfiles,
+    crossRepoLinks: Array.isArray(data.crossRepoLinks) ? data.crossRepoLinks.map(_redactCrossRepoLink) : data.crossRepoLinks,
+  };
+}