@blamejs/core 0.10.7 → 0.10.8

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.10.x
 
+- v0.10.8 (2026-05-17) — **EU AI Act Art. 50 + AB-853 + CAC implicit label + AIBOM + operator-surfaced DX primitives.** Calendar-bound release ahead of the 2026-08-02 EU AI Act Art. 50 transparency / California SB-942-as-amended-by-AB-853 effective date and the live (2025-09-01) China CAC GB 45438-2025 labeling regime. Three new AI-transparency surfaces + three operator-surfaced DX primitives (issues #91 / #92 / #93). **(a) `b.ai.aiContentDetect.report`** — inbound-asset provenance detector. Operators extract C2PA-COSE envelopes / CAC implicit-label JSON / IPTC PhotoMetadata via their format-specific muxer and feed the artifacts to `report({...})`; the framework verifies signatures, anchors against an operator-pinned trust list, and returns a normalized provenance report for the AB-853 §22757.21 disclosure UI. Trust-list-empty surfaces as an alert rather than silent acceptance. Profile / posture cascade: `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `cac-genai-label` pin to `strict` (refuse on signer not on trust list); `nist-ai-600-1`, `iso-42001`, `iso-23894`, `nist-ai-rmf` pin to `balanced`. **(b) `b.contentCredentials.cacImplicitLabel` + `b.contentCredentials.cacImplicitLabelRead`** — China CAC (Cyberspace Administration) "Measures for Labeling AI-Generated Synthetic Content" + mandatory standard GB 45438-2025 implicit metadata emitter and reverse parser. Validates the 18-character Chinese unified social credit code (统一社会信用代码 per GB 32100-2015), `aigcMarker` field, and `contentKind` enum at the config-time tier. Operators co-emit alongside the C2PA-COSE manifest by declaring `cac-genai-label` posture on the existing `b.contentCredentials.build`. **(c) `b.ai.modelManifest.build` / `.sign` / `.verify`** — CycloneDX 1.6 ML-BOM (AI bill of materials) emitter. EU AI Act Art. 11 + Annex IV require technical documentation for high-risk AI systems; CycloneDX 1.6 ML-BOM is the de-facto serialization (and forward-positioned for EU CRA 2027-12-11 — Regulation (EU) 2024/2847 requires SBOM-style documentation for AI components in products with digital elements). Emits `bomFormat: "CycloneDX"` + `specVersion: "1.6"` + `serialNumber` UUIDv4 URN + `metadata.timestamp` + `metadata.tools[]` + `metadata.component` (primary model with `type: "machine-learning-model"`) + `components[]` datasets + `properties[]` hyperparameters (per CycloneDX spec issue #702 EU CRA alignment) + `formulation[]` workflows + `services[]` external model APIs. ML-DSA-87 signature over canonical-JSON-1785 representation; verify path NEVER trusts an embedded "signedBytes" field — defends the CVE-2025-29774 / CVE-2025-29775 xml-crypto-style signature-substitution class. Self-validates required CycloneDX 1.6 fields at emit time. **(d) `b.atomicFile.conflictPath`** — filesystem-portable conflict-suffix path builder (issue #91). `notes.md` → `notes.conflict-2026-05-17T19-30-00Z.md`; Windows-safe (no `:` / `.`), extension-preserving, dotfile-aware, optional `tag` + `suffix` disambiguator for same-second collisions. Composes the existing `b.atomicFile.pathTimestamp`. **(e) `b.promisePool.create`** — bounded-concurrency promise pool (issue #92). The gap between `b.workerPool` (worker-thread CPU-bound work) and `b.queue` (durable cross-process messaging). `run(taskFn)` / `fire(taskFn)` / `drain({ close? })` shape with back-pressure on enqueue, queueLimit refusal, composes with `b.appShutdown` for drain-on-shutdown. No hidden retry — operators compose `b.retry.withRetry` inside the task body when they want it. **(f) `b.sdNotify.send` / `.ready` / `.stopping` / `.reloading` / `.watchdog`** — sd_notify protocol surface for systemd Type=notify daemons (issue #93). Reads `$NOTIFY_SOCKET` via `b.parsers.safeEnv.readVar`, dispatches `READY=1` / `STOPPING=1` / `RELOADING=1` / `WATCHDOG=1` via `systemd-notify(1)` with `execFile` (no shell). No-op (with audit) when `$NOTIFY_SOCKET` is unset (foreground / container / non-systemd init). Compose with `b.appShutdown.create` for the STOPPING signal; compose with a periodic watchdog interval for systemd's auto-restart-on-hang guarantee. **(g) `b.crypto.randomInt` substrate** — exported alongside the v0.10.7 substrate to give the new AIBOM UUID generator a single greppable random-int path. **(h) New compliance postures in `b.contentCredentials` / `b.ai.aiContentDetect` / `b.ai.modelManifest`:** `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `eu-ai-act-art-11`, `cac-genai-label`, `nist-ai-600-1`, `nist-ai-rmf`, `iso-42001`, `iso-23894`. **(i) New audit namespaces:** `aibom` (aibom.signed / aibom.verified), `aicontentdetect` (aicontentdetect.report), `sdnotify` (sdnotify.send / sdnotify.send.skipped). **Deferred to v0.10.9:** in-tree IPTC PhotoMetadata reader for `digitalSourceType` field — operators pre-parse with their tool of choice and pass via `opts.ipmd`. **Operator impact:** no breaking changes. Operators already declaring `eu-ai-act-art-50` posture should pin a trust list via the new primitive before turning on default-on detection in production; AB-853 §22757.21 platform-detection obligations are 2027-01-01 effective so there's runway. References: [EU AI Act Regulation (EU) 2024/1689](https://eur-lex.europa.eu/eli/reg/2024/1689) · [California SB-942 + AB-853](https://leginfo.legislature.ca.gov/faces/billNavClient.xhtml?bill_id=202320240SB942) · [CAC GB 45438-2025](http://www.cac.gov.cn/2025-03/14/c_1742700786675936.htm) · [C2PA 2.1 / 2.2 spec](https://c2pa.org/specifications/specifications/2.2/) · [CycloneDX 1.6 ML-BOM](https://cyclonedx.org/docs/1.6/json/) · [OWASP CycloneDX AI/ML-BOM Authoritative Guide](https://owasp.org/www-project-cyclonedx/) · [NIST AI 600-1 Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf) · [ISO/IEC 42001:2023](https://www.iso.org/standard/81230.html) · [systemd-notify(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html) · [CVE-2025-29774](https://nvd.nist.gov/vuln/detail/CVE-2025-29774) · [CVE-2025-29775](https://nvd.nist.gov/vuln/detail/CVE-2025-29775) · [CVE-2025-32711 EchoLeak](https://nvd.nist.gov/vuln/detail/CVE-2025-32711).
 - v0.10.7 (2026-05-17) — **Mail-stack P3 / P4 hardening sweep.** Twenty-plus refusals + observability additions across the four mail listeners, the DKIM verifier, ARC signer, MIME parser, and the DNS / DSN / List-* guards. No new public primitives; one substrate addition (`b.crypto.randomInt`); two new operator-visible opts on the submission listener. **(a) `b.crypto.randomInt(min, max)`** — substrate wrapper that routes every framework integer draw through one greppable primitive. Migrates the inline `nodeCrypto.randomInt` sites in `b.network.dns` / `b.network.dns.resolver` (DNS query-ID), `b.mail.auth` (DMARC `pct` sampling), and `b.externalDb` (transaction-retry jitter) so the audit trail is uniform and future detectors see one shape. **(b) `b.mail.server.submission.create({ requireDkim, dkimRequireMode })`** — outbound DKIM-required gate per Yahoo / Google 2024 bulk-sender alignment. `requireDkim` defaults `true` under `strict` profile (`false` under `balanced` / `permissive`). `dkimRequireMode` is `"self"` (signer's `d=` must match authenticated identity's domain), `"any"` (any signer present), or `"off"` (no gate). Default `"any"`. Submission listener that doesn't carry a `DKIM-Signature:` header at DATA-end refuses with `5.7.20`. **(c) `b.mail.server.{mx,submission}.create({ allowSmtpUtf8 })`** — single per-listener SMTPUTF8 (RFC 6531) switch threaded end-to-end into `guardSmtpCommand.validate`. Default `false`. Operators that accept EAI envelopes flip to `true` and the toggle reaches every wire-line guard call. **(d) DKIM verifier signature-count cap.** `b.mail.dkim.verify` now refuses (`policy` verdict) rather than silently truncating when a message carries more `DKIM-Signature` headers than `maxSignatures` (default 8). The opt is range-checked at config time against a ceiling of 16; out-of-range throws `dkim/bad-max-signatures`. Closes a verifier-fan-out DoS shape per RFC 6376 §6.1. Emits `dkim.verify.signature_count_cap` audit on the refusal so postmasters see DoS attempts in the authentication-results stream. **(e) MX listener size-overrun + observability.** `MAIL FROM SIZE=` is now reconciled against the actual DATA byte count after dot-stuffing reversal — senders that understate `SIZE=` to probe `maxMessageBytes` get `552 5.3.4` rather than silently accepted, with `mail.server.mx.size_overrun` audit. Refused-recipient list (bounded at 32 per transaction) now surfaces in the `data_accepted` / `delivered` audit metadata. Write-backpressure on every reply attaches a once-per-socket `mail.server.mx.write_backpressure` audit so operators see stalled connections without flooding on every reply. **(f) IMAP refinements.** `APPEND mailbox [flags] [date-time] {literal}` now honors the optional RFC 9051 §6.3.12 date-time argument (parsed into `internalDate` ms-epoch, refused with `BAD` rather than silently falling back to `Date.now()`). `FETCH` / `STORE` outside of Selected state now respond `BAD` (RFC 9051 §6.4.5 / §6.4.6 — protocol-context violation, not policy refusal). `LOGIN` quoted-string args honor `\"` / `\\` escape pairs per the RFC 9051 §5.1 grammar (the prior shape terminated at the first `"`, letting a hostile client smuggle `LOGIN "alice\"@example.com" "pw"` past the username binding). **(g) ARC signer hop-count ceiling.** `b.mail.arc.sign` extracts prior hops with the RFC 8617 §5 50-hop cap; an inbound chain claiming >50 hops or an out-of-range `i=` tag is refused rather than enumerated. **(h) MIME parser charset + observability.** `b.safeMime.parse` now decodes `utf-16` (RFC 2781 §3.3 BOM detection + BE default), `utf-16be`, and `utf-16le` end-to-end — the prior shape advertised `utf-16` / `utf-16be` in the allowlist but only decoded `utf-16le`. `binary` Content-Transfer-Encoding is removed from the default allowlist (RFC 3030 §3 — `binary` requires explicit BINARYMIME negotiation; operators that wire BINARYMIME opt back in via `transferEncodingAllowlist: [..., "binary"]`). Control-character refusal errors now report the BYTE offset (via `Buffer.byteLength` on the JS string prefix) rather than the UTF-16 code-unit index, so audit lines align with wire-level inspection. **(i) DKIM / DMARC / ARC / iPrev / DSN tightening.** `b.guardDsn` splits the RFC 3464 §2.1.1 block separator on literal `\r\n\r\n` only (the prior `\n\s*\n` accepted `\v` / `\f` whitespace as a block boundary, letting a hostile sender bend the per-message vs per-recipient boundary). `b.guardMessageId` now validates id-left + id-right against RFC 5322 §3.2.3 dot-atom-text shape under `strict` profile; `b.guardListId` extends the localhost FQDN exception to `.local` (RFC 6762) and `.lan` (draft-chapin-rfc2606bis). **(j) `b.guardListUnsubscribe` SSRF defense.** HTTPS one-click URIs now refuse IP-literal hosts (v4 + v6), reserved-local hostnames (`localhost` / `localhost.localdomain` / `ip6-localhost` / `ip6-loopback`), and reserved-local TLD suffixes (`.local` / `.lan` / `.internal`). New optional `allowedHosts` opt provides a domain allowlist — when supplied, every HTTPS host (or any ancestor) must be on the list. **(k) `b.mailStore` JMAP objectid bump to 128 bits.** RFC 8474 §1.5.1 — the prior 24-char hex prefix cut entropy to 96 bits; full 32-char hex restores 128 bits. **Operator impact:** Submission listeners on `strict` profile WITHOUT operator-side DKIM signing (`b.mail.dkim.sign` pre-relay) now refuse outbound DATA — operators in this state either wire DKIM signing, opt to `dkimRequireMode: "off"`, or step down to `balanced`. `b.mail.dkim.verify` callers passing `maxSignatures > 16` now throw at config time — clamp via the opt or rely on the framework default. `b.safeMime.parse` callers that legitimately receive `binary` Content-Transfer-Encoding (BINARYMIME-aware downstream pipelines) opt back in via `transferEncodingAllowlist`. `b.guardListUnsubscribe.validate` callers that legitimately rely on IP-literal one-click URIs (test harnesses, internal-network operators) opt in via `allowedHosts: ["10.0.0.0/8"]` style ancestor matches. **Deferred to v0.10.8 / v0.10.12:** per-tenant pepper on `b.mailStore` derived hashes (`from_hash` / `message_id_hash`) ships in v0.10.12 alongside the `b.agent.tenant` adoption refactor; the schema migration is too invasive to fold into this patch. `b.mailStore` forensic-recovery columns (original Content-Transfer-Encoding + charset preserved alongside decoded body) defer to v0.10.8 — the schema change carries its own backwards-compatibility surface. References: [RFC 9051 IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051), [RFC 6376 DKIM §6.1](https://www.rfc-editor.org/rfc/rfc6376#section-6.1), [RFC 6531 SMTPUTF8](https://www.rfc-editor.org/rfc/rfc6531), [RFC 3030 BINARYMIME](https://www.rfc-editor.org/rfc/rfc3030), [RFC 2781 UTF-16 BOM](https://www.rfc-editor.org/rfc/rfc2781), [RFC 1870 SMTP SIZE](https://www.rfc-editor.org/rfc/rfc1870), [RFC 8474 JMAP objectid](https://www.rfc-editor.org/rfc/rfc8474), [RFC 8617 ARC §5](https://www.rfc-editor.org/rfc/rfc8617#section-5), [RFC 3464 DSN §2.1.1](https://www.rfc-editor.org/rfc/rfc3464#section-2.1.1), [RFC 5322 Message Format §3.2.3](https://www.rfc-editor.org/rfc/rfc5322#section-3.2.3), [RFC 6761 Reserved Domain Names](https://www.rfc-editor.org/rfc/rfc6761), [Yahoo / Gmail bulk-sender 2024](https://blog.google/products/gmail/gmail-security-authentication-spam-protection/).
 - v0.10.6 (2026-05-17) — **Vendored-SBOM CycloneDX 1.6 conformance + cosign verification recipe pin.** Build-side + verification-side improvements; no runtime changes. **(a) `scripts/build-vendored-sbom.js` per-component `cpe` field** — every vendored bundle gets a CPE 2.3 string (`cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*`). CISA / NVD CVE-matching tools (Dependency-Track, OWASP Dependency-Check, Snyk SBOM Monitor) match CVE advisories against components by CPE; the prior emit had no CPE field, so vendored bundles were invisible to operator-side CVE scanners. **(b) Per-component `supplier` block** — `metadata.supplier` (framework-level) was already populated; each vendored bundle now also carries its own `components[].supplier` with the upstream maintainer / org per [SLSA v1.0 provenance requirements](https://slsa.dev/spec/v1.0/provenance) — operators auditing the SBOM see both the framework supplier (blamejs) AND the vendored bundle's upstream supplier (noble-curves, noble-ciphers, etc.) at the component level. **(c) `metadata.lifecycles[].externalReferences[]`** — CycloneDX 1.6 §4.4.2 requires `lifecycles` entries to carry build-provenance references (workflow URL, run ID); the npm-publish workflow now populates these so the SBOM points back at the SLSA-attesting workflow run that produced the tarball. **(d) Sub-component `dependsOn` graph** — when a vendored bundle exposes sub-components (e.g. `noble-ciphers` exports `xchacha20poly1305` + `aes-gcm` as named sub-modules), each sub-component now emits its own SBOM entry with a `dependencies` edge pointing to its parent (CycloneDX 1.6 §4.7). Operators get the full transitive graph instead of just the top-level vendored bundle. **(e) `_licenseFor()` inline-path fix** — the path-resolution branch that handles vendored bundles whose `package.json` is under `lib/vendor/<name>/package.json` now correctly returns the SPDX `license.id` (was returning `null` for that branch, causing CycloneDX-validator warnings). **(f) `SECURITY.md` cosign verification recipe pinned to workflow path + tag-ref** — the operator-side recipe now constrains `cosign verify-blob --certificate-identity-regexp` to the specific workflow file (`.github/workflows/npm-publish.yml`) + tag-ref shape (`refs/tags/v[0-9]+\.[0-9]+\.[0-9]+`), refusing certificates issued for any other workflow or ref class. Also documents `--rekor-url` for operators running on an air-gapped network with a local transparency log + offline TUF root path for `cosign initialize --root <local-root.json>`. **(g) `.github/workflows/npm-publish.yml` recipe comment** synchronized to match the SECURITY.md recipe so operators copy-pasting from either source see identical verification steps. **Operator impact:** SBOM consumers that previously saw vendored bundles as opaque now see CPE-matched components with proper supplier attribution + transitive sub-component graph. The Sigstore-keyless verification recipe is more restrictive (rejects certificates issued for non-`npm-publish.yml` workflows on this repo) — operators already verifying against the prior recipe see the same successful verification with the tighter identity match. References: [CycloneDX 1.6 §4](https://cyclonedx.org/docs/1.6/json/), [CPE 2.3 spec](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7695.pdf), [SLSA v1.0 provenance](https://slsa.dev/spec/v1.0/provenance), [Sigstore cosign verify-blob](https://docs.sigstore.dev/cosign/verifying/verify/), [TUF specification](https://theupdateframework.github.io/specification/latest/).
 - v0.10.5 (2026-05-16) — **`b.mail.server.pop3` APOP cleartext refusal + `b.vendorData` constant-time digest compares.** Two small entry-tier refusals on the mail and vendor-data surfaces. **(a) `b.mail.server.pop3._handleApop`** refuses APOP when the connection is cleartext and the profile is not permissive, symmetric with the existing USER / PASS refusal. APOP transmits `MD5(timestamp+secret)` (not cleartext credentials), but an attacker who captures the digest plus the known greeting timestamp can mount an offline dictionary attack against the shared secret. RFC 1939 §7 explicitly warns about this; the wire MUST be TLS-protected to deny the offline-attack vector. Emits the same `mail.server.pop3.auth_refused_cleartext` audit event + writes `-ERR APOP refused over cleartext (use STLS first; RFC 1939 §7)`. The cleartext-refusal line was advertised in the v0.10.4 release notes but the wire-level enforcement only lands here; operators relying on v0.10.4 saw the comment but not the runtime gate. **(b) `b.vendorData.verifyAll()`** boot-time digest verifies (SHA-256 layer 1, SHA3-512 layer 2, and the SLH-DSA-SHAKE-256f pubkey-fingerprint cross-check) now compare via a length-prechecked `nodeCrypto.timingSafeEqual` instead of `!==`. The framework convention is that every digest / MAC compare is constant-time regardless of whether the value is a secret — reaching for `!==` whenever a value "isn't a secret" is the smell; the convention is the gate. Uses `nodeCrypto.timingSafeEqual` directly (not `b.crypto.timingSafeEqual`) because `b.crypto` is `lazyRequire`'d to break a circular load chain and isn't available during boot-time `verifyAll()`. **Operator impact:** APOP users on plaintext POP3 (port 110) without STLS first now get `-ERR` instead of authenticating — the operator either wires STLS, switches the listener to implicit TLS (port 995), or sets `profile: "permissive"` for the deliberately-open path. `b.vendorData` consumers see no behavioral change — the timing-safe compare returns the same boolean as `!==` for length-equal inputs. References: [RFC 1939 §7](https://www.rfc-editor.org/rfc/rfc1939#section-7), [CWE-208 timing attack](https://cwe.mitre.org/data/definitions/208.html), [NIST SP 800-38B §6.3 MAC verification](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38B.pdf).

package/index.js

@@ -397,7 +397,14 @@ module.exports = {
   nis2:             { report: require("./lib/nis2-report") },
   gdpr:             { ropa: require("./lib/gdpr-ropa") },
   breach:           require("./lib/breach-deadline"),
-  ai:               { adverseDecision: require("./lib/ai-adverse-decision"), input: aiInput },
+  ai:               {
+    adverseDecision: require("./lib/ai-adverse-decision"),
+    input:           aiInput,
+    aiContentDetect: require("./lib/ai-content-detect"),
+    modelManifest:   require("./lib/ai-model-manifest"),
+  },
+  promisePool:      require("./lib/promise-pool"),
+  sdNotify:         require("./lib/sd-notify"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/ai-content-detect.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * @module b.ai.aiContentDetect
+ * @nav    AI
+ * @title  AI Content Detection
+ *
+ * @intro
+ *   Inbound-asset provenance detector. Counterpart to the outbound
+ *   `b.contentCredentials` seal path: the operator extracts whatever
+ *   provenance metadata their format-specific muxer surfaces
+ *   (C2PA-COSE envelope from JPEG XMP / PNG iTXt / MP4 boxes, CAC
+ *   implicit-label JSON from the embedded metadata block, IPTC
+ *   `digitalSourceType` when an IPTC PhotoMetadata reader is wired),
+ *   feeds them to `report({...})`, and renders the normalized result
+ *   in their user-facing UI. California AB-853 §22757.21 requires the
+ *   disclosure; the framework owns the validation + trust-list anchor
+ *   layer, the application owns the rendering.
+ *
+ *   Trust-list anchored: the operator declares which signer subjects
+ *   are acceptable. Default trust list is empty — the framework does
+ *   not ship a curated CA list. Operators that want a one-line ramp
+ *   point at the public C2PA Trust List per
+ *   https://opensource.contentauthenticity.org/docs/trust-list.
+ *
+ *   Posture vocabulary: `strict` (refuse on signature invalid, refuse
+ *   on signer not on trust list), `balanced` (refuse on cryptographic
+ *   tamper, audit-only on missing provenance), `permissive`
+ *   (audit-only across the board). Default `balanced`.
+ *
+ *   IPTC `digitalSourceType` PhotoMetadata reading is forward-watch —
+ *   the framework ships no XMP / EXIF parser yet, so operators that
+ *   want IPTC detection pre-parse with their tool of choice and pass
+ *   the field via `opts.ipmd`. AB-853 names C2PA as "widely adopted";
+ *   IPTC PhotoMetadata reader lands in v0.10.9 once a vendoring
+ *   decision is made.
+ *
+ * @card
+ *   Inbound provenance detector — composes C2PA verify + CAC implicit-label parser + operator-supplied IPTC field, returns a normalized report for AB-853 / EU AI Act Art. 50 / CAC disclosure UIs.
+ */
+
+var lazyRequire = require("./lazy-require");
+var contentCredentials = lazyRequire(function () { return require("./content-credentials"); });
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+
+var AiContentDetectError = defineClass("AiContentDetectError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "balanced";
+var PROFILES = Object.freeze({
+  strict:     { refuseUnsigned: true,  refuseUnpinned: true,  auditOnly: false },
+  balanced:   { refuseUnsigned: false, refuseUnpinned: false, auditOnly: false },
+  permissive: { refuseUnsigned: false, refuseUnpinned: false, auditOnly: true },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "ca-ab-853":          "strict",
+  "ca-sb-942":          "strict",
+  "eu-ai-act-art-50":   "strict",
+  "cac-genai-label":    "strict",
+  "nist-ai-600-1":      "balanced",
+  "iso-42001":          "balanced",
+  "iso-23894":          "balanced",
+  "nist-ai-rmf":        "balanced",
+});
+
+function _resolveProfile(opts) {
+  if (opts && typeof opts.posture === "string") {
+    var profile = COMPLIANCE_POSTURES[opts.posture];
+    if (profile) return PROFILES[profile];
+  }
+  if (opts && typeof opts.profile === "string" && PROFILES[opts.profile]) {
+    return PROFILES[opts.profile];
+  }
+  return PROFILES[DEFAULT_PROFILE];
+}
+
+/**
+ * @primitive b.ai.aiContentDetect.report
+ * @signature b.ai.aiContentDetect.report(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance ca-ab-853, ca-sb-942, eu-ai-act-art-50, cac-genai-label, nist-ai-600-1, iso-42001, iso-23894, nist-ai-rmf
+ * @related   b.contentCredentials.verify, b.contentCredentials.cacImplicitLabelRead
+ *
+ * Build a normalized `provenanceReport` from the provenance artifacts
+ * an operator's muxer extracted from an inbound asset. At least one
+ * of `c2paEnvelope`, `cacImplicitLabel`, or `ipmd` must be supplied;
+ * absence of all three returns `kind: "none"` with `verified: false`.
+ *
+ * @opts
+ *   c2paEnvelope:       object,         // { manifest, signature } from operator's C2PA extractor
+ *   c2paPublicKeyPem:   string,         // PEM for verify (operator-pinned signer key)
+ *   cacImplicitLabel:   Buffer|string|object, // GB 45438-2025 implicit metadata block
+ *   ipmd:               object,         // IPTC PhotoMetadata digitalSourceType field (operator-pre-parsed)
+ *   trustList:          string[],       // acceptable signer subject identifiers
+ *   profile:            "strict"|"balanced"|"permissive",
+ *   posture:            string,         // pins profile per posture vocabulary
+ *
+ * @example
+ *   var report = b.ai.aiContentDetect.report({
+ *     c2paEnvelope: env, c2paPublicKeyPem: pem,
+ *     trustList: ["CN=Acme AI, O=Acme, C=US"],
+ *     posture: "ca-ab-853",
+ *   });
+ *   report.kind;     // → "c2pa"
+ *   report.verified; // → true if signature OK and signer on trustList
+ */
+function report(opts) {
+  opts = opts || {};
+  var profile = _resolveProfile(opts);
+  var trustList = Array.isArray(opts.trustList) ? opts.trustList.slice() : [];
+  var alerts = [];
+
+  var has = {
+    c2pa: opts.c2paEnvelope && typeof opts.c2paEnvelope === "object",
+    cac:  opts.cacImplicitLabel !== undefined && opts.cacImplicitLabel !== null,
+    ipmd: opts.ipmd && typeof opts.ipmd === "object",
+  };
+  if (!has.c2pa && !has.cac && !has.ipmd) {
+    if (profile.refuseUnsigned) {
+      throw new AiContentDetectError("ai-content-detect/no-provenance",
+        "report: strict profile requires at least one provenance artifact " +
+        "(c2paEnvelope, cacImplicitLabel, or ipmd) — got none");
+    }
+    var out = {
+      kind: "none", verified: false, alerts: ["no-provenance"], rawDisclosure: null,
+    };
+    if (!profile.auditOnly) {
+      try {
+        audit.safeEmit({
+          action: "aicontentdetect.report", outcome: "denied",
+          metadata: { kind: "none", reason: "no-provenance" },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    return Object.freeze(out);
+  }
+
+  var verified = false;
+  var kind = "none";
+  var manifest = null;
+  var signerSubject = null;
+  var signedAt = null;
+  var cacLabel = null;
+  var ipmd = null;
+
+  if (has.c2pa) {
+    kind = "c2pa";
+    var keyMissing = typeof opts.c2paPublicKeyPem !== "string" || opts.c2paPublicKeyPem.length === 0;
+    if (keyMissing) {
+      // Strict refuses outright on a missing key — caller cannot
+      // produce a verified disclosure without it, so the report
+      // would be useless under the AB-853 / EU AI Act Art. 50
+      // posture cascade.
+      if (profile.refuseUnsigned) {
+        throw new AiContentDetectError("ai-content-detect/c2pa-public-key-missing",
+          "report: strict profile requires c2paPublicKeyPem when c2paEnvelope is supplied");
+      }
+      alerts.push("c2pa-public-key-missing");
+    } else {
+      var v = contentCredentials().verify(opts.c2paEnvelope, opts.c2paPublicKeyPem, { audit: false });
+      if (v.valid) {
+        verified = true;
+        manifest = v.claims;
+        signerSubject = opts.c2paEnvelope.signerSubject ||
+                        (v.claims && v.claims.signer && v.claims.signer.subject) || null;
+        signedAt = (v.claims && v.claims.signedAt) || null;
+      } else {
+        // Strict refuses on cryptographic-verify failure — a tampered
+        // or signature-invalid envelope MUST NOT produce a
+        // disclosure object the caller might surface as anything
+        // other than "refused." The append-alert-and-continue path
+        // is the balanced / permissive shape; strict throws.
+        if (profile.refuseUnsigned) {
+          throw new AiContentDetectError("ai-content-detect/c2pa-verify-failed",
+            "report: strict profile refuses tampered / invalid C2PA envelope (" +
+            v.reason + ")");
+        }
+        alerts.push("c2pa-verify-failed:" + v.reason);
+      }
+    }
+    if (verified && trustList.length > 0) {
+      if (!signerSubject || trustList.indexOf(signerSubject) === -1) {
+        if (profile.refuseUnpinned) {
+          throw new AiContentDetectError("ai-content-detect/signer-not-on-trust-list",
+            "report: signer '" + (signerSubject || "(unknown)") +
+            "' is not on the operator-supplied trust list");
+        }
+        verified = false;
+        alerts.push("signer-not-on-trust-list");
+      }
+    } else if (verified && trustList.length === 0) {
+      alerts.push("trust-list-empty");
+    }
+  }
+
+  if (has.cac) {
+    try { cacLabel = contentCredentials().cacImplicitLabelRead(opts.cacImplicitLabel); }
+    catch (e) {
+      alerts.push("cac-label-parse-failed:" + (e && e.code));
+    }
+    if (cacLabel && kind === "none") kind = "cac";
+  }
+
+  if (has.ipmd) {
+    ipmd = Object.freeze(Object.assign({}, opts.ipmd));
+    if (kind === "none") kind = "iptc";
+  }
+
+  var rawDisclosure = {
+    c2pa:  has.c2pa ? { manifest: manifest, signerSubject: signerSubject, signedAt: signedAt } : null,
+    cac:   cacLabel,
+    iptc:  ipmd,
+  };
+
+  if (!profile.auditOnly) {
+    try {
+      audit.safeEmit({
+        action: "aicontentdetect.report",
+        outcome: verified ? "success" : "warning",
+        metadata: {
+          kind:           kind,
+          verified:       verified,
+          signerSubject:  signerSubject,
+          alerts:         alerts.slice(),
+        },
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  return Object.freeze({
+    kind:          kind,
+    verified:      verified,
+    manifest:      manifest,
+    signerSubject: signerSubject,
+    signedAt:      signedAt,
+    cacLabel:      cacLabel,
+    ipmd:          ipmd,
+    alerts:        Object.freeze(alerts),
+    rawDisclosure: Object.freeze(rawDisclosure),
+  });
+}
+
+/**
+ * @primitive b.ai.aiContentDetect.compliancePosture
+ * @signature b.ai.aiContentDetect.compliancePosture(posture)
+ * @since     0.10.8
+ * @status    stable
+ *
+ * Return the effective profile name (`strict` / `balanced` /
+ * `permissive`) for a compliance posture, or `null` for unknown
+ * posture names. Operators introspect the cascade before wiring
+ * default-on paths.
+ *
+ * @example
+ *   b.ai.aiContentDetect.compliancePosture("ca-ab-853"); // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+module.exports = {
+  report:               report,
+  compliancePosture:    compliancePosture,
+  PROFILES:             PROFILES,
+  COMPLIANCE_POSTURES:  COMPLIANCE_POSTURES,
+  AiContentDetectError: AiContentDetectError,
+};

package/lib/ai-input.js

@@ -1,15 +1,23 @@
 "use strict";
 /**
- * AI input classifier for prompt-injection detection on operator
- * input flowing into LLM prompts. OWASP LLM01:2025 + NIST COSAIS RFI.
+ * @module b.ai.input
+ * @nav    AI
+ * @title  AI Input Classifier
  *
- * Public API:
- *   aiInput.classify(input, opts) -> { verdict, signals, features, confidence }
- *   aiInput.refuseIfMalicious(input, opts) -> result | throws
+ * @intro
+ *   Prompt-injection + jailbreak classifier for operator input flowing
+ *   into LLM prompts. OWASP LLM01:2025 + NIST COSAIS RFI. Pattern set
+ *   covers explicit-override prompts, role-reset markers, persona
+ *   jailbreaks, exfiltration callbacks, bidi / zero-width / control
+ *   char features, and encoded-instruction smells (base64 / rot13 /
+ *   markdown / HTML script).
  *
- * Severity 3 = malicious-by-default; 2 = suspicious. Verdict is
- * "malicious" with any severity-3 hit, "suspicious" with 2+ severity-2
- * hits, otherwise "clean".
+ *   Severity 3 = malicious-by-default; severity 2 = suspicious. Verdict
+ *   is `malicious` on any severity-3 hit, `suspicious` on 2+ severity-2
+ *   hits, otherwise `clean`.
+ *
+ * @card
+ *   Prompt-injection + jailbreak classifier — OWASP LLM01:2025 + NIST COSAIS RFI. Pattern set + bidi / zero-width feature scan; verdict-driven refusal helper.
  */
 
 var C = require("./constants");
@@ -67,6 +75,27 @@ function _featuresOf(input) {
   };
 }
 
+/**
+ * @primitive b.ai.input.classify
+ * @signature b.ai.input.classify(input, opts?)
+ * @since     0.8.10
+ * @status    stable
+ * @related   b.ai.input.refuseIfMalicious, b.guardHtml, b.mcp.toolResult.sanitize
+ *
+ * Classify operator-supplied prompt text against the injection /
+ * jailbreak pattern set. Returns
+ * `{ verdict, signals, features, confidence }`.
+ *
+ * @opts
+ *   maxBytes:    number,      // default 64 KiB; throws on overflow
+ *   audit:       boolean,      // default true; emit ai.input.classify event
+ *   errorClass:  ErrorClass,   // override the thrown class on bad input
+ *
+ * @example
+ *   var v = b.ai.input.classify("Ignore all prior instructions...");
+ *   v.verdict;     // → "malicious"
+ *   v.signals[0];  // → { id: "ignore-prior-instructions", severity: 3 }
+ */
 function classify(input, opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || AiInputError;
@@ -132,6 +161,27 @@ function classify(input, opts) {
   };
 }
 
+/**
+ * @primitive b.ai.input.refuseIfMalicious
+ * @signature b.ai.input.refuseIfMalicious(input, opts?)
+ * @since     0.8.10
+ * @status    stable
+ * @related   b.ai.input.classify
+ *
+ * Run `classify` and throw on `verdict === "malicious"` (severity-3
+ * pattern hit) — return the classification result otherwise. Operator
+ * convenience wrapper for handlers that want a single fail-closed
+ * call before forwarding to an LLM.
+ *
+ * @opts
+ *   maxBytes:    number,      // default 64 KiB
+ *   audit:       boolean,      // default true
+ *   errorClass:  ErrorClass,   // override the thrown class
+ *
+ * @example
+ *   try { b.ai.input.refuseIfMalicious(req.body.prompt); }
+ *   catch (e) { res.statusCode = 400; res.end(e.message); }
+ */
 function refuseIfMalicious(input, opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || AiInputError;