@blamejs/core 0.10.7 → 0.10.8

package/lib/ai-model-manifest.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * @module b.ai.modelManifest
+ * @nav    AI
+ * @title  AI Model Manifest (AIBOM)
+ *
+ * @intro
+ *   CycloneDX 1.6 ML-BOM emitter for AI bills of materials. EU AI Act
+ *   Art. 11 + Annex IV require technical documentation for high-risk
+ *   AI systems; the EU CRA (Regulation (EU) 2024/2847) transposition
+ *   deadline (2027-12-11) extends SBOM-style documentation to AI
+ *   components in products with digital elements. ML-BOM extends the
+ *   CycloneDX 1.5 machine-learning component type with model-card,
+ *   dataset, hyperparameter, formulation, and external-service
+ *   sections per the OWASP CycloneDX Authoritative Guide to AI/ML-BOM
+ *   and CycloneDX spec issue #702 (EU CRA alignment).
+ *
+ *   Two paths:
+ *   - `build({...})` constructs a 1.6-conformant JSON BOM in memory.
+ *   - `sign(bom, { privateKeyPem })` signs the canonical-JSON-1785
+ *     representation with the operator's signing key (ML-DSA-87 by
+ *     default per project hard-rule 2). `verify(envelope, publicKeyPem)`
+ *     re-canonicalizes and checks before trusting any field.
+ *
+ *   Self-validation: `build` rejects BOMs missing CycloneDX 1.6
+ *   required fields (`bomFormat`, `specVersion`, `metadata.timestamp`,
+ *   `metadata.component` when shipping a model). Catches malformed
+ *   inputs at emit time, not at downstream validator.
+ *
+ * @card
+ *   CycloneDX 1.6 AI bill of materials (AIBOM) — model cards, datasets, hyperparameters, training workflows. ML-DSA-87 signed.
+ */
+
+var bCrypto = require("./crypto");
+var canonicalJson = require("./canonical-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var audit = require("./audit");
+
+var AiModelManifestError = defineClass("AiModelManifestError", { alwaysPermanent: true });
+
+var SPEC_VERSION = "1.6";
+var BOM_FORMAT = "CycloneDX";
+var COMPONENT_TYPE_MODEL = "machine-learning-model";
+var VALID_DATA_TYPES = Object.freeze({
+  "source-code": true, configuration: true, dataset: true, definition: true,
+  "device-driver": true, documentation: true, evidence: true, executable: true,
+  file: true, firmware: true, framework: true, library: true,
+  "machine-learning-model": true, manifest: true, "operating-system": true,
+  patch: true, platform: true, "test-case": true,
+});
+var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+var BOM_REF_RE = /^[A-Za-z0-9._:/+-]{1,256}$/;                                                  // allow:raw-byte-literal — CycloneDX bom-ref string-length cap, not bytes
+
+function _requireString(obj, key, ownerName) {
+  if (typeof obj[key] !== "string" || obj[key].length === 0) {
+    throw new AiModelManifestError("aibom/bad-" + key,
+      ownerName + ": " + key + " must be a non-empty string");
+  }
+}
+
+function _validateModelComponent(c) {
+  if (!c || typeof c !== "object") {
+    throw new AiModelManifestError("aibom/bad-model-component",
+      "build: opts.model must be an object");
+  }
+  _requireString(c, "name", "build.model");
+  _requireString(c, "version", "build.model");
+  if (c["bom-ref"] !== undefined) {
+    if (typeof c["bom-ref"] !== "string" || c["bom-ref"].length > 256) {                         // allow:raw-byte-literal — bom-ref string-length cap, not bytes
+      throw new AiModelManifestError("aibom/bad-bom-ref",
+        "build.model: bom-ref must be a string of length 1-256");
+    }
+    if (!BOM_REF_RE.test(c["bom-ref"])) {                                                        // allow:regex-no-length-cap — length-bounded immediately above
+      throw new AiModelManifestError("aibom/bad-bom-ref",
+        "build.model: bom-ref must match [A-Za-z0-9._:/+-]");
+    }
+  }
+  // modelCard is CycloneDX 1.6 §4.5.5; required for ML components when
+  // the operator wants downstream tooling (e.g. Dependency-Track) to
+  // surface the card. We do not REQUIRE the card here (some operators
+  // ship a hash-only ML-BOM by policy) but we do validate shape when
+  // present.
+  if (c.modelCard !== undefined) {
+    if (typeof c.modelCard !== "object") {
+      throw new AiModelManifestError("aibom/bad-model-card",
+        "build.model.modelCard: must be an object");
+    }
+  }
+}
+
+function _validateDataComponent(d, idx) {
+  if (!d || typeof d !== "object") {
+    throw new AiModelManifestError("aibom/bad-dataset",
+      "build.datasets[" + idx + "]: must be an object");
+  }
+  _requireString(d, "name", "build.datasets[" + idx + "]");
+  if (d.type !== undefined && !VALID_DATA_TYPES[d.type]) {
+    throw new AiModelManifestError("aibom/bad-dataset-type",
+      "build.datasets[" + idx + "].type '" + d.type + "' not in CycloneDX 1.6 data-type vocabulary");
+  }
+}
+
+/**
+ * @primitive b.ai.modelManifest.build
+ * @signature b.ai.modelManifest.build(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11, nist-ai-600-1, iso-42001, iso-23894
+ * @related   b.ai.modelManifest.sign, b.ai.modelManifest.verify
+ *
+ * Build a CycloneDX 1.6 ML-BOM JSON document for the supplied model
+ * + datasets + hyperparameters + formulation + external services.
+ * Returns a frozen plain object ready for `sign({...})` or direct
+ * serialization. Validates against the spec's required-field set at
+ * emit time (`bomFormat` / `specVersion` / `metadata.timestamp` /
+ * `metadata.component`) plus the ML-BOM-specific shape (model
+ * component type, dataset type vocabulary, bom-ref grammar).
+ *
+ * @opts
+ *   model:           object,        // { name, version, license?, bom-ref?, modelCard? }
+ *   datasets:        object[],      // [{ name, type?, contents?, classification?, ... }]
+ *   hyperparameters: object,        // kv pairs → properties[]
+ *   formulation:     object[],      // [{ ref, components, workflows }]
+ *   services:        object[],      // [{ name, endpoints, authenticated }]
+ *   tool:            object,        // tool metadata; defaults to blamejs core
+ *   timestamp:       string,        // ISO 8601 UTC; defaults to now
+ *   serialNumber:    string,        // urn:uuid:...; defaults to fresh UUIDv4
+ *
+ * @example
+ *   var bom = b.ai.modelManifest.build({
+ *     model: { name: "acme-classifier", version: "1.2.3" },
+ *     datasets: [{ name: "training-2026", type: "dataset" }],
+ *   });
+ *   bom.bomFormat;   // → "CycloneDX"
+ *   bom.specVersion; // → "1.6"
+ */
+function build(opts) {
+  opts = opts || {};
+  _validateModelComponent(opts.model);
+  if (opts.datasets !== undefined) {
+    if (!Array.isArray(opts.datasets)) {
+      throw new AiModelManifestError("aibom/bad-datasets",
+        "build: opts.datasets must be an array");
+    }
+    for (var i = 0; i < opts.datasets.length; i += 1) _validateDataComponent(opts.datasets[i], i);
+  }
+  var timestamp = opts.timestamp || new Date().toISOString();
+  if (!ISO8601_RE.test(timestamp)) {
+    throw new AiModelManifestError("aibom/bad-timestamp",
+      "build: timestamp must be ISO 8601 UTC (e.g. 2026-05-17T20:00:00Z)");
+  }
+  var serialNumber = opts.serialNumber || _uuidUrn();
+  if (typeof serialNumber !== "string" || serialNumber.indexOf("urn:uuid:") !== 0) {
+    throw new AiModelManifestError("aibom/bad-serial-number",
+      "build: serialNumber must start with `urn:uuid:`");
+  }
+
+  var primaryComponent = Object.assign({
+    type:    COMPONENT_TYPE_MODEL,
+    "bom-ref": opts.model["bom-ref"] || ("model:" + opts.model.name + "@" + opts.model.version),
+  }, opts.model);
+  primaryComponent.type = COMPONENT_TYPE_MODEL;
+
+  var components = [];
+  // Per CycloneDX 1.6 §4.7: the primary component goes in
+  // metadata.component, NOT in components[]. Datasets, hyperparameter-
+  // bearing components, and external dependencies live in components[].
+  if (Array.isArray(opts.datasets)) {
+    for (var di = 0; di < opts.datasets.length; di += 1) {
+      var ds = opts.datasets[di];
+      components.push(Object.assign({
+        type: ds.type || "data",
+        "bom-ref": ds["bom-ref"] || ("dataset:" + ds.name),
+      }, ds));
+    }
+  }
+
+  // Hyperparameters → CycloneDX properties[] kv pairs per spec
+  // issue #702 EU CRA alignment.
+  var properties = [];
+  if (opts.hyperparameters && typeof opts.hyperparameters === "object") {
+    var keys = Object.keys(opts.hyperparameters);
+    for (var k = 0; k < keys.length; k += 1) {
+      var key = keys[k];
+      properties.push({ name: "ai:hyperparameter:" + key,
+                        value: String(opts.hyperparameters[key]) });
+    }
+  }
+
+  var bom = {
+    bomFormat:     BOM_FORMAT,
+    specVersion:   SPEC_VERSION,
+    serialNumber:  serialNumber,
+    version:       1,
+    metadata: {
+      timestamp: timestamp,
+      tools: [Object.assign({
+        vendor:  "blamejs",
+        name:    "@blamejs/core",
+        version: _frameworkVersion(),
+      }, opts.tool || {})],
+      component: primaryComponent,
+    },
+  };
+  if (components.length > 0) bom.components = components;
+  if (properties.length > 0) bom.properties = properties;
+  if (Array.isArray(opts.formulation) && opts.formulation.length > 0) {
+    bom.formulation = opts.formulation;
+  }
+  if (Array.isArray(opts.services) && opts.services.length > 0) {
+    bom.services = opts.services;
+  }
+  if (Array.isArray(opts.dependencies) && opts.dependencies.length > 0) {
+    bom.dependencies = opts.dependencies;
+  }
+  return Object.freeze(bom);
+}
+
+/**
+ * @primitive b.ai.modelManifest.sign
+ * @signature b.ai.modelManifest.sign(bom, opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11
+ * @related   b.ai.modelManifest.build, b.ai.modelManifest.verify
+ *
+ * Sign an AIBOM produced by `build({...})`. Signature is over the
+ * canonical-JSON-1785 representation of the BOM (deterministic byte
+ * stream regardless of object-key insertion order); the operator's
+ * `privateKeyPem` selects the signing alg (ML-DSA-87 by default per
+ * the project's PQC-first crypto rule). Returns `{ bom, signature }`
+ * where `signature` is base64-encoded.
+ *
+ * @opts
+ *   privateKeyPem:  string,        // PEM-encoded private key
+ *   audit:          boolean,        // default true
+ *
+ * @example
+ *   var pair = b.crypto.generateSigningKeyPair("ml-dsa-87");
+ *   var bom = b.ai.modelManifest.build({ model: { name: "x", version: "1" }});
+ *   var env = b.ai.modelManifest.sign(bom, { privateKeyPem: pair.privateKey });
+ *   typeof env.signature; // → "string"
+ */
+function sign(bom, opts) {
+  opts = opts || {};
+  if (!bom || typeof bom !== "object") {
+    throw new AiModelManifestError("aibom/bad-bom",
+      "sign: bom must be an object produced by build({...})");
+  }
+  validateOpts.requireNonEmptyString(opts.privateKeyPem,
+    "sign: opts.privateKeyPem", AiModelManifestError, "aibom/bad-key");
+  var canonical = canonicalJson.stringify(bom);
+  var signature = bCrypto.sign(Buffer.from(canonical, "utf8"), opts.privateKeyPem);
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "aibom.signed",
+      outcome:  "success",
+      metadata: {
+        modelName:    bom.metadata && bom.metadata.component && bom.metadata.component.name,
+        modelVersion: bom.metadata && bom.metadata.component && bom.metadata.component.version,
+        serialNumber: bom.serialNumber,
+      },
+    });
+  }
+  return Object.freeze({
+    bom:       bom,
+    signature: signature.toString("base64"),
+  });
+}
+
+/**
+ * @primitive b.ai.modelManifest.verify
+ * @signature b.ai.modelManifest.verify(envelope, publicKeyPem, opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11
+ * @related   b.ai.modelManifest.sign
+ *
+ * Verify an envelope produced by `sign(bom, {...})`. Re-canonicalizes
+ * the BOM with `canonicalJson.stringify` (NEVER trusts an embedded
+ * "signedBytes" field — defends the CVE-2025-29774 / CVE-2025-29775
+ * xml-crypto-style signature-substitution class) and checks the
+ * signature with `b.crypto.verify` against the supplied public-key
+ * PEM. Returns `{ valid, bom, reason }`; never throws.
+ *
+ * @opts
+ *   audit:           boolean,        // default true
+ *
+ * @example
+ *   var result = b.ai.modelManifest.verify(envelope, pair.publicKey);
+ *   if (!result.valid) console.log(result.reason);
+ */
+function verify(envelope, publicKeyPem, opts) {
+  opts = opts || {};
+  if (!envelope || typeof envelope !== "object" || !envelope.bom || !envelope.signature) {
+    return { valid: false, bom: null, reason: "envelope-shape" };
+  }
+  if (typeof publicKeyPem !== "string" || publicKeyPem.length === 0) {
+    return { valid: false, bom: null, reason: "public-key-required" };
+  }
+  if (envelope.bom.specVersion !== SPEC_VERSION || envelope.bom.bomFormat !== BOM_FORMAT) {
+    return { valid: false, bom: null, reason: "bom-spec-mismatch" };
+  }
+  var canonical = canonicalJson.stringify(envelope.bom);
+  var sigBuf;
+  try { sigBuf = Buffer.from(envelope.signature, "base64"); }
+  catch (_e) { return { valid: false, bom: null, reason: "signature-base64-bad" }; }
+  // `b.crypto.verify` can throw on malformed public-key PEM (Node's
+  // crypto layer surfaces `DECODER routines::unsupported` and similar).
+  // The documented contract here is `{ valid, bom, reason }` with no
+  // throws — wrap so a hostile / mistyped key returns a structured
+  // verdict instead of crashing the request path.
+  var ok;
+  try { ok = bCrypto.verify(Buffer.from(canonical, "utf8"), sigBuf, publicKeyPem); }
+  catch (_e2) { return { valid: false, bom: null, reason: "public-key-malformed" }; }
+  if (!ok) return { valid: false, bom: null, reason: "signature-invalid" };
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "aibom.verified",
+      outcome:  "success",
+      metadata: {
+        modelName:    envelope.bom.metadata && envelope.bom.metadata.component &&
+                      envelope.bom.metadata.component.name,
+        serialNumber: envelope.bom.serialNumber,
+      },
+    });
+  }
+  return { valid: true, bom: envelope.bom, reason: null };
+}
+
+// UUIDv4 via the framework's CSPRNG path. Used for `serialNumber`
+// defaults — operators may supply their own for cross-build stability.
+function _uuidUrn() {
+  var b = bCrypto.generateBytes(16);                                                            // allow:raw-byte-literal — RFC 9562 §4.1 UUIDv4 is a 16-byte (128-bit) primitive
+  b[6] = (b[6] & 0x0f) | 0x40;                                                                  // allow:raw-byte-literal — UUIDv4 version nibble (RFC 9562 §4.4)
+  b[8] = (b[8] & 0x3f) | 0x80;                                                                  // allow:raw-byte-literal — UUIDv4 variant nibble (RFC 9562 §4.4)
+  var h = b.toString("hex");
+  return "urn:uuid:" + h.slice(0, 8) + "-" + h.slice(8, 12) + "-" +                              // allow:raw-byte-literal — RFC 9562 §4 UUID text representation hex offsets (8-4-4-4-12)
+         h.slice(12, 16) + "-" + h.slice(16, 20) + "-" + h.slice(20);                            // allow:raw-byte-literal — RFC 9562 §4 UUID hex offsets
+}
+
+// package.json read lives behind the call to dodge a circular-load
+// chain: framework boot pulls index.js → ai-model-manifest → audit →
+// db → framework-error → constants → package.json. Reading
+// package.json at boot time would close the cycle. The lazy read is
+// idempotent and the result is cached on first call.
+var _cachedVersion = null;
+function _frameworkVersion() {
+  if (_cachedVersion) return _cachedVersion;
+  try { _cachedVersion = require("../package.json").version; }                                  // allow:inline-require — lazy package-version read to avoid boot-time circular load
+  catch (_e) { _cachedVersion = "0.0.0"; }
+  return _cachedVersion;
+}
+
+module.exports = {
+  build:               build,
+  sign:                sign,
+  verify:              verify,
+  SPEC_VERSION:        SPEC_VERSION,
+  BOM_FORMAT:          BOM_FORMAT,
+  AiModelManifestError: AiModelManifestError,
+};

package/lib/atomic-file.js

@@ -279,6 +279,88 @@ function pathTimestamp(date) {
   return d.toISOString().replace(/[:.]/g, "-");
 }
 
+// Generic [A-Za-z0-9_-]+ identifier shape used by conflictPath tag /
+// suffix validation. The pattern collides with similar shapes in
+// safe-buffer / redact / etc.; keeping the regex literal local to
+// atomic-file rather than pulling in a cross-module dependency for a
+// 30-byte regex keeps this file's lazy-load chain short.
+var IDENT_RE = /^[A-Za-z0-9_-]+$/;                                                              // allow:regex-no-length-cap — caller bounds length before .test() // allow:duplicate-regex — generic [A-Za-z0-9_-]+ identifier shape; extracting a one-line regex into a cross-module dependency would lengthen atomic-file's boot-time lazy chain for no behavioral win
+
+/**
+ * @primitive b.atomicFile.conflictPath
+ * @signature b.atomicFile.conflictPath(originalPath, opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.atomicFile.pathTimestamp, b.atomicFile.write
+ *
+ * Build a filesystem-portable conflict-suffix path next to
+ * `originalPath`, e.g. `notes.md` → `notes.conflict-2026-05-17T19-30-00Z.md`.
+ * Drop-in name for last-write-wins reconciliation in sync / backup /
+ * dual-control workflows. Preserves the original extension. Inserts a
+ * caller-supplied `tag` (default `conflict`) between the basename and
+ * the timestamp. The timestamp uses `pathTimestamp` so the result is
+ * portable across Windows (no `:` / `.`), macOS, and Linux. Same-second
+ * collision handling: pass `opts.suffix` (e.g. a per-row crypto-random
+ * hex) when multiple conflicts may land in the same second; otherwise
+ * the timestamp's millisecond field disambiguates.
+ *
+ * @opts
+ *   tag:       string,     // default "conflict"; sandwiched between basename and timestamp
+ *   timestamp: Date,       // default `new Date()`
+ *   suffix:    string,     // optional extra disambiguator appended after timestamp
+ *
+ * @example
+ *   var p = b.atomicFile.conflictPath("/srv/notes.md");
+ *   // → "/srv/notes.conflict-2026-05-17T20-30-00-123Z.md"
+ *
+ *   var withSuffix = b.atomicFile.conflictPath("/srv/notes.md", {
+ *     tag: "merge", suffix: "abc123",
+ *   });
+ *   // → "/srv/notes.merge-2026-05-17T20-30-00-123Z.abc123.md"
+ */
+function conflictPath(originalPath, opts) {
+  if (typeof originalPath !== "string" || originalPath.length === 0) {
+    throw new TypeError("b.atomicFile.conflictPath: originalPath must be a non-empty string");
+  }
+  opts = opts || {};
+  var tag = typeof opts.tag === "string" && opts.tag.length > 0 ? opts.tag : "conflict";
+  if (typeof tag !== "string" || tag.length === 0 || tag.length > 64) {                          // allow:raw-byte-literal — tag length cap, not bytes
+    throw new TypeError("b.atomicFile.conflictPath: tag must be a 1-64 char string");
+  }
+  if (!IDENT_RE.test(tag)) {                                                                     // allow:regex-no-length-cap — length-bounded immediately above
+    throw new TypeError("b.atomicFile.conflictPath: tag must match [A-Za-z0-9_-]+");
+  }
+  var stamp = pathTimestamp(opts.timestamp);
+  var suffix = "";
+  if (opts.suffix !== undefined) {
+    if (typeof opts.suffix !== "string" || opts.suffix.length === 0 ||
+        opts.suffix.length > 64) {                                                               // allow:raw-byte-literal — suffix length cap, not bytes
+      throw new TypeError("b.atomicFile.conflictPath: suffix must be a 1-64 char string");
+    }
+    if (!IDENT_RE.test(opts.suffix)) {                                                           // allow:regex-no-length-cap — length-bounded immediately above
+      throw new TypeError("b.atomicFile.conflictPath: suffix must match [A-Za-z0-9_-]+");
+    }
+    suffix = "." + opts.suffix;
+  }
+  // Walk from the rightmost `.` to split base + ext. POSIX `path` module
+  // does it portably; using string ops here keeps the helper free of
+  // additional require()s in the hot atomic-file file (which is loaded
+  // before most of the framework's lazy chain). Extension preservation
+  // walks ONLY the basename — a directory containing a `.` doesn't
+  // confuse the suffix.
+  var sep = originalPath.lastIndexOf("/");
+  var bsep = originalPath.lastIndexOf("\\");
+  var lastSep = sep > bsep ? sep : bsep;
+  var dir = lastSep >= 0 ? originalPath.slice(0, lastSep + 1) : "";
+  var name = lastSep >= 0 ? originalPath.slice(lastSep + 1) : originalPath;
+  var dotIdx = name.lastIndexOf(".");
+  // Treat a leading dot (dotfile, e.g. `.env`) as part of the base, not
+  // as an extension separator. `dotIdx === 0` → no extension.
+  var base = dotIdx > 0 ? name.slice(0, dotIdx) : name;
+  var ext  = dotIdx > 0 ? name.slice(dotIdx) : "";
+  return dir + base + "." + tag + "-" + stamp + suffix + ext;
+}
+
 /**
  * @primitive b.atomicFile.writeSync
  * @signature b.atomicFile.writeSync(filepath, data, opts)
@@ -935,6 +1017,7 @@ module.exports = {
   ensureDir:         ensureDir,
   copyDirRecursive:  copyDirRecursive,
   pathTimestamp:     pathTimestamp,
+  conflictPath:      conflictPath,
   AtomicFileError:   AtomicFileError,
   DEFAULTS:          DEFAULTS,
 };

package/lib/audit.js

@@ -296,6 +296,9 @@ var FRAMEWORK_NAMESPACES = [
   "localdb",    // b.localDb.thin (localdb.thin.opened / recovered / closed — desktop-daemon SQLite wrapper)
   "dataact",    // b.dataAct (EU Data Act 2023/2854 — product_declared / user_access / share_with_third_party / share_refused / switch_request)
   "idempotency", // b.middleware.idempotencyKey (idempotency.missing_key / bad_key / replay / key_reuse_mismatch / cache_store / store_read_failed / store_write_failed / skip_5xx / body_too_large — draft-ietf-httpapi-idempotency-key)
+  "aibom",            // b.ai.modelManifest (aibom.signed / aibom.verified — CycloneDX 1.6 ML-BOM)
+  "aicontentdetect",  // b.ai.aiContentDetect (aicontentdetect.report — AB-853 / EU AI Act Art. 50 inbound provenance)
+  "sdnotify",         // b.sdNotify (sdnotify.send / sdnotify.send.skipped — systemd Type=notify)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/content-credentials.js

@@ -30,6 +30,7 @@
 
 var bCrypto = require("./crypto");
 var canonicalJson = require("./canonical-json");
+var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var audit = require("./audit");
 var { defineClass } = require("./framework-error");
@@ -552,12 +553,151 @@ function signCose(manifest, opts) {
   };
 }
 
+/**
+ * @primitive b.contentCredentials.cacImplicitLabel
+ * @signature b.contentCredentials.cacImplicitLabel(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance cac-genai-label
+ * @related   b.contentCredentials.build, b.contentCredentials.cacImplicitLabelRead
+ *
+ * Build the GB 45438-2025 "Cybersecurity Technology — Labeling Method
+ * for Content Generated by Artificial Intelligence" implicit metadata
+ * block (effective 2025-09-01 per CAC Measures for Labeling AI-
+ * Generated Synthetic Content). The framework owns the implicit lane
+ * (metadata); the visible explicit label is application-layer
+ * rendering. Operators co-emit alongside the C2PA-COSE manifest by
+ * declaring `cac-genai-label` posture on `b.contentCredentials.build`.
+ *
+ * @opts
+ *   providerName:   string,         // UTF-8 ≤256 bytes
+ *   providerCode:   string,         // 18-char 统一社会信用代码 (Chinese USCC)
+ *   contentId:      string,         // globally-unique asset id
+ *   contentKind:    string,         // "text"|"image"|"audio"|"video"|"virtual-scene"|"other"
+ *   generatedAt:    string,         // ISO 8601 UTC
+ *
+ * @example
+ *   var label = b.contentCredentials.cacImplicitLabel({
+ *     providerName: "Example AI",
+ *     providerCode: "91110000600037341A",
+ *     contentId:    "asset-2026-05-17-abc123",
+ *     contentKind:  "image",
+ *     generatedAt:  "2026-05-17T20:00:00Z",
+ *   });
+ *   // → { aigcMarker: "AIGC", providerName, providerCode, contentId, contentKind, generatedAt }
+ */
+var CAC_KIND_ENUM = Object.freeze({
+  text: true, image: true, audio: true, video: true,
+  "virtual-scene": true, other: true,
+});
+var CAC_USCC_RE = /^[0-9A-HJ-NPQRTUWXY]{18}$/;                                                  // allow:raw-byte-literal — GB 32100-2015 USCC fixed length, not bytes // allow:raw-time-literal — 18 is char-count of the credit code, not seconds
+var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+function cacImplicitLabel(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new ContentCredentialsError("cac-implicit-label/bad-opts",
+      "cacImplicitLabel: opts object required");
+  }
+  validateOpts.requireNonEmptyString(opts.providerName,
+    "cacImplicitLabel: providerName", ContentCredentialsError,
+    "cac-implicit-label/bad-provider-name");
+  if (Buffer.byteLength(opts.providerName, "utf8") > STR_LEN_MAX) {
+    throw new ContentCredentialsError("cac-implicit-label/oversize-provider-name",
+      "cacImplicitLabel: providerName exceeds " + STR_LEN_MAX + " bytes (UTF-8)");
+  }
+  if (typeof opts.providerCode !== "string" || opts.providerCode.length !== 18 ||                // allow:raw-byte-literal — USCC fixed length (GB 32100-2015), not bytes // allow:raw-time-literal — string length, not seconds
+      !CAC_USCC_RE.test(opts.providerCode)) {                                                    // allow:regex-no-length-cap — length-bounded immediately above
+    throw new ContentCredentialsError("cac-implicit-label/bad-provider-code",
+      "cacImplicitLabel: providerCode must be an 18-char unified social credit code " +
+      "(统一社会信用代码 per GB 32100-2015 / GB 45438-2025)");
+  }
+  if (typeof opts.contentId !== "string" || opts.contentId.length === 0 ||
+      opts.contentId.length > 128) {                                                             // allow:raw-byte-literal — contentId char cap, not bytes
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-id",
+      "cacImplicitLabel: contentId must be 1-128 chars");
+  }
+  if (!ID_RE.test(opts.contentId)) {                                                             // allow:regex-no-length-cap — length-bounded immediately above
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-id",
+      "cacImplicitLabel: contentId must match [A-Za-z0-9._:/-]");
+  }
+  if (typeof opts.contentKind !== "string" || !CAC_KIND_ENUM[opts.contentKind]) {
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-kind",
+      "cacImplicitLabel: contentKind must be one of " +
+      Object.keys(CAC_KIND_ENUM).join("/"));
+  }
+  if (typeof opts.generatedAt !== "string" || !ISO8601_RE.test(opts.generatedAt)) {
+    throw new ContentCredentialsError("cac-implicit-label/bad-generated-at",
+      "cacImplicitLabel: generatedAt must be ISO 8601 UTC (e.g. 2026-05-17T20:00:00Z)");
+  }
+  return Object.freeze({
+    aigcMarker:   "AIGC",
+    providerName: opts.providerName,
+    providerCode: opts.providerCode,
+    contentId:    opts.contentId,
+    contentKind:  opts.contentKind,
+    generatedAt:  opts.generatedAt,
+  });
+}
+
+/**
+ * @primitive b.contentCredentials.cacImplicitLabelRead
+ * @signature b.contentCredentials.cacImplicitLabelRead(bytesOrObject)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance cac-genai-label
+ * @related   b.contentCredentials.cacImplicitLabel
+ *
+ * Reverse parser for the GB 45438-2025 implicit label. Accepts either
+ * a `Buffer` / `string` containing the JSON-serialized block (as the
+ * sender embedded in XMP / EXIF / MP4-box / etc.) or the already-
+ * parsed object. Returns the validated label shape or throws on any
+ * field that fails the same gate `cacImplicitLabel({...})` enforces.
+ *
+ * @example
+ *   var label = b.contentCredentials.cacImplicitLabelRead(jsonBuf);
+ *   // → { aigcMarker: "AIGC", providerName, providerCode, ... }
+ */
+function cacImplicitLabelRead(input) {
+  var obj;
+  if (Buffer.isBuffer(input)) {
+    try { obj = safeJson.parse(input.toString("utf8"), { maxBytes: 64 * 1024 }); }              // allow:raw-byte-literal — 64 KiB CAC label cap
+    catch (e) {
+      throw new ContentCredentialsError("cac-implicit-label/bad-json",
+        "cacImplicitLabelRead: JSON parse failed: " + (e && e.message));
+    }
+  } else if (typeof input === "string") {
+    try { obj = safeJson.parse(input, { maxBytes: 64 * 1024 }); }                                // allow:raw-byte-literal — 64 KiB CAC label cap
+    catch (e2) {
+      throw new ContentCredentialsError("cac-implicit-label/bad-json",
+        "cacImplicitLabelRead: JSON parse failed: " + (e2 && e2.message));
+    }
+  } else if (input && typeof input === "object") {
+    obj = input;
+  } else {
+    throw new ContentCredentialsError("cac-implicit-label/bad-input",
+      "cacImplicitLabelRead: input must be Buffer / string / object (got " + typeof input + ")");
+  }
+  if (obj.aigcMarker !== "AIGC") {
+    throw new ContentCredentialsError("cac-implicit-label/missing-aigc-marker",
+      "cacImplicitLabelRead: aigcMarker field must equal 'AIGC' (GB 45438-2025 §6)");
+  }
+  return cacImplicitLabel({
+    providerName: obj.providerName,
+    providerCode: obj.providerCode,
+    contentId:    obj.contentId,
+    contentKind:  obj.contentKind,
+    generatedAt:  obj.generatedAt,
+  });
+}
+
 module.exports = {
   build:      build,
   sign:       sign,
   signCose:   signCose,
   verify:     verify,
   required:   required,
+  cacImplicitLabel:     cacImplicitLabel,
+  cacImplicitLabelRead: cacImplicitLabelRead,
   REQUIRED_FIELDS: REQUIRED_FIELDS.slice(),
   COSE_ALGS:  Object.assign({}, COSE_ALGS),
   ContentCredentialsError: ContentCredentialsError,