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

package/dist/frontend/src/export-entry.js

@@ -0,0 +1,36 @@
+// export-entry.js — Milestone 4, sub-project Self-contained HTML report.
+//
+// The entry point for a bundled, offline, self-contained export — NOT
+// main.js, which is the `explore`-server-specific entry point (token
+// extraction + authenticated fetch, both irrelevant and unavailable
+// offline). This file's only job: read the graph the report generator
+// embedded as a global, and call the SAME, UNCHANGED bootstrap() every
+// other entry point uses.
+//
+// `window.__AGENTIC_SECURITY_EXPORTED_GRAPH__` is set by an inline
+// <script> the report generator writes BEFORE this bundled script in the
+// emitted HTML — see scanner/scripts/generate-html-report.mjs.
+import { bootstrap } from './app.js';
+import { el, clear } from './lib/dom.js';
+
+function showError(rootEl, message) {
+  clear(rootEl);
+  rootEl.appendChild(el('div', { class: 'app-error' }, [
+    el('div', { class: 'app-error__title' }, 'Data Flow Explorer report could not load'),
+    el('div', { class: 'app-error__message' }, message),
+  ]));
+}
+
+function init() {
+  const rootEl = document.getElementById('app-root');
+  const graph = typeof window !== 'undefined' ? window.__AGENTIC_SECURITY_EXPORTED_GRAPH__ : undefined;
+  if (!graph) {
+    showError(rootEl, 'No embedded graph data found in this report file. It may be corrupted — regenerate it with `agentic-security` and open the new file.');
+    return;
+  }
+  bootstrap(rootEl, graph);
+}
+
+if (typeof document !== 'undefined' && typeof document.getElementById === 'function' && document.getElementById('app-root')) {
+  init();
+}

package/dist/frontend/src/lib/api-client.js

@@ -0,0 +1,92 @@
+// api-client.js — Milestone 3, sub-project Wire.
+//
+// The frontend's entire integration surface with the `explore` server
+// (scanner/src/server/). Two small functions: extract the session token
+// once from the URL fragment, then use it to fetch the graph. Every other
+// view's own rendering code stays untouched — this file is the whole
+// integration point (see the M3-Wire scoping doc's Decision 3).
+//
+// The session token travels via the URL FRAGMENT (`#token=<hex>`), never a
+// query string or a cookie — a URL fragment is never sent to the server in
+// any HTTP request, so the initial page-load request itself cannot leak the
+// token into a server access log, yet the fragment IS readable by this
+// page's own JS via `location.hash` (see Decision 1).
+
+const TOKEN_HEADER = 'x-agentic-security-token';
+
+/**
+ * Parses `location.hash` (or an explicitly-supplied hash string, for
+ * testing) for a `#token=<64-hex-char>` parameter. Other params (e.g.
+ * `view`/`selected`/`filters`, which shell.js starts writing into the same
+ * hash after the first render) are ignored here — this function only ever
+ * cares about `token`.
+ *
+ * @param {string} [hash] - defaults to the real `location.hash` in a browser
+ * @returns {string|null} the token, or null if absent/malformed
+ */
+export function extractTokenFromFragment(hash = (typeof location !== 'undefined' ? location.hash : '')) {
+  const raw = String(hash ?? '').replace(/^#/, '');
+  if (!raw) return null;
+
+  let params;
+  try {
+    params = new URLSearchParams(raw);
+  } catch {
+    return null;
+  }
+
+  const token = params.get('token');
+  if (!token || !/^[0-9a-f]{64}$/i.test(token)) return null;
+  return token;
+}
+
+/**
+ * Fetches the full graph from the explore server's `GET /api/v1/graph`
+ * endpoint, authenticating via the `x-agentic-security-token` header (never
+ * a query string), and unwraps the response envelope's `.data` field (see
+ * scanner/src/server/routes.js's `wrapResponse`) to hand back the plain
+ * graph object `bootstrap()` already expects.
+ *
+ * @param {object} opts
+ * @param {string} opts.token - required
+ * @param {string} [opts.baseUrl=''] - defaults to a relative fetch against
+ *   the page's own origin, which is the ONLY thing a real browser page is
+ *   ever expected to pass (same-origin, per the M3-Wire scoping doc's
+ *   load-bearing CORS-disabled correction). Overridable so a real live-HTTP
+ *   test can point this at a real running server without a headless
+ *   browser — never used by the shipped frontend itself.
+ * @returns {Promise<object>} the plain graph object
+ */
+export async function fetchGraph({ token, baseUrl = '' } = {}) {
+  if (!token) {
+    throw new Error('fetchGraph: a session token is required');
+  }
+
+  const res = await fetch(`${baseUrl}/api/v1/graph`, {
+    headers: { [TOKEN_HEADER]: token },
+  });
+
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const body = await res.json();
+      if (body && typeof body.error === 'string') detail = `: ${body.error}`;
+    } catch {
+      /* non-JSON error body — report the status alone */
+    }
+    throw new Error(`fetchGraph: request failed with status ${res.status}${detail}`);
+  }
+
+  let envelope;
+  try {
+    envelope = await res.json();
+  } catch {
+    throw new Error('fetchGraph: response was not valid JSON');
+  }
+
+  if (!envelope || typeof envelope !== 'object' || !('data' in envelope)) {
+    throw new Error('fetchGraph: unexpected response shape (missing .data)');
+  }
+
+  return envelope.data;
+}

package/dist/frontend/src/lib/contrast.js

@@ -0,0 +1,34 @@
+// WCAG 2.x relative-luminance contrast ratio, from first principles
+// (https://www.w3.org/TR/WCAG21/#dfn-relative-luminance /
+// https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio). No existing contrast
+// checker exists anywhere in this repo — this is a small, dependency-free,
+// directly-testable implementation rather than a new npm dependency.
+
+function srgbChannelToLinear(c8) {
+  const c = c8 / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+function hexToRgb(hex) {
+  const m = /^#([0-9a-f]{6})$/i.exec(String(hex));
+  if (!m) throw new Error(`hexToRgb: invalid hex color "${hex}" (expected #RRGGBB)`);
+  const int = parseInt(m[1], 16);
+  return [(int >> 16) & 255, (int >> 8) & 255, int & 255];
+}
+
+function relativeLuminance([r, g, b]) {
+  const [rl, gl, bl] = [r, g, b].map(srgbChannelToLinear);
+  return 0.2126 * rl + 0.7152 * gl + 0.0722 * bl;
+}
+
+export function contrastRatio(hexA, hexB) {
+  const lumA = relativeLuminance(hexToRgb(hexA));
+  const lumB = relativeLuminance(hexToRgb(hexB));
+  const lighter = Math.max(lumA, lumB);
+  const darker = Math.min(lumA, lumB);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function meetsAA(hexA, hexB, { largeText = false } = {}) {
+  return contrastRatio(hexA, hexB) >= (largeText ? 3 : 4.5);
+}

package/dist/frontend/src/lib/dom.js

@@ -0,0 +1,24 @@
+// Safe DOM element builder. Attributes are set via setAttribute/className/
+// addEventListener; text children go through createTextNode. Never uses
+// innerHTML — graph-derived text can never become live markup through this
+// function (PRD §16 last line, AC-15 hygiene, even though the formal
+// adversarial-fixture gate is Milestone 3's).
+
+export function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key === 'class') node.className = String(value);
+    else if (key.startsWith('on') && typeof value === 'function') node.addEventListener(key.slice(2).toLowerCase(), value);
+    else node.setAttribute(key, String(value));
+  }
+  for (const child of [].concat(children)) {
+    if (child === undefined || child === null || child === false) continue;
+    node.appendChild(typeof child === 'string' ? document.createTextNode(child) : child);
+  }
+  return node;
+}
+
+export function clear(node) {
+  while (node.firstChild) node.removeChild(node.firstChild);
+}

package/dist/frontend/src/lib/escape-html.js

@@ -0,0 +1,16 @@
+// Safe HTML-text escaping. Neither existing in-repo escaper is quote-complete
+// (scanner/src/posture/fleet.js's `esc` skips `'`; scanner/src/badge.js's
+// `_xmlEscape` skips `"` and `'`) — this one escapes all five HTML-significant
+// characters so it is safe in both text content and quoted attribute values.
+
+const ENTITIES = Object.freeze({
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+});
+
+export function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => ENTITIES[c]);
+}

package/dist/frontend/src/lib/flow-path.js

@@ -0,0 +1,40 @@
+// Shared per-flow path/topology helpers, used by every view that needs to
+// know "which nodes does this flow actually touch" — extracted here after
+// Architecture View independently reimplemented the same node-collection
+// logic inline in computeFlowSummary, to avoid a third divergent copy when
+// Privacy View needed it too.
+
+export function flowPathNodeIds(graph, flow) {
+  const ids = new Set([flow.source, flow.sink]);
+  for (const edgeId of flow.edgeIds) {
+    const edge = graph.edges.find((e) => e.id === edgeId);
+    if (edge) {
+      ids.add(edge.from);
+      ids.add(edge.to);
+    }
+  }
+  return ids;
+}
+
+// Backend AI node-subtype vocabulary (scanner/src/lineage/schema.js's
+// SOURCE_CATEGORIES/SINK_CATEGORIES, AI-flavored entries only). This list
+// must be hand-kept in sync with that schema file — the frontend never
+// imports scanner/src/lineage/ at runtime (see frontend/CLAUDE.md).
+// Corrected this increment: the previous set ('ai-assistant',
+// 'vector-store') matched neither real enum and silently never matched
+// any real node.
+export const AI_SUBTYPES = new Set([
+  'ai-model-provider', 'ai-local-model', 'ai-agent', 'ai-tool',
+  'ai-vector-store', 'ai-memory', 'ai-training', 'ai-evaluation', 'ai-telemetry',
+  'ai-model-output', 'ai-tool-result', 'ai-retrieved-document',
+]);
+
+// AI relevance is computed from flow/node TOPOLOGY (does the path touch an
+// AI-kind node), never from dataElement.aiContexts — that field is never
+// populated by name-only classification (see scanner/src/lineage's
+// classification.js), so an aiContexts-based filter would show zero AI
+// relevance despite real AI-processing flows existing in the graph.
+export function isAiRelevantFlow(graph, flow) {
+  const pathNodeIds = flowPathNodeIds(graph, flow);
+  return graph.nodes.some((n) => pathNodeIds.has(n.id) && AI_SUBTYPES.has(n.subtype));
+}

package/dist/frontend/src/lib/focus-controls.js

@@ -0,0 +1,149 @@
+// Milestone 3, sub-project M3-UX-Query, Task 3. Nine focus-control graph
+// traversals over the SAME DataFlowGraph v1 structure the query language
+// (lib/query-language.js) reads. Each function returns the SAME
+// `{nodeIds: Set<string>, edgeIds: Set<string>}` shape
+// `views/architecture-view.js`'s own `resolveSelection` already produces
+// for `selection` — so the render layer needs zero new consumption code to
+// accept output from any of these. `resetToOverview` is deliberately NOT
+// implemented here: Task 4 wires the existing `resolveSelection(graph,
+// null)` directly for that control (see this file's own header note in the
+// task brief) — duplicating it here would just be a second, divergent copy
+// of the same empty-selection shape.
+
+function buildAdjacency(graph) {
+  const forward = new Map(); // nodeId -> [{edgeId, toId}]
+  const backward = new Map(); // nodeId -> [{edgeId, fromId}]
+  for (const n of graph.nodes) { forward.set(n.id, []); backward.set(n.id, []); }
+  for (const e of graph.edges) {
+    forward.get(e.from)?.push({ edgeId: e.id, toId: e.to });
+    backward.get(e.to)?.push({ edgeId: e.id, fromId: e.from });
+  }
+  return { forward, backward };
+}
+
+function bfsDirection(graph, startId, adjacencyKey, adjacency) {
+  const nodeIds = new Set([startId]);
+  const edgeIds = new Set();
+  const queue = [startId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const { edgeId, toId, fromId } of adjacency.get(current) ?? []) {
+      const nextId = adjacencyKey === 'forward' ? toId : fromId;
+      edgeIds.add(edgeId);
+      if (!nodeIds.has(nextId)) { nodeIds.add(nextId); queue.push(nextId); }
+    }
+  }
+  return { nodeIds, edgeIds };
+}
+
+export function showDownstream(graph, nodeId) {
+  const { forward } = buildAdjacency(graph);
+  return bfsDirection(graph, nodeId, 'forward', forward);
+}
+
+export function showUpstream(graph, nodeId) {
+  const { backward } = buildAdjacency(graph);
+  return bfsDirection(graph, nodeId, 'backward', backward);
+}
+
+export function showAllPaths(graph, nodeId) {
+  const down = showDownstream(graph, nodeId);
+  const up = showUpstream(graph, nodeId);
+  return {
+    nodeIds: new Set([...down.nodeIds, ...up.nodeIds]),
+    edgeIds: new Set([...down.edgeIds, ...up.edgeIds]),
+  };
+}
+
+export function showShortestPath(graph, fromId, toId) {
+  const { forward } = buildAdjacency(graph);
+  const cameFrom = new Map(); // nodeId -> {viaEdgeId, fromId}
+  const visited = new Set([fromId]);
+  const queue = [fromId];
+  let found = false;
+  while (queue.length > 0 && !found) {
+    const current = queue.shift();
+    for (const { edgeId, toId: nextId } of forward.get(current) ?? []) {
+      if (visited.has(nextId)) continue;
+      visited.add(nextId);
+      cameFrom.set(nextId, { viaEdgeId: edgeId, fromId: current });
+      if (nextId === toId) { found = true; break; }
+      queue.push(nextId);
+    }
+  }
+  if (!found) return { nodeIds: new Set(), edgeIds: new Set() };
+  const nodeIds = new Set([toId]);
+  const edgeIds = new Set();
+  let cursor = toId;
+  while (cursor !== fromId) {
+    const step = cameFrom.get(cursor);
+    edgeIds.add(step.viaEdgeId);
+    nodeIds.add(step.fromId);
+    cursor = step.fromId;
+  }
+  return { nodeIds, edgeIds };
+}
+
+export function showExternalPathsOnly(graph) {
+  const externalNodeIds = new Set(graph.nodes.filter((n) => n.externality?.value === 'external').map((n) => n.id));
+  const nodeIds = new Set();
+  const edgeIds = new Set();
+  for (const flow of graph.flows) {
+    const pathNodeIds = new Set([flow.source, flow.sink]);
+    for (const edgeId of flow.edgeIds) {
+      const edge = graph.edges.find((e) => e.id === edgeId);
+      if (edge) { pathNodeIds.add(edge.from); pathNodeIds.add(edge.to); }
+    }
+    if ([...pathNodeIds].some((id) => externalNodeIds.has(id))) {
+      for (const id of pathNodeIds) nodeIds.add(id);
+      for (const edgeId of flow.edgeIds) edgeIds.add(edgeId);
+    }
+  }
+  return { nodeIds, edgeIds };
+}
+
+const UNPROTECTED_VERDICTS = new Set(['unprotected', 'mixed', 'unknown']);
+export function showUnprotectedPathsOnly(graph) {
+  const nodeIds = new Set();
+  const edgeIds = new Set();
+  for (const edge of graph.edges) {
+    const verdicts = [edge.protection.transit.verdict, edge.protection.atRest.verdict, edge.protection.handling.verdict];
+    if (verdicts.some((v) => UNPROTECTED_VERDICTS.has(v))) {
+      edgeIds.add(edge.id);
+      nodeIds.add(edge.from);
+      nodeIds.add(edge.to);
+    }
+  }
+  return { nodeIds, edgeIds };
+}
+
+export function showAliases(graph, nodeId) {
+  const node = graph.nodes.find((n) => n.id === nodeId);
+  const nodeIds = new Set([nodeId]);
+  // Real, honest implementation. This plan's own Global Constraints section
+  // disclosed node.aliases as "confirmed always empty in real scan output" —
+  // that claim does NOT hold against the real committed flagship fixture
+  // (Web App/Payment API/Analytics API all carry non-empty aliases arrays
+  // there; see test/focus-controls.test.js for the correction). What IS
+  // true, confirmed against that same fixture: every alias entry is an
+  // alternate DISPLAY NAME for the node itself (e.g. "Checkout Form" is
+  // another name for the Web App node), never a pointer to a distinct
+  // sibling node record — no alias string in the fixture matches any other
+  // real node's label or id. This loop is still real, correct logic (not a
+  // no-op stub): it looks up each alias against the graph's own nodes and
+  // only adds a match it actually finds, so it will do the right thing the
+  // moment (if ever) alias data that DOES reference a distinct node record
+  // shows up in a real scan — nothing here is invented alias data.
+  for (const alias of node?.aliases ?? []) {
+    const aliasNode = graph.nodes.find((n) => n.label === alias || n.id === alias);
+    if (aliasNode) nodeIds.add(aliasNode.id);
+  }
+  return { nodeIds, edgeIds: new Set() };
+}
+
+export function showDisconnected(graph) {
+  const connectedIds = new Set();
+  for (const e of graph.edges) { connectedIds.add(e.from); connectedIds.add(e.to); }
+  const nodeIds = new Set(graph.nodes.filter((n) => !connectedIds.has(n.id)).map((n) => n.id));
+  return { nodeIds, edgeIds: new Set() };
+}

package/dist/frontend/src/lib/protection-visual.js

@@ -0,0 +1,46 @@
+// The single source of truth for how a protection verdict renders — every
+// view/component must call protectionVisual() rather than hardcoding a
+// color or glyph, so AC-20 (verdicts distinguishable without color) holds
+// everywhere by construction, not by convention.
+//
+// These verdict strings are NOT imported from scanner/src/lineage/protection.js
+// — the browser bundle never imports anything under scanner/src/lineage/ at
+// runtime (see frontend/CLAUDE.md). Keep this list in sync by hand if the
+// backend's PROTECTION_VERDICTS/FLOW_SUMMARY_VALUES enums ever change.
+
+// PRD §8.4, exact quoted precedence: "unprotected/prohibited → mixed →
+// unknown/manual_required → protected/permitted → not_assessed". Read as
+// display priority when aggregating multiple verdicts into one, not a raw
+// severity order: not_assessed is LOWEST priority because it means "no
+// information," and any real signal (even a protected one) should be shown
+// instead of "not assessed." not_applicable isn't named in the PRD list;
+// treated at the same lowest priority as not_assessed (both mean "nothing
+// to prioritize").
+export const VERDICT_PRECEDENCE = Object.freeze([
+  'unprotected',
+  'mixed',
+  'unknown',
+  'protected',
+  'not_assessed',
+  'not_applicable',
+]);
+
+const VISUALS = Object.freeze({
+  protected: { verdict: 'protected', label: 'Protected', glyph: '✓', lineStyle: 'solid', colorVar: '--status-protected' },
+  unprotected: { verdict: 'unprotected', label: 'Unprotected', glyph: '✗', lineStyle: 'solid', colorVar: '--status-unprotected' },
+  mixed: { verdict: 'mixed', label: 'Mixed', glyph: '±', lineStyle: 'solid', colorVar: '--status-unprotected' },
+  unknown: { verdict: 'unknown', label: 'Unknown', glyph: '?', lineStyle: 'dashed', colorVar: '--status-unknown' },
+  not_applicable: { verdict: 'not_applicable', label: 'Not applicable', glyph: '·', lineStyle: 'dotted', colorVar: '--text-secondary' },
+  not_assessed: { verdict: 'not_assessed', label: 'Not assessed', glyph: '–', lineStyle: 'dotted', colorVar: '--status-unknown' },
+});
+
+export function protectionVisual(verdict) {
+  return VISUALS[verdict] ?? VISUALS.not_assessed;
+}
+
+export function worstVerdict(verdicts) {
+  for (const tier of VERDICT_PRECEDENCE) {
+    if (verdicts.includes(tier)) return tier;
+  }
+  return 'not_assessed';
+}