@quantakrypto/core 0.4.3 → 0.5.0

package/src/detectors/webauthn.ts

@@ -0,0 +1,205 @@
+/**
+ * Config detector: classical asymmetric signature algorithms pinned by
+ * WebAuthn / FIDO2 / passkey attestation & assertion, expressed as COSE
+ * algorithm identifiers in relying-party code and config
+ * (@simplewebauthn/server, py_webauthn, go-webauthn, webauthn4j).
+ *
+ * WHY WebAuthn is PQC-relevant: a WebAuthn credential is an asymmetric key
+ * pair whose PUBLIC key the authenticator returns (COSE-encoded) at
+ * registration; every subsequent assertion is a classical signature over the
+ * authentication challenge, and attestation statements are classical
+ * signatures over the credential. These are AUTHENTICATION signatures, not
+ * confidentiality — there is nothing to "harvest now" — but the moment a
+ * cryptographically-relevant quantum computer (CRQC) exists, an attacker who
+ * has a user's registered public key (or an attestation CA's key) can FORGE
+ * assertions/attestations and impersonate the user or a genuine authenticator.
+ * So every finding here is `category: "signature"`, `hndl: false`.
+ *
+ * The relying party pins which algorithms it will accept: `pubKeyCredParams`
+ * (registration) and `supportedAlgorithmIDs` (verification) enumerate COSE
+ * `alg` values, and the classical ones — ES256 (COSE -7, ECDSA P-256),
+ * RS256 (-257, RSA), EdDSA (-8) and their P-384/P-521/RSA-2048+ siblings — are
+ * exactly the ones a PQC migration must inventory and replace once FIDO/COSE
+ * standardise post-quantum algorithm identifiers.
+ *
+ * WHY numeric COSE ids need their own detector: the existing JWT/JOSE rule
+ * only matches QUOTED alg strings (`"ES256"`, `"RS256"`). WebAuthn libraries
+ * almost never write those strings — they use the NUMERIC COSE ids
+ * (`alg: -7`, `supportedAlgorithmIDs: [-7, -257]`) and language-level enum
+ * identifiers (`COSEAlgorithmIdentifier.ES256`, `webauthncose.AlgES256`,
+ * `COSEAlgorithmIdentifier.EDDSA`). None of those carry the quote characters
+ * the JWT rule keys off, so the entire WebAuthn surface is invisible today.
+ *
+ * Two independent match shapes per family, both gated by a file-level WebAuthn
+ * marker (see `hasWebauthnMarker`) so the generic numeric `alg: -7` form can't
+ * fire on unrelated code that happens to assign a small negative number:
+ *
+ *  1. NUMERIC form — the COSE `alg` value as an integer, either as an object
+ *     member (`alg: -7`, `alg = -257`) or inside a `supportedAlgorithmIDs`
+ *     array (`supportedAlgorithmIDs: [-7, -257]`). Restricted to the classical
+ *     COSE numbers only; symmetric / KDF / "direct" ids (e.g. -6, HS*) are
+ *     never in the alternation, so they cannot match.
+ *  2. ENUM form — the COSE algorithm's identifier as written in each library:
+ *     `COSEAlgorithmIdentifier.ES256|RS256|EdDSA|ECDSA_SHA_256` (webauthn4j,
+ *     py_webauthn) and Go's `webauthncose.AlgES256` / `AlgRS256` / `AlgEdDSA`
+ *     constants.
+ *
+ * COSE algorithm numbers → {@link AlgorithmFamily} (per the COSE registry, using
+ * the mapping this detector is specified against):
+ *  - ES256 (-7), ES384 (-35), ES512 (-36)      → ECDSA
+ *  - RS256 (-257), RS384 (-258), RS512 (-259)  → RSA
+ *  - EdDSA (-8)                                 → EdDSA
+ *
+ * Fast reject: `detect()` bails unless the file carries a distinctive WebAuthn
+ * API token (`pubKeyCredParams`, `PublicKeyCredential`, `webauthn`,
+ * `COSEAlgorithm`, `supportedAlgorithmIDs`, `navigator.credentials`). Those
+ * tokens are the marker gate ONLY — they never produce a standalone finding.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import {
+  DOC_EXTENSIONS,
+  eachMatch,
+  findingFromRule,
+  hasExtension,
+  maskBlockComments,
+  maskCommentLines,
+} from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+// Classical COSE algorithm numbers, grouped by family (see module docstring).
+const NUM_ECDSA = "7|35|36"; // ES256, ES384, ES512
+const NUM_RSA = "257|258|259"; // RS256, RS384, RS512
+const NUM_EDDSA = "8"; // EdDSA
+
+// --- NUMERIC form: a COSE `alg` value written as an integer. ---
+// (a) object member: `alg: -7`, `alg = -257` (JS/JSON, Python `alg=-7`).
+// `["']?alg["']?` tolerates the JSON/serialized form `"alg": -7` (the WebAuthn
+// options object is JSON-serializable and often stored/transmitted/tested as JSON
+// with a quoted key), as well as the unquoted `alg: -7` / `alg = -7` (audit M2).
+const RE_NUM_ECDSA = new RegExp(`["']?\\balg\\b["']?\\s*[:=]\\s*-(?:${NUM_ECDSA})\\b`, "g");
+const RE_NUM_RSA = new RegExp(`["']?\\balg\\b["']?\\s*[:=]\\s*-(?:${NUM_RSA})\\b`, "g");
+const RE_NUM_EDDSA = new RegExp(`["']?\\balg\\b["']?\\s*[:=]\\s*-(?:${NUM_EDDSA})\\b`, "g");
+// (b) `supportedAlgorithmIDs: [-7, -257]` array (@simplewebauthn verify option).
+// `[^\]]*` stays inside a single array literal; one match per family even when
+// the array lists several ids of that family.
+const RE_IDS_ECDSA = new RegExp(
+  `supportedAlgorithmIDs\\s*[:=]\\s*\\[[^\\]]*-(?:${NUM_ECDSA})\\b`,
+  "g",
+);
+const RE_IDS_RSA = new RegExp(`supportedAlgorithmIDs\\s*[:=]\\s*\\[[^\\]]*-(?:${NUM_RSA})\\b`, "g");
+const RE_IDS_EDDSA = new RegExp(
+  `supportedAlgorithmIDs\\s*[:=]\\s*\\[[^\\]]*-(?:${NUM_EDDSA})\\b`,
+  "g",
+);
+
+// --- ENUM form: the COSE algorithm's language-level identifier. ---
+// webauthn4j / py_webauthn: `COSEAlgorithmIdentifier.<name>`; go-webauthn:
+// `webauthncose.Alg<name>` (matched bare as `Alg<name>`).
+const RE_ENUM_ECDSA =
+  /\bCOSEAlgorithmIdentifier\.(?:ES(?:256|384|512)|ECDSA_SHA_(?:256|384|512))\b|\bAlgES(?:256|384|512)\b/g;
+const RE_ENUM_RSA =
+  /\bCOSEAlgorithmIdentifier\.(?:RS(?:256|384|512)|RSASSA_[A-Za-z0-9_]+)\b|\bAlgRS(?:256|384|512)\b/g;
+const RE_ENUM_EDDSA = /\bCOSEAlgorithmIdentifier\.(?:EdDSA|EDDSA)\b|\bAlgEdDSA\b/g;
+
+const REMEDIATION =
+  "WebAuthn/FIDO2 is standardizing PQC COSE algorithms; inventory the classical attestation/assertion algs now and plan migration.";
+
+const RULE_WEBAUTHN_ECDSA: RuleMeta = {
+  id: "webauthn-ecdsa",
+  title: "WebAuthn ECDSA COSE algorithm",
+  description:
+    "WebAuthn/FIDO2 credential pins a classical ECDSA COSE algorithm (ES256/ES384/ES512)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "WebAuthn/FIDO2 relying party accepts a classical ECDSA COSE algorithm (ES256/ES384/ES512); attestation/assertion signatures become forgeable once a CRQC exists.",
+  remediation: REMEDIATION,
+};
+const RULE_WEBAUTHN_RSA: RuleMeta = {
+  id: "webauthn-rsa",
+  title: "WebAuthn RSA COSE algorithm",
+  description: "WebAuthn/FIDO2 credential pins a classical RSA COSE algorithm (RS256/RS384/RS512)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "WebAuthn/FIDO2 relying party accepts a classical RSA COSE algorithm (RS256/RS384/RS512); attestation/assertion signatures become forgeable once a CRQC exists.",
+  remediation: REMEDIATION,
+};
+const RULE_WEBAUTHN_EDDSA: RuleMeta = {
+  id: "webauthn-eddsa",
+  title: "WebAuthn EdDSA COSE algorithm",
+  description: "WebAuthn/FIDO2 credential pins the classical EdDSA COSE algorithm (COSE -8)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "EdDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "WebAuthn/FIDO2 relying party accepts the classical EdDSA COSE algorithm (Ed25519); modern but still classical — attestation/assertion signatures become forgeable once a CRQC exists.",
+  remediation: REMEDIATION,
+};
+
+interface WebauthnRule {
+  meta: RuleMeta;
+  res: readonly RegExp[];
+}
+
+const WEBAUTHN_RULES: readonly WebauthnRule[] = [
+  { meta: RULE_WEBAUTHN_ECDSA, res: [RE_NUM_ECDSA, RE_IDS_ECDSA, RE_ENUM_ECDSA] },
+  { meta: RULE_WEBAUTHN_RSA, res: [RE_NUM_RSA, RE_IDS_RSA, RE_ENUM_RSA] },
+  { meta: RULE_WEBAUTHN_EDDSA, res: [RE_NUM_EDDSA, RE_IDS_EDDSA, RE_ENUM_EDDSA] },
+];
+
+/**
+ * True when `content` carries a distinctive WebAuthn API token. Used ONLY as
+ * the fast-reject marker gate — none of these tokens produce a finding — so the
+ * generic numeric `alg: -7` form can't fire on unrelated code.
+ */
+function hasWebauthnMarker(content: string): boolean {
+  return (
+    content.includes("pubKeyCredParams") ||
+    content.includes("PublicKeyCredential") ||
+    content.includes("COSEAlgorithm") ||
+    content.includes("supportedAlgorithmIDs") ||
+    content.includes("navigator.credentials") ||
+    /webauthn/i.test(content)
+  );
+}
+
+/** Detects classical COSE signature algorithms pinned by WebAuthn/FIDO2 relying parties. */
+export const webauthnDetector: Detector = {
+  id: "webauthn-crypto",
+  description: "Classical COSE signature algorithms in WebAuthn/FIDO2/passkey relying-party code",
+  scope: "config",
+  language: "any",
+  rules: WEBAUTHN_RULES.map((r) => r.meta),
+  appliesTo: (f) => !hasExtension(f, DOC_EXTENSIONS),
+  detect({ file, content }): Finding[] {
+    if (!hasWebauthnMarker(content)) return [];
+
+    // Mask C-style (`//`, `/* */`) and hash (`#`) comments so a commented-out
+    // options object can't fire. Offsets are preserved so finding locations stay
+    // exact.
+    const scan = maskCommentLines(maskBlockComments(content), ["//", "#"]);
+    const findings: Finding[] = [];
+    for (const { meta, res } of WEBAUTHN_RULES) {
+      for (const re of res) {
+        eachMatch(re, scan, (m) =>
+          findings.push(
+            findingFromRule(meta, { file, content, index: m.index, matchLength: m[0].length }),
+          ),
+        );
+      }
+    }
+    return findings;
+  },
+};

package/src/detectors/xmldsig.ts

@@ -0,0 +1,115 @@
+/**
+ * Config detector: classical crypto in XML Digital Signature / XML Encryption
+ * (W3C XML-DSig / XML-Enc), the algorithm layer under SAML SSO, WS-Security /
+ * SOAP, and signed XML documents. Enterprise identity is ubiquitous and its IdP
+ * signing keys are long-lived, so a forged SAML assertion is a prime quantum
+ * forgery surface; an encrypted SAML assertion (RSA key transport) is
+ * harvest-now-decrypt-later exposed.
+ *
+ * Detection keys off the W3C algorithm URIs, which are globally-unique constant
+ * strings (RFC-precise, so a lexical match is exact):
+ *  - `…xmldsig#rsa-sha1` / `…xmldsig-more#rsa-sha256` …  → RSA signature (forgeable)
+ *  - `…xmldsig11#dsa-sha256` / `…xmldsig#dsa-sha1`       → DSA signature
+ *  - `…xmldsig-more#ecdsa-sha256` …                      → ECDSA signature
+ *  - `…xmlenc#rsa-oaep(-mgf1p)` / `…xmlenc#rsa-1_5`      → RSA key transport (HNDL)
+ *
+ * These URIs appear both in XML config (`.xml`) and as string constants in SAML
+ * library code (python3-saml, xml-crypto, OpenSAML), so the detector runs on any
+ * non-doc file.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import { DOC_EXTENSIONS, eachMatch, findingFromRule, hasExtension } from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+// The `#fragment` of the W3C XML-DSig / XML-Enc algorithm URIs. Anchored on the
+// namespace fragment (`xmldsig…#` / `xmlenc#`) so a bare `rsa-sha256` elsewhere
+// doesn't misfire.
+const RE_XMLDSIG_RSA = /\bxmldsig(?:-more|11)?#rsa-sha(?:1|224|256|384|512)\b/g;
+const RE_XMLDSIG_DSA = /\bxmldsig(?:11)?#dsa-sha(?:1|256)\b/g;
+const RE_XMLDSIG_ECDSA = /\bxmldsig-more#ecdsa-sha(?:1|224|256|384|512)\b/g;
+const RE_XMLENC_RSA = /\bxmlenc#rsa-(?:oaep(?:-mgf1p)?|1_5)\b/g;
+
+const RULE_XMLDSIG_RSA: RuleMeta = {
+  id: "xmldsig-rsa-sign",
+  title: "XML-DSig RSA signature",
+  description: "XML Digital Signature with an RSA-SHA* algorithm (SAML/WS-Security)",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "XML signatures (SAML / WS-Security) use classical RSA (rsa-sha*); a quantum attacker could forge assertions signed with this key.",
+  remediation:
+    "Track PQC XML-DSig / SAML profiles (ML-DSA); rotate to a PQC signing key as tooling and IdPs add support.",
+};
+const RULE_XMLDSIG_DSA: RuleMeta = {
+  id: "xmldsig-dsa-sign",
+  title: "XML-DSig DSA signature",
+  description: "XML Digital Signature with a DSA-SHA* algorithm",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "DSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message: "XML signatures use classical DSA (dsa-sha*) — deprecated and quantum-forgeable.",
+  remediation: "Migrate off DSA now; track PQC XML-DSig profiles (ML-DSA).",
+};
+const RULE_XMLDSIG_ECDSA: RuleMeta = {
+  id: "xmldsig-ecdsa-sign",
+  title: "XML-DSig ECDSA signature",
+  description: "XML Digital Signature with an ECDSA-SHA* algorithm",
+  category: "signature",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDSA",
+  hndl: false,
+  cwe: CWE_BROKEN_CRYPTO,
+  message: "XML signatures use classical ECDSA (ecdsa-sha*); forgeable by a quantum attacker.",
+  remediation:
+    "Track PQC XML-DSig / SAML profiles (ML-DSA); rotate the signing key when supported.",
+};
+const RULE_XMLENC_RSA: RuleMeta = {
+  id: "xmlenc-rsa-keytransport",
+  title: "XML-Enc RSA key transport",
+  description: "XML Encryption with RSA-OAEP / RSA-1_5 key transport (encrypted SAML assertions)",
+  category: "kem",
+  severity: "high",
+  confidence: "high",
+  algorithm: "RSA",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "XML Encryption wraps the content key with classical RSA (rsa-oaep / rsa-1_5); encrypted XML (e.g. SAML assertions) is harvest-now-decrypt-later exposed.",
+  remediation:
+    "Plan migration to a post-quantum KEM (ML-KEM-768) for key transport as XML-Enc / SAML PQC profiles mature.",
+};
+
+/** Detects classical XML-DSig / XML-Enc algorithms (SAML, WS-Security, signed XML). */
+export const xmldsigDetector: Detector = {
+  id: "xmldsig-crypto",
+  description: "Classical XML-DSig / XML-Enc algorithms (SAML, WS-Security, signed XML)",
+  scope: "config",
+  language: "any",
+  // Skip prose/docs: a page explaining the SAML algorithm URIs is not live config.
+  appliesTo: (f) => !hasExtension(f, DOC_EXTENSIONS),
+  rules: [RULE_XMLDSIG_RSA, RULE_XMLDSIG_DSA, RULE_XMLDSIG_ECDSA, RULE_XMLENC_RSA],
+  detect({ file, content }): Finding[] {
+    // Fast reject: only proceed if an XML-DSig / XML-Enc namespace fragment is present.
+    if (!content.includes("xmldsig") && !content.includes("xmlenc")) return [];
+    const findings: Finding[] = [];
+    const add = (re: RegExp, rule: RuleMeta): void =>
+      eachMatch(re, content, (m) =>
+        findings.push(
+          findingFromRule(rule, { file, content, index: m.index, matchLength: m[0].length }),
+        ),
+      );
+    add(RE_XMLDSIG_RSA, RULE_XMLDSIG_RSA);
+    add(RE_XMLDSIG_DSA, RULE_XMLDSIG_DSA);
+    add(RE_XMLDSIG_ECDSA, RULE_XMLDSIG_ECDSA);
+    add(RE_XMLENC_RSA, RULE_XMLENC_RSA);
+    return findings;
+  },
+};

package/src/evidence.ts

@@ -21,6 +21,8 @@ import { createHash } from "node:crypto";
 import type { ScanResult } from "./types.js";
 import { toCbom } from "./cbom.js";
 import { VERSION } from "./version.js";
+import { buildPolicyMapping } from "./policy.js";
+import type { CryptoPolicy, PolicyMapping } from "./policy.js";
 
 /** Stable per-finding record for the evidence body (deterministic per commit). */
 export interface EvidenceFinding {
@@ -44,14 +46,27 @@ export interface ReadinessReport {
   tool: { name: "qScan"; version: string };
   inventory: ScanResult["inventory"];
   findings: EvidenceFinding[];
+  /** §4 policy verdicts, present only when a crypto policy was supplied. */
+  policyMapping?: PolicyMapping;
   cbom: unknown;
   attestation: {
     /** sha256 over the canonicalized deterministic body (excludes scanTimeUtc). */
     contentHash: string;
-    /** RFC-3161 / transparency-log token — filled by an external signer. */
-    timestamp: null;
-    /** Detached signature over `contentHash` — filled by an external signer. */
-    signature: null;
+    /**
+     * RFC-3161 / transparency-log token over `contentHash`, produced by an EXTERNAL
+     * timestamper (opaque string, e.g. base64). `null` until {@link signReadinessReport}
+     * runs one.
+     */
+    timestamp: string | null;
+    /**
+     * Detached signature over `contentHash`, produced by an EXTERNAL signer (opaque
+     * string, e.g. base64/PEM). `null` until {@link signReadinessReport} runs one.
+     */
+    signature: string | null;
+    /** Non-sensitive provenance label of the signer (e.g. "openssl", "cosign"). */
+    signedWith?: string;
+    /** Non-sensitive provenance label of the timestamper (e.g. "openssl-ts"). */
+    timestampedWith?: string;
   };
 }
 
@@ -73,6 +88,8 @@ export interface ReadinessReportOptions {
   repository?: string;
   /** Full commit SHA (e.g. from `GITHUB_SHA`); omitted → null. */
   commit?: string;
+  /** Optional org cryptography policy — adds the §4 `policyMapping` verdicts. */
+  policy?: CryptoPolicy;
 }
 
 /**
@@ -97,6 +114,10 @@ export function buildReadinessReport(
   // its CycloneDX envelope carries a volatile timestamp/serial — so it is
   // EXCLUDED from the hashed body (its integrity follows from its hashed inputs)
   // to keep the content hash reproducible across scan runs on the same commit.
+  // §4: if the org supplied a crypto policy, attest the per-finding verdicts too.
+  // Deterministic (same findings + policy → same mapping), so it is hashed.
+  const policyMapping = opts.policy ? buildPolicyMapping(result.findings, opts.policy) : undefined;
+
   const hashableBody = {
     reportType: "quantakrypto-readiness",
     specVersion: 1,
@@ -108,6 +129,7 @@ export function buildReadinessReport(
     tool: { name: "qScan", version: VERSION },
     inventory: result.inventory,
     findings,
+    ...(policyMapping ? { policyMapping } : {}),
   };
   const contentHash =
     "sha256:" +
@@ -122,3 +144,115 @@ export function buildReadinessReport(
     attestation: { contentHash, timestamp: null, signature: null },
   } as ReadinessReport;
 }
+
+/** The result of {@link verifyReadinessReport}. */
+export interface VerifyReadinessResult {
+  /** True iff the recomputed body hash equals the hash claimed in the attestation. */
+  valid: boolean;
+  /** The hash recomputed over the report's CURRENT body. */
+  computedHash: string;
+  /** The hash claimed in the report's attestation (`attestation.contentHash`). */
+  claimedHash: string;
+  /** A short human reason; present only when `valid` is false. */
+  reason?: string;
+}
+
+/**
+ * Recompute the deterministic content hash over a readiness report's body and
+ * compare it to the hash the attestation claims. Detects tampering with ANY
+ * hashed field — a finding, the inventory, a policy verdict, or subject/tool
+ * metadata: editing it after the fact changes the recomputed hash, so `valid`
+ * becomes false.
+ *
+ * By construction the scan timestamp, the CBOM envelope, and the attestation
+ * block itself are EXCLUDED from the hash (see {@link buildReadinessReport}), so
+ * touching those does not fail verification — their integrity follows from their
+ * hashed inputs. The body is reconstructed from the report's OWN stored fields
+ * (including `tool.version`), so a report built by an older qScan still verifies.
+ *
+ * This checks the INTEGRITY hash only. It does NOT validate the detached
+ * signature or RFC-3161 timestamp: those are opaque tokens from an external
+ * signer (ADR-0004) and are verified with that signer's own tooling.
+ */
+export function verifyReadinessReport(report: ReadinessReport): VerifyReadinessResult {
+  const hashableBody = {
+    reportType: report.reportType,
+    specVersion: report.specVersion,
+    subject: {
+      repository: report.subject.repository,
+      commit: report.subject.commit,
+      scannedRoot: report.subject.scannedRoot,
+    },
+    tool: { name: report.tool.name, version: report.tool.version },
+    inventory: report.inventory,
+    findings: report.findings,
+    ...(report.policyMapping ? { policyMapping: report.policyMapping } : {}),
+  };
+  const computedHash =
+    "sha256:" +
+    createHash("sha256")
+      .update(JSON.stringify(canonicalize(hashableBody)))
+      .digest("hex");
+  const claimedHash = report.attestation.contentHash;
+  if (computedHash === claimedHash) {
+    return { valid: true, computedHash, claimedHash };
+  }
+  return {
+    valid: false,
+    computedHash,
+    claimedHash,
+    reason: "content-hash mismatch: the report body was modified after it was built",
+  };
+}
+
+/**
+ * An EXTERNAL signer/timestamper the tool orchestrates. Per ADR-0004 the tool
+ * implements no cryptography: it hands the payload to an operator-provided signer
+ * (an `openssl`/`cosign` invocation, an RFC-3161 TSA client, …) and records what
+ * comes back. `label` is a short, non-sensitive provenance string (e.g. the signer
+ * program name) — NOT the full command, which may contain a key path.
+ */
+export interface EvidenceSigner {
+  label: string;
+  /**
+   * Produce a detached signature / timestamp token (opaque string) over `payload`.
+   * May be async so a future signer can shell out OR call a KMS / RFC-3161 TSA over
+   * the network without foreclosing that once this contract freezes at 1.0.
+   */
+  sign(payload: string): string | Promise<string>;
+}
+
+/** Options for {@link signReadinessReport}: a detached-signature and/or a timestamp signer. */
+export interface SignEvidenceOptions {
+  signer?: EvidenceSigner;
+  timestamper?: EvidenceSigner;
+}
+
+/**
+ * Fill a readiness report's attestation with a detached signature and/or RFC-3161
+ * timestamp, produced by EXTERNAL signers over the report's `contentHash`. Pure
+ * orchestration: it invokes the injected signers and records their opaque output
+ * plus a provenance label — it performs no cryptography itself (ADR-0004). Returns a
+ * NEW report; the hashed body is untouched (attestation is excluded from the hash),
+ * so signing never changes `contentHash`.
+ */
+export async function signReadinessReport(
+  report: ReadinessReport,
+  opts: SignEvidenceOptions,
+): Promise<ReadinessReport> {
+  const payload = report.attestation.contentHash;
+  const signature = opts.signer ? await opts.signer.sign(payload) : report.attestation.signature;
+  const timestamp = opts.timestamper
+    ? await opts.timestamper.sign(payload)
+    : report.attestation.timestamp;
+  return {
+    ...report,
+    attestation: {
+      ...report.attestation,
+      signature,
+      timestamp,
+      ...(opts.signer ? { signedWith: opts.signer.label } : {}),
+      ...(opts.timestamper ? { timestampedWith: opts.timestamper.label } : {}),
+    },
+  };
+}

package/src/index.ts

@@ -56,13 +56,14 @@ export type {
 // Scan cancellation / work-budget errors.
 export { AbortError, BudgetExceededError } from "./errors.js";
 
-// Parallel scanning (worker_threads pool) + pure merge/chunk helpers.
-export { scanParallel, mergeChunkResults, chunkByBytes } from "./parallel.js";
-export type { ScanChunk, ChunkResult, SizedFile } from "./parallel.js";
+// Parallel scanning (worker_threads pool). The chunk/merge helpers and their
+// SizedFile/ChunkResult types are internal plumbing (not part of the public API).
+export { scanParallel } from "./parallel.js";
+export type { ScanChunk } from "./parallel.js";
 
-// Detector registry (plugin point) + helpers + the rule catalog.
-export { DetectorRegistry, defaultRegistry, detectorScope } from "./registry.js";
-export type { RuleCatalogEntry } from "./registry.js";
+// Detector registry (plugin point). `detectorScope` and the rule-catalog type are
+// internal.
+export { DetectorRegistry, defaultRegistry } from "./registry.js";
 
 // Canonical baseline (shared by qScan + the Action).
 export {
@@ -83,7 +84,7 @@ export { loadConfig, ConfigError, CONFIG_FILENAME } from "./config.js";
 export type { QuantakryptoFileConfig, LoadConfigResult } from "./config.js";
 
 // Filesystem walker (relative POSIX paths, default ignores, size/binary filters).
-export { walkFiles, isBinaryPath, isGeneratedPath, looksMinified } from "./walk.js";
+export { walkFiles, isBinaryPath, looksMinified } from "./walk.js";
 
 // Analyzable-language coverage (which source languages the scanner inspects).
 export {
@@ -104,20 +105,43 @@ export { vulnerableDependencies, DEP_VULNERABLE_RULE, isManifestFile } from "./d
 export { SEVERITY_ORDER, severityRank, meetsThreshold, sarifLevel } from "./severity.js";
 
 // Reporters.
-export { toSarif, toJson, formatSummary, formatTierGuidance } from "./report.js";
+export {
+  toSarif,
+  toJson,
+  formatSummary,
+  formatTierGuidance,
+  formatProfileGuidance,
+} from "./report.js";
 export type { ReportOptions } from "./report.js";
 
 // CycloneDX 1.6 cryptographic bill of materials (CBOM) export.
 export { toCbom } from "./cbom.js";
 export type { CycloneDxBom, CbomComponent } from "./cbom.js";
+// Merge multiple CBOMs (code + infra + live endpoints) into one combined BOM.
+export { mergeCboms } from "./cbom-merge.js";
+// OpenVEX 0.2.0 export — quantum-readiness posture as VEX statements.
+export { toOpenVex } from "./vex.js";
+export type { OpenVexDocument, OpenVexStatement, OpenVexOptions } from "./vex.js";
 // ISO/IEC 27001 A.8.24 evidence-chain readiness report.
-export { buildReadinessReport } from "./evidence.js";
-export type { ReadinessReport, EvidenceFinding, ReadinessReportOptions } from "./evidence.js";
-
-// Remediation lookup (family + tier-aware) and stateful-HBS guidance.
+export { buildReadinessReport, signReadinessReport, verifyReadinessReport } from "./evidence.js";
+export type {
+  ReadinessReport,
+  EvidenceFinding,
+  ReadinessReportOptions,
+  EvidenceSigner,
+  SignEvidenceOptions,
+  VerifyReadinessResult,
+} from "./evidence.js";
+
+// Cryptography policy → per-finding verdicts (A.8.24 evidence §4).
+export { buildPolicyMapping, parseCryptoPolicy } from "./policy.js";
+export type { CryptoPolicy, PolicyVerdict, PolicyMapping, PolicyFindingVerdict } from "./policy.js";
+
+// Remediation lookup (family + tier-aware + profile-aware) and stateful-HBS guidance.
 export {
   remediationFor,
   remediationForTier,
+  remediationForProfile,
   TIER_PARAMS,
   STATEFUL_HBS_NOTE,
   PQC_TRANSITION_NOTE,
@@ -125,6 +149,20 @@ export {
 } from "./remediation.js";
 export type { SecurityTier } from "./remediation.js";
 
+// Post-quantum standards source of truth + review cadence.
+export { PQC_STANDARDS } from "./standards.js";
+export type { PqcStandards, StandardsCitation, StandardsReviewStatus } from "./standards.js";
+
+// Selectable standards regime profiles (NIST / CNSA / BSI / ANSSI / NCSC).
+export {
+  STANDARDS_PROFILES,
+  DEFAULT_PROFILE_ID,
+  standardsProfileIds,
+  getStandardsProfile,
+  defaultStandardsProfile,
+} from "./standards-profiles.js";
+export type { StandardsProfile, HybridStance } from "./standards-profiles.js";
+
 // CWE identifier constants.
 export {
   CWE_BROKEN_CRYPTO,

package/src/inventory.ts

@@ -48,7 +48,7 @@ const SCORE_SCALE = 100;
 const TEST_PATH_WEIGHT = 0.15;
 
 /** True when a finding's file path is test / fixture / example / documentation. */
-export function isTestOrFixturePath(file: string): boolean {
+function isTestOrFixturePath(file: string): boolean {
   const f = file.toLowerCase().replace(/\\/g, "/");
   if (
     /(?:^|\/)(?:tests?|__tests__|testdata|test-data|fixtures?|examples?|demos?|samples?|specs?|mocks?|docs?|benchmarks?|e2e)\//.test(
@@ -75,20 +75,28 @@ export function isTestOrFixturePath(file: string): boolean {
 export function readinessScore(findings: Finding[]): number {
   if (findings.length === 0) return 100;
 
-  const seen: Record<Severity, number> = {
+  // Diminishing-returns occurrence counters, kept SEPARATE for full-weight vs
+  // test-path findings. Sharing one counter per severity let whichever finding came
+  // first in the (path-sorted) list claim the `1/√1` slot, so a directory rename — or
+  // a test finding sorting ahead of a real one — changed the score. Bucketing makes
+  // the penalty independent of file order and of test/real interleaving.
+  const zero = (): Record<Severity, number> => ({
     critical: 0,
     high: 0,
     medium: 0,
     low: 0,
     info: 0,
-  };
+  });
+  const seenReal = zero();
+  const seenTest = zero();
 
   let penalty = 0;
   for (const f of findings) {
-    seen[f.severity] += 1;
-    const weight =
-      SEVERITY_WEIGHT[f.severity] * (isTestOrFixturePath(f.location.file) ? TEST_PATH_WEIGHT : 1);
-    penalty += penaltyFor(weight, seen[f.severity]);
+    const isTest = isTestOrFixturePath(f.location.file);
+    const bucket = isTest ? seenTest : seenReal;
+    bucket[f.severity] += 1;
+    const weight = SEVERITY_WEIGHT[f.severity] * (isTest ? TEST_PATH_WEIGHT : 1);
+    penalty += penaltyFor(weight, bucket[f.severity]);
   }
 
   return Math.max(0, Math.min(100, Math.round(100 * Math.exp(-penalty / SCORE_SCALE))));