@blamejs/core 0.15.11 → 0.15.13

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.15.x
 
+- v0.15.13 (2026-06-19) — **Consolidates a large set of duplicated, security-sensitive code paths — injected-dependency validation, positive-integer option caps, TOCTOU-safe file reads, markup escaping, audit emission, structured-field parsing, and untrusted-JWK import — onto shared hardened primitives, so a fix or guard now applies everywhere at once; adds a TOCTOU-safe file reader; and makes several configuration errors throw typed framework errors instead of a bare Error.** Across the framework, logic that had been hand-rolled in many places (and had quietly drifted between copies) is now single-sourced through shared primitives. The practical effect for operators is consistency: the strongest available guard is applied everywhere a given operation happens, rather than in whichever copy happened to have it. Injected dependencies (stores, backends, vaults, db handles, query objects) are validated through one contract; operator-tunable positive-integer options (pool sizes, byte caps, timeouts, stream limits) validate through one bounds primitive that forwards the caller's non-retryable / HTTP-status flags; the open-fd → fstat → read-fully pattern that several call sites used to defend file reads against a swap-after-stat race (CWE-367) is now the b.atomicFile.fdSafeReadSync primitive, with symlink refusal, inode-equality, a byte cap, and an integrity hash available as options and each caller's exact typed error preserved; and the XML/HTML markup escapers (including the b.guardHtml / b.guardSvg sanitizer output) route through one b.markupEscape so the base & < > " chain can't drift between them. A few configuration-validation paths that threw a bare Error (httpClient.configurePool, b.db stream-limit validation) now throw the module's typed framework error. No security defaults change; this release tightens and unifies existing protections rather than adding opt-ins. **Added:** *b.atomicFile.fdSafeReadSync(filepath, opts?)* — A TOCTOU-safe synchronous file read (CWE-367 / js/file-system-race): it opens the path read-only, then binds the size, content, and integrity measurement to the inode the fd holds open, so a swap between stat and read can't change which bytes are returned. Optional guards layer on top — maxBytes (refuse an over-cap file), refuseSymlink + inodeCheck (refuse a symlink source and any inode swap, the strongest posture for operator-writable paths), expectedHash (SHA3-512), encoding (return a string), allowShortRead — and an errorFor(kind, detail) callback lets each caller keep its own typed error. The framework's own file reads (atomic-file, the TLS certificate-path loader, the sealed-PEM source reader, the backup bundle reader) all route through it. · *Shared substrate primitives for previously-duplicated logic* — A set of shared primitives now back call sites that had each re-implemented the same logic: validateOpts.requireMethods (gains a `permanent` flag) for injected-dependency contract checks; numericBounds positive-finite-int validators (gain an errorOpts { permanent, statusCode }) for tunable integer options; b.markupEscape for the & < > " markup chain; structured-field parsing helpers (parseTagList, forEachKeyValue, splitUnquoted, stripDoubleQuotes, unfoldHeaderContinuations); crypto.importPublicJwk and crypto.makeBase64UrlDecoder; safeSql.toPositional; safeBuffer.makeByteCoercer; nonceStore.enforceReplay; and the audit/observability namespaced emitters. These are mostly invisible substrate — the operator-visible benefit is that a guard or fix added to one of them now covers every caller. **Changed:** *Configuration errors throw typed framework errors* — Two configuration-validation paths that threw a bare `Error` now throw the module's typed framework error: httpClient.configurePool (bad maxSockets / maxFreeSockets / keepAliveMsecs → HttpClientError, code httpclient/bad-opts) and the b.db stream-limit validation (Query.stream → DbQueryError). The thrown error remains an Error subclass, so existing `instanceof Error` / try-catch handling is unaffected; code that matched the old free-text message should match the typed error's `code` instead. Several routed validators also report a slightly more precise message ("positive finite integer" instead of "positive integer"). **Fixed:** *Webhook deliveries retry transient transport failures instead of dead-lettering them* — A delivery that failed with a transient transport error (connection reset, timeout, 5xx) was recorded as permanently failed and dead-lettered rather than retried. The destination-safety check (SSRF / blocked-host guard) now runs in its own step and is the only permanent failure; a transport failure backs off and retries up to the configured limit. · *Webhook deliveries table creates on MySQL* — The pending-delivery index used a partial-index (WHERE) clause that MySQL does not support, so the deliveries table failed to create on a MySQL backend. The index is now dialect-aware — partial on PostgreSQL / SQLite, plain on MySQL. · *Inline webhook delivery can't be double-sent by concurrent retry processing* — An inline delivery is now claimed (status set to in-flight with a claim timestamp) before the POST, so a concurrent retry pass can't pick up and re-send the same delivery; a row left in-flight by a crash is reclaimed after the stale-claim window. · *Audit checkpoint can never be anchored against a replaced database* — close() fires a best-effort final checkpoint as the database shuts down. In a narrow close-then-reopen window that checkpoint's write could resume after a fresh database had opened and anchor the prior database's chain tip into it. checkpoint() now binds to the database it read the tip from and refuses to write (returns null, fail-closed) if that handle has since been closed or replaced — so a checkpoint is only ever written against the database it measured. **Security:** *TOCTOU-safe file reads applied uniformly* — The open-fd → fstat → read pattern that anchors a file read to one inode against a swap-after-stat race is now centralized in b.atomicFile.fdSafeReadSync, and every framework file read routes through it. The sealed-PEM source reader keeps the strongest posture (symlink refusal + inode-equality + byte cap), and those guards are now available as options to any caller — a re-introduced hand-rolled read-loop is flagged by a codebase-pattern detector. · *Injected-dependency and integer-option validation can't silently drift* — Injected stores / backends / vaults / db handles / query objects are validated through one contract (validateOpts.requireMethods), and operator-tunable positive-integer options through one bounds primitive (numericBounds), both forwarding the caller's non-retryable / HTTP-status error flags so a config error stays permanent / carries its 4xx. Inverse detectors flag any re-introduced inline check, so the validation can no longer be partially copied or weakened in one place. · *Single markup-escape chain for the HTML/SVG sanitizers* — The b.guardHtml and b.guardSvg sanitizer output escapers, the AI-Act transparency and mail HTML escapers, and the XML report escapers now share one b.markupEscape for the base & < > " chain (apostrophe form as a parameter; each caller keeps its own input coercion and any extra escapes such as guardHtml.escapeAttr's backtick / = IE-attribute-injection hardening). Byte-for-byte parity with the prior escapers was verified across an XSS-vector corpus, so the consolidation cannot have introduced an escaping gap; a re-inlined & < > " chain anywhere else is flagged by a detector. · *One hardening point for untrusted public-JWK import* — The createPublicKey-from-JWK call that imports attacker-controlled key material (DID publicKeyJwk, DNSKEY, COSE_Key, DPoP / OAuth / OIDC / DBSC proof JWKs) is centralized in b.crypto.importPublicJwk, so the untrusted-key import has a single audited home; each caller keeps its own kty/crv pre-validation and typed error. · *Linear-time Content-Security-Policy header parsing* — The CSP response-header parser split directives on a `/\s*,\s*/` regex that ran in O(n^2) on a long comma-less run of whitespace, letting a crafted header stall a worker (js/polynomial-redos). It now splits on the literal comma and trims each item, which is linear and byte-for-byte equivalent. · *Parsed INI and OpenAPI path maps can't reach Object.prototype* — The INI parser already refuses a `__proto__` / `constructor` / `prototype` section or key (it throws before any write); as defense-in-depth, every parsed node — and the OpenAPI paths map keyed by URL pattern — is now a null-prototype object, so even a future gap could only ever set an own property, never mutate Object.prototype (CWE-1321).
+
+- v0.15.12 (2026-06-14) — **Hardens a set of defense-in-depth seams: a single-pass structured-field unescape, a constant-time content-digest member match, complete reserved-character stripping, a Trojan-Source escape on the boot logger, generic body-parse error responses, and an audit trail whenever outbound TLS certificate validation is disabled.** A sweep of low-severity but real hardening items. RFC 8941 structured-field string values (HTTP Message Signatures, Client Hints, Cache-Control) were un-escaped with two chained replaces that mis-decoded an escaped backslash adjacent to another escape; they now use one left-to-right pass that decodes each escape exactly once. The HTTP Message Signature content-digest check dropped a dead identity-replace and now matches the sha3-512 member by an exact, top-level, constant-time comparison instead of an unanchored substring scan. b.guardFilename's reserved-character strip used a non-global regex that left every separator after the first; it now strips all of them. The boot logger's TTY branch wrote raw text, bypassing the Trojan-Source / control-character escape the main logger applies — it now escapes the bidi and C0/newline control classes on every sink. The body parser no longer echoes a caught exception's detail (an fs errno + temp path, or a parse hook's thrown message) to the HTTP client — the client gets a generic status phrase while the full detail stays on the audit chain. And any outbound TLS connection that runs with peer-certificate validation disabled (an explicit operator opt-in, never a default) now emits a tls.insecure_skip_verify audit + observability event so the degraded posture is visible for compliance and incident response. **Added:** *b.structuredFields.unescapeSfStringBody(body)* — A single-pass decode of the RFC 8941 §3.3.3 quoted-string backslash escapes (the bytes between the surrounding quotes). It replaces the chained two-`.replace()` form, which is not equivalent to one decode — whichever pass runs first can rewrite a backslash the other escape sequence owns, so a lone escaped backslash decoded to two. The HTTP Message Signature, Client Hints, and Cache-Control sf-string readers now route through it. · *tls.insecure_skip_verify audit event* — b.network.tls.auditInsecureTls(meta) emits an audit + observability event at the point an outbound TLS connection honors rejectUnauthorized:false / allowInsecure. The connectWithEch, OTLP-gRPC log stream, syslog-TLS log stream, and SMTP transports all emit it when an operator disables certificate validation — parallel to the existing tls.classical_downgrade audit. No default changes; the framework never disables validation itself. **Security:** *Single-pass structured-field string unescape* — The RFC 8941 sf-string readers in HTTP Message Signatures (Signature-Input covered-component names), Client Hints, and Cache-Control directive values un-escaped with `.replace(/\\\\/g,"\\").replace(/\\"/g,'"')` — two sequential passes that mis-decode adjacent escapes (a lone escaped backslash became two). All four sites now use the single-pass b.structuredFields.unescapeSfStringBody. It is fail-closed (a mis-decoded covered-component name just fails the signature check, never bypasses it); the fix restores RFC-conformant interop with peers that legitimately escape these values. · *Constant-time, member-anchored content-digest verification* — b.crypto.httpSig.verify's covered content-digest check dropped a dead no-op replace and now parses the Content-Digest header into its top-level members and matches the sha3-512 member EXACTLY, in constant time (b.crypto.timingSafeEqual), rather than scanning for the digest text as a substring anywhere in the header. The Content-Digest header is already bound by the signature, so the substring form was not reachably exploitable; the change removes the latent ambiguity and the timing channel. · *Reserved-character filename strip removes every occurrence* — b.guardFilename's reservedCharPolicy:"strip" (the permissive profile) used a non-global regex, so only the FIRST reserved character — including path separators — was replaced and the rest leaked through. The strip is now global: every reserved character is removed. Not a traversal bypass (the unconditional security floor still throws on `..`, null bytes, NTFS ADS, UNC, overlong UTF-8), but the strip is now complete and consistent. · *Boot logger escapes control + bidi characters on every sink* — The boot-time logger's TTY branch wrote the raw message, bypassing the Trojan-Source (bidi) and control-character escapes the main logger applies — a hostile message could forge extra log lines on a terminal (CWE-117) or re-order the visible line (CVE-2021-42574). Both boot branches now escape the bidi and C0/newline control classes, matching the create() path and the logger's advertised guarantee. · *Body-parser error responses never echo internal detail* — The body-parser's terminal error path surfaced a caught exception's message verbatim to the HTTP client — a multipart filesystem error leaked the errno + temp path, and a parse hook's thrown error (which can carry secrets) was echoed back. The client now gets a curated message only for a framework-classified 4xx error and a generic status phrase otherwise; the parse-hook wrapper carries a fixed message, and full diagnostics stay on the audit chain server-side (CWE-209). The cluster leader-discovery endpoint's error body is generalized the same way.
+
 - v0.15.11 (2026-06-14) — **Replaces a family of quadratic-time regexes that hostile input could use to stall a worker with linear scans, refuses a relocatable sealed-cell downgrade on the read side, fails closed when enabling row-level security behind a non-native driver, and scans the vendored crypto for known CVEs on every build.** Several text-handling primitives stripped trailing whitespace or extracted a mail address with a regex whose backtracking is quadratic in the input length on adversarial strings — a request body, a YAML document, a CSV cell, or a From header crafted as a long run of spaces could pin a worker's CPU. Each is now a linear character scan with identical output. The HTML-content check the MCP tool surface applies gained the vbscript: and data:text/html vectors it was missing. On the data-at-rest side, an AAD-bound (or per-row-key) column now refuses a plain, unbound vault cell on read — a relocatable envelope an attacker with write access could copy in from another row defeats the cross-row binding, so the field is nulled rather than surfaced; operators mid-migration opt back in with registerTable({ allowPlainMigration: true }). declareRowPolicy now treats row-level-security as enabled only on a value that unambiguously means true, so a non-native Postgres driver that returns the string "f" can no longer be read as "already on" and silently skip the ENABLE that protects the table's rows. Finally, because the framework's crypto is vendored rather than installed, npm audit and Dependabot never see it: every build now matches the vendored versions against the OSV vulnerability database, with a complementary Semgrep pass and workflow-file static analysis alongside. **Added:** *b.safeBuffer.indexAfterOpenTag(html, tagName)* — A linear helper that returns the offset just past a `<tag ...>` opening tag (case-insensitive), or -1 when absent or unterminated — the insertion point a response rewriter uses to splice content after <body> or <head> without a regex. It replaces the O(n^2) html.match(/<body[^>]*>/i) shape and is stricter than it: a real tag boundary is required after the name, so <bodyfoo> is not mistaken for <body>. **Security:** *Linear-time replacements across a family of quadratic regexes (ReDoS class)* — Several primitives located or stripped text with a regex whose backtracking is quadratic in V8 on adversarial input (CWE-1333): b.safeBuffer and the safe-env / safe-yaml / guard-csv parsers stripped trailing horizontal whitespace with /[ \t]+$/; b.mail extracted the address from a `Name <addr>` header with /<([^>]+)>/; the bot-disclosure and speculation-rules response middleware found the <body> insertion point with /<body[^>]*>/i; and the BIMI certificate-chain splitter walked PEM blocks with a lazy /BEGIN[\s\S]*?END/ scan. A crafted field — a long run of spaces, an unterminated bracket, a body carrying many <body starts with no closing >, a chain of BEGIN markers — could drive a worker's CPU to seconds of work. Each is now a linear scan: a shared b.safeBuffer.stripTrailingHspace (backward char walk), b.safeBuffer.indexAfterOpenTag (forward indexOf walk for the tag insertion point), a forward indexOf for address extraction, and an indexOf walk for the PEM split. Output is byte-identical (the tag-find is stricter — it no longer mistakes <bodyfoo> for <body>), and 400K-character adversarial inputs that took 8–85 seconds now complete in under 2 ms. · *MCP HTML-content check covers vbscript: and data:text/html* — The dangerous-markup check applied to text/html tool content matched <script>/<iframe>/<object>/<embed> and javascript: URLs but not the vbscript: scheme or data:text/html payloads. Both are now refused; data: URLs carrying non-HTML media (data:image/png and similar) are unaffected. · *AAD-bound columns refuse a plain sealed cell on read* — b.cryptoField.unsealRow now refuses a plain, unbound vault: envelope found on an AAD-bound (or per-row-key) column and nulls the field instead of returning it. A plain envelope carries no per-cell binding, so a writer who could place one — copied from anywhere under the same vault root — would otherwise relocate a value across rows or columns and defeat the copy-protection the AAD binding advertises. Operators migrating pre-AAD rows up to bound ciphertext opt into a bounded acceptance window with registerTable({ allowPlainMigration: true }) and clear it when migration completes. · *Row-level-security enablement fails closed on non-native drivers* — b.db.declareRowPolicy read pg_class.relrowsecurity to skip a redundant ENABLE ROW LEVEL SECURITY, but tested it with a bare truthiness check. A native pg driver returns a JS boolean; a proxy or ORM may return the string "f" for a disabled table — and "f" is truthy, so the check read it as already-enabled and silently skipped the ENABLE, leaving every row in the table unprotected while the migration reported success. RLS now counts as enabled only on a value that unambiguously means true (true, 1, or "t"/"true"/"1"/"on"/"yes"); every other shape re-issues ENABLE, a harmless no-op on an already-enabled table. · *Vendored-crypto CVE scanning, complementary SAST, and workflow static analysis in CI* — The framework ships zero npm runtime dependencies — its crypto (the noble suite, the WebAuthn server, the PKI layer) is vendored under lib/vendor/, where npm audit, Dependabot, and Socket cannot see it. Every build now generates a CycloneDX SBOM of the vendored tree (each library carrying an npm purl) and runs it through OSV-Scanner, matching the exact pinned version against the OSV vulnerability database; a published CVE or GHSA affecting a vendored version fails the build so the copy is refreshed before merge. A Semgrep pass (registry security-audit + javascript packs at ERROR severity) runs alongside CodeQL as complementary SAST, and actionlint statically checks the workflow files. All three install the OSS tool from its upstream release, matching the existing secret-scan gate's posture. **Detectors:** *Quadratic trailing-whitespace and tag-find regex detectors* — Two codebase-pattern detectors refuse reintroduction of the quadratic shapes: the /[ \t]+$/ trailing-whitespace strip (as .replace, .test, or via the named TRAILING_HSPACE_RE export) outside the linear helper that owns it, and the str.match(/<tag[^>]*>/) document-tag find that the response middleware must route through b.safeBuffer.indexAfterOpenTag. Each is proven to fire on the removed shape and stay silent on the linear replacement, so the ReDoS class cannot creep back into a new parser, guard, or response rewriter.
 
 - v0.15.10 (2026-06-13) — **Makes S3 Object-Lock version erasure reachable through the object store, and pins the build toolchain's native binary to a reviewed hash.** The object store gains the versioned-delete surface its S3 Object Lock support always needed for real erasure. An unversioned delete on a versioning-enabled (Object-Lock) bucket only writes a delete-marker — the data version survives — so the framework's own delete could report success while a record protected for compliance, or one a data subject asked to erase, stayed on disk. b.objectStore / b.storage now carry a versionId: put and saveRaw return the version they created, deleteFile(key, { versionId, bypassGovernanceRetention }) targets a specific version (refused — not silently delete-markered — when it is under an active retention), and listVersions enumerates versions and delete-markers so an erasure workflow can find them. Backends with no version surface (the filesystem backend, and the current Azure and GCS adapters) refuse a versioned delete loudly rather than silently dropping the current object. Separately, the build toolchain's native bundler binary is now verified against a reviewed SHA-256 pin so a tampered or drifted binary is caught before it bundles the framework. **Added:** *Versioned object delete + listVersions for S3 Object-Lock erasure* — b.storage.deleteFile and the b.objectStore sigv4 backend now accept opts.versionId to erase a specific object version, and opts.bypassGovernanceRetention to lift a GOVERNANCE-mode retention for callers with the permission (COMPLIANCE stays immutable to everyone). b.storage.saveRaw and the backend put now return the versionId they created on a versioning-enabled bucket, and a new b.storage.listVersions(prefix) / backend listVersions enumerates every version and delete-marker (key, versionId, isLatest, deleteMarker, size, lastModified, etag) so a right-to-erasure or crypto-shred workflow can target prior versions. On a backend with no version surface, listVersions throws VERSIONS_UNSUPPORTED and a versioned delete throws VERSIONID_UNSUPPORTED rather than silently acting on the current object. · *b.localDb.thin reaches SQLite resource-limit parity (limits option)* — b.localDb.thin now opens its node:sqlite handle with the same parse-time statement-size cap as b.db and the CLI — a SQL statement over 1 MiB is rejected at parse time, the SQLITE_LIMIT_LENGTH floor that guards prepare()/exec() of raw SQL against an attacker-influenced megaquery (SQLite's default is 1 GB). The cap is on by default; a new limits option (e.g. { sqlLength: 2 * 1024 * 1024 } or other SQLITE_LIMIT_* keys) lets an operator raise or extend it. Previously the thin opener had no limits plumbing, so a consumer on that path could not reach parity with the rest of the framework's SQLite surface. **Fixed:** *S3 Object-Lock version erasure is reachable through the framework delete path* — On a versioning-enabled (Object-Lock) bucket, an unversioned DELETE only writes a delete-marker — the protected data version survives untouched — yet the framework's delete had no versionId surface, so it issued the unversioned form and reported success while the bytes the lock protects remained. A retention or legal hold could therefore look enforced to the framework caller while the operation WORM actually blocks was unreachable. The delete path now targets the exact version: deleting a version under a COMPLIANCE retention is refused (it throws, even with bypassGovernanceRetention), a no-retention version erases cleanly, and the enforcement is proven end-to-end against MinIO through the framework's own API. · *b.configDrift.verifyVendorIntegrity is now working-directory-independent* — The vendored-dependency integrity check resolved each manifest file path against process.cwd(), so it only worked when run from the application root. Run from anywhere else it read-failed every entry (reporting ok:false), and under a crafted working directory that happened to contain a clean vendor tree it could hash a different tree than the one actually loaded. It now resolves each file under the framework's own vendor directory by default — the tree loaded at runtime — and honors an explicit libVendorDir for verifying a deployed tree elsewhere, so the result no longer depends on where the process was started. **Security:** *Build toolchain native binary pinned to a reviewed hash* — The native bundler binary the build toolchain runs (esbuild's per-platform compiler, a development dependency that never ships in the runtime) is now verified against a SHA-256 pin captured by diffing the published package tarballs and hashing the binary. The build gate fails if the on-disk binary does not match the reviewed hash for its (version, platform); for a version that has not been reviewed it notes the gap and skips rather than trusting an unverified binary. A cross-artifact check keeps the version in agreement across package.json, the CI install step, and the hash map, so the gate can never quietly test a version that was never diffed — closing a real drift where CI had been installing an older patch than package.json declared. The reviewed diff is benign: version strings plus an installer size-bound and error-message hardening, no new install hooks, files, or network paths, and no runtime-dependency impact. **Detectors:** *Object-store erasure guard, esbuild-pin agreement, + structural re-anchoring of the lint detectors* — A new guard locks the object-store delete path to the versioned-erasure contract: b.storage.deleteFile must thread versionId to the backend, so it can never silently revert to the WORM-blind unversioned delete. A second guard enforces that the esbuild build-tool version agrees across package.json, the CI install step, and the binary-hash map, so a future bump can't update one and leave the gate testing an unreviewed version. Separately, the framework's internal codebase-pattern lint detectors were re-anchored from fixed character spans to structural code boundaries, so they keep matching the code they guard as those functions grow rather than aging out of range; reviving them surfaced a few internal validation and transaction sites that now route through shared helpers (a required positive-integer-with-range validator and an async transaction wrapper) instead of hand-rolling the check. No public API change.

package/index.js

@@ -225,6 +225,7 @@ var guardYaml = require("./lib/guard-yaml");
 var guardXml = require("./lib/guard-xml");
 var guardMarkdown = require("./lib/guard-markdown");
 var guardEmail = require("./lib/guard-email");
+var guardText = require("./lib/guard-text");
 var guardDomain = require("./lib/guard-domain");
 var guardUuid = require("./lib/guard-uuid");
 var guardCidr = require("./lib/guard-cidr");
@@ -609,6 +610,7 @@ module.exports = {
   guardXml:         guardXml,
   guardMarkdown:    guardMarkdown,
   guardEmail:       guardEmail,
+  guardText:        guardText,
   guardDomain:      guardDomain,
   guardUuid:        guardUuid,
   guardCidr:        guardCidr,

package/lib/a2a-tasks.js

@@ -51,7 +51,7 @@ var validateOpts  = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var httpClient = lazyRequire(function () { return require("./http-client"); });
-var audit      = lazyRequire(function () { return require("./audit"); });
+var auditEmit  = require("./audit-emit");
 var C          = require("./constants");
 
 // A2aTasksError is the per-call error class — separate from A2aError
@@ -82,15 +82,7 @@ var TASK_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 var SKILL_NAME_RE = /^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/;   // allow:duplicate-regex — RFC-3986-unreserved identifier shape, shared across mcp.js + mcp-tool-registry.js
 // RFC-3986-unreserved identifier shape (length cap inside regex), not a byte count
 
-function _emitAudit(action, metadata, outcome) {
-  try {
-    audit().safeEmit({
-      action:   action,
-      outcome:  outcome || "success",
-      metadata: metadata,
-    });
-  } catch (_e) { /* best-effort */ }
-}
+var _emitAudit = auditEmit.emit;
 
 var bCrypto = lazyRequire(function () { return require("./crypto"); });
 
@@ -515,19 +507,11 @@ function _jsonRpcError(id, code, message, data) {
 }
 
 function _readBody(req, maxBytes) {
-  return new Promise(function (resolve, reject) {
-    var collector = safeBuffer.boundedChunkCollector({
-      maxBytes:    maxBytes,
-      errorClass:  A2aTasksError,
-      sizeCode:    "a2a-tasks/body-too-large",
-      sizeMessage: "a2a-tasks: request body exceeded " + maxBytes + " bytes",
-    });
-    req.on("data", function (chunk) {
-      try { collector.push(chunk); }
-      catch (capErr) { reject(capErr); }
-    });
-    req.on("end", function () { resolve(collector.result()); });
-    req.on("error", function (e) { reject(e); });
+  return safeBuffer.collectStream(req, {
+    maxBytes:    maxBytes,
+    errorClass:  A2aTasksError,
+    sizeCode:    "a2a-tasks/body-too-large",
+    sizeMessage: "a2a-tasks: request body exceeded " + maxBytes + " bytes",
   });
 }
 

package/lib/acme.js

@@ -42,6 +42,7 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var safeBuffer = require("./safe-buffer");
 
 var C = require("./constants");
 var asn1 = require("./asn1-der");
@@ -92,10 +93,6 @@ function _emitAudit(audit, action, outcome, metadata) {
   } catch (_e) { /* audit best-effort */ }
 }
 
-function _emitObs(name, fields) {
-  try { observability().safeEvent(name, 1, fields || {}); } catch (_e) { /* obs best-effort */ }
-}
-
 // JWK shape for an ES256 (P-256) public key — RFC 7518 §6.2.1.
 function _publicJwkFromKeyObject(keyObject) {
   if (!keyObject || typeof keyObject.export !== "function") {
@@ -479,7 +476,7 @@ function create(opts) {
     state.directory = body;
     _emitAudit(audit, "acme.directory.fetched", "success",
       { directoryUrl: state.directoryUrl, hasAri: typeof body.renewalInfo === "string" });
-    _emitObs("acme.directory.fetched", { hasAri: typeof body.renewalInfo === "string" });
+    observability().safeEvent("acme.directory.fetched", 1, { hasAri: typeof body.renewalInfo === "string" });
     return body;
   }
 
@@ -557,7 +554,7 @@ function create(opts) {
       var id = orderOpts.identifiers[i];
       if (!id || typeof id.type !== "string" || typeof id.value !== "string" ||
           id.type.length === 0 || id.value.length === 0 ||
-          id.value.length > C.BYTES.bytes(255)) {
+          safeBuffer.byteLengthOf(id.value) > C.BYTES.bytes(255)) {
         throw _err("acme/bad-identifier",
           "newOrder: identifier must be { type: string, value: string<=255 }", true);
       }
@@ -573,7 +570,7 @@ function create(opts) {
     // the field. v1-defensible scope: refuse non-string + cap length so
     // attacker-supplied profile values can't bloat the JSON payload.
     if (typeof orderOpts.profile === "string") {
-      if (orderOpts.profile.length === 0 || orderOpts.profile.length > C.BYTES.bytes(64)) {
+      if (orderOpts.profile.length === 0 || safeBuffer.byteLengthOf(orderOpts.profile) > C.BYTES.bytes(64)) {
         throw _err("acme/bad-profile",
           "newOrder: profile name must be a non-empty string <= 64 bytes", true);
       }
@@ -615,7 +612,7 @@ function create(opts) {
     } else {
       throw _err("acme/bad-csr", "finalize: csr must be a DER Buffer or PEM string", true);
     }
-    if (csrDer.length === 0 || csrDer.length > C.BYTES.kib(64)) {
+    if (csrDer.length === 0 || safeBuffer.byteLengthOf(csrDer) > C.BYTES.kib(64)) {
       throw _err("acme/bad-csr",
         "finalize: CSR DER size out of range (got " + csrDer.length + " bytes)", true);
     }
@@ -675,7 +672,7 @@ function create(opts) {
     }
     _emitAudit(audit, "acme.cert.issued", "success",
       { orderUrl: order.url, bytes: pem.length });
-    _emitObs("acme.cert.issued", { bytes: pem.length });
+    observability().safeEvent("acme.cert.issued", 1, { bytes: pem.length });
     return pem;
   }
 
@@ -846,7 +843,7 @@ function create(opts) {
     }
     for (var di = 0; di < opts2.domains.length; di += 1) {
       var d = opts2.domains[di];
-      if (typeof d !== "string" || d.length === 0 || d.length > C.BYTES.bytes(255)) {
+      if (typeof d !== "string" || d.length === 0 || safeBuffer.byteLengthOf(d) > C.BYTES.bytes(255)) {
         throw _err("acme/bad-csr-domain",
           "buildCsr: domains[" + di + "] must be a non-empty string <= 255 bytes", true);
       }
@@ -1042,7 +1039,7 @@ function create(opts) {
         windowEnd:      ari.suggestedWindow.end,
         nowIso:         new Date(nowMs).toISOString(),
       });
-      _emitObs("acme.cert.renew.skipped", { reason: "before-window" });
+      observability().safeEvent("acme.cert.renew.skipped", 1, { reason: "before-window" });
       var ret = { shouldRenew: false, reason: "before-window", ari: ari };
       if (jitter) ret.renewAt = new Date(renewAtMs).toISOString();
       return ret;
@@ -1053,7 +1050,7 @@ function create(opts) {
         reason:         "past-window",
         windowEnd:      ari.suggestedWindow.end,
       });
-      _emitObs("acme.cert.renew.scheduled", { reason: "past-window" });
+      observability().safeEvent("acme.cert.renew.scheduled", 1, { reason: "past-window" });
       var rp = { shouldRenew: true, reason: "past-window", ari: ari };
       if (jitter) rp.renewAt = new Date(renewAtMs).toISOString();
       return rp;
@@ -1064,7 +1061,7 @@ function create(opts) {
       windowEnd:      ari.suggestedWindow.end,
       renewAt:        jitter ? new Date(renewAtMs).toISOString() : null,
     });
-    _emitObs("acme.cert.renew.scheduled", { reason: "in-window" });
+    observability().safeEvent("acme.cert.renew.scheduled", 1, { reason: "in-window" });
     var ri = { shouldRenew: true, reason: "in-window", ari: ari };
     if (jitter) ri.renewAt = new Date(renewAtMs).toISOString();
     return ri;
@@ -1140,7 +1137,7 @@ function create(opts) {
         "revokeCert returned " + rsp.statusCode, true, rsp.statusCode);
     }
     _emitAudit(audit, "acme.cert.revoked", "success", { reason: ropts.reason || null });
-    _emitObs("acme.cert.revoked", { reason: ropts.reason || 0 });
+    observability().safeEvent("acme.cert.revoked", 1, { reason: ropts.reason || 0 });
     return true;
   }
 
@@ -1190,7 +1187,7 @@ function create(opts) {
     privateKey = newPrivateKey;
     publicJwk  = newPublicJwk;
     _emitAudit(audit, "acme.account.key_rotated", "success", { accountUrl: state.accountUrl });
-    _emitObs("acme.account.key_rotated", {});
+    observability().safeEvent("acme.account.key_rotated", 1, {});
     return true;
   }
 
@@ -1332,7 +1329,7 @@ function create(opts) {
     if (!opts2 || typeof opts2 !== "object" || typeof opts2.identifier !== "string" || opts2.identifier.length === 0) {
       throw _err("acme/bad-identifier", "dnsAccount01ChallengeRecord: opts.identifier (host) is required", true);
     }
-    if (opts2.identifier.length > C.BYTES.bytes(255)) {
+    if (safeBuffer.byteLengthOf(opts2.identifier) > C.BYTES.bytes(255)) {
       throw _err("acme/bad-identifier", "dnsAccount01ChallengeRecord: identifier exceeds 255 bytes", true);
     }
     if (!state.accountUrl) {

package/lib/agent-event-bus.js

@@ -70,6 +70,7 @@ var agentAudit            = require("./agent-audit");
 var envelopeMac           = require("./agent-envelope-mac");
 var safeJson              = require("./safe-json");
 var bCrypto               = require("./crypto");
+var boundedMap            = require("./bounded-map");
 
 var audit                 = lazyRequire(function () { return require("./audit"); });
 
@@ -149,10 +150,10 @@ function create(opts) {
 
 function _registerTopic(topics, name, topicOpts, auditImpl) {
   guardEventBusTopic.validate(name);
-  if (topics.has(name)) {
+  boundedMap.requireAbsent(topics, name, function () {
     throw new AgentEventBusError("agent-event-bus/topic-duplicate",
       "registerTopic: '" + name + "' already registered");
-  }
+  });
   if (!topicOpts.schema || typeof topicOpts.schema !== "object") {
     throw new AgentEventBusError("agent-event-bus/bad-schema",
       "registerTopic: schema required (flat key→type map)");
@@ -193,10 +194,10 @@ function _registerTopic(topics, name, topicOpts, auditImpl) {
 // lifecycle traceability.
 function _unregisterTopic(topics, name, auditImpl) {
   guardEventBusTopic.validate(name);
-  if (!topics.has(name)) {
+  boundedMap.requirePresent(topics, name, function () {
     throw new AgentEventBusError("agent-event-bus/unknown-topic",
       "unregisterTopic: '" + name + "' not registered");
-  }
+  });
   topics.delete(name);
   _safeAudit(auditImpl, "agent.event_bus.topic_unregistered", null, { name: name });
 }

package/lib/agent-idempotency.js

@@ -143,11 +143,8 @@ function _ensureSealTable() {
 function create(opts) {
   opts = opts || {};
   var store = opts.store || _inMemoryBackend(opts.maxInMemoryEntries);
-  if (typeof store.get !== "function" || typeof store.put !== "function" ||
-      typeof store.delete !== "function") {
-    throw new AgentIdempotencyError("agent-idempotency/bad-store",
-      "create: store must expose { get, put, delete }");
-  }
+  validateOpts.requireMethods(store, ["get", "put", "delete"],
+    "create: store", AgentIdempotencyError, "agent-idempotency/bad-store");
   var ttlMs = typeof opts.ttlMs === "number" ? opts.ttlMs : DEFAULT_TTL_MS;
   if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
     throw new AgentIdempotencyError("agent-idempotency/bad-ttl",

package/lib/agent-orchestrator.js

@@ -157,11 +157,8 @@ var _saltedFnvBasisCache = null;
 function create(opts) {
   opts = opts || {};
   var backend = opts.backend || _inMemoryBackend();
-  if (typeof backend.get !== "function" || typeof backend.set !== "function" ||
-      typeof backend.delete !== "function" || typeof backend.list !== "function") {
-    throw new AgentOrchestratorError("agent-orchestrator/bad-backend",
-      "b.agent.orchestrator.create: backend must expose { get, set, delete, list }");
-  }
+  validateOpts.requireMethods(backend, ["get", "set", "delete", "list"],
+    "b.agent.orchestrator.create: backend", AgentOrchestratorError, "agent-orchestrator/bad-backend");
   var clusterImpl = opts.cluster || cluster();
   var auditImpl   = opts.audit   || audit();
   var permissions = opts.permissions || null;

package/lib/agent-saga.js

@@ -71,6 +71,7 @@
 
 var lazyRequire        = require("./lazy-require");
 var { defineClass }    = require("./framework-error");
+var validateOpts       = require("./validate-opts");
 var guardSagaConfig    = require("./guard-saga-config");
 var bCrypto            = require("./crypto");
 var agentAudit         = require("./agent-audit");
@@ -118,11 +119,8 @@ function create(config) {
   // `agent.saga.no_state_store` surfaces the posture per call).
   var stateStore = config.stateStore || null;
   if (stateStore !== null) {
-    if (typeof stateStore.saveStep !== "function" ||
-        typeof stateStore.loadResumePoint !== "function") {
-      throw new AgentSagaError("agent-saga/bad-state-store",
-        "create: stateStore must expose { saveStep, loadResumePoint, markCompleted?, markFailed? }");
-    }
+    validateOpts.requireMethods(stateStore, ["saveStep", "loadResumePoint"],
+      "create: stateStore", AgentSagaError, "agent-saga/bad-state-store");
   }
   return {
     run:                    function (ctx, initialState, opts) { return _run(config, auditImpl, stateStore, ctx, initialState, opts || {}); },

package/lib/agent-tenant.js

@@ -153,11 +153,8 @@ var TENANT_KEY_BYTES = 32;
 function create(opts) {
   opts = opts || {};
   var backend = opts.backend || _inMemoryBackend();
-  if (typeof backend.get !== "function" || typeof backend.set !== "function" ||
-      typeof backend.delete !== "function" || typeof backend.list !== "function") {
-    throw new AgentTenantError("agent-tenant/bad-backend",
-      "create: backend must expose { get, set, delete, list }");
-  }
+  validateOpts.requireMethods(backend, ["get", "set", "delete", "list"],
+    "create: backend", AgentTenantError, "agent-tenant/bad-backend");
   var auditImpl   = opts.audit || audit();
   var permissions = opts.permissions || null;
   var ctx = {

package/lib/ai-adverse-decision.js

@@ -99,25 +99,12 @@ function wrap(opts) {
   var legalBasis = opts.legalBasis;
   var decide = opts.decide;
   var onAdverse = typeof opts.onAdverse === "function" ? opts.onAdverse : null;
-  var auditOn = opts.audit !== false;
   var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
 
   var deadlines = REGIME_DEADLINES[legalBasis] || REGIME_DEADLINES["operator-defined"];
 
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({
-        action:   "ai.adverse_decision." + action,
-        outcome:  outcome,
-        metadata: metadata || {},
-      });
-    } catch (_e) { /* drop-silent */ }
-  }
-  function _emitMetric(verb, n, labels) {
-    try { observability().safeEvent("ai.adverse_decision." + verb, n || 1, labels || {}); }
-    catch (_e) { /* drop-silent */ }
-  }
+  var _emitAudit = audit().namespaced("ai.adverse_decision", opts.audit);
+  var _emitMetric = observability().namespaced("ai.adverse_decision");
 
   return async function adverseDecisionDecorated(subject) {
     if (!subject || typeof subject !== "object") {

package/lib/ai-capability.js

@@ -239,12 +239,7 @@ function create(opts) {
   }
   var auditOn = opts.audit !== false;
 
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} });
-    } catch (_e) { /* audit best-effort — drop-silent */ }
-  }
+  var _emitAudit = audit().namespaced(null, { audit: auditOn });
 
   function describe(modelId) {
     var d = registry.get(modelId);

package/lib/ai-dp.js

@@ -429,11 +429,7 @@ function budget(opts) {
   var spentDelta = 0;
   var rdp = RDP_ORDERS.map(function () { return 0; });   // rdp accounting
 
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try { audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} }); }
-    catch (_e) { /* drop-silent */ }
-  }
+  var _emitAudit = audit().namespaced(null, { audit: auditOn });
 
   function _currentEpsilon(rdpCurve) {
     if (accounting === "basic") return spentEpsilon;

package/lib/ai-input.js

@@ -23,6 +23,7 @@
 var C = require("./constants");
 var numericBounds = require("./numeric-bounds");
 var audit = require("./audit");
+var codepointClass = require("./codepoint-class");
 var { AiInputError } = require("./framework-error");
 
 var SAMPLE_TRUNC = 80;                                                                       // sample truncation length, not bytes
@@ -69,8 +70,7 @@ function _featuresOf(input) {
     var cp = input.charCodeAt(i);
     if ((cp >= 0x202a && cp <= 0x202e) || (cp >= 0x2066 && cp <= 0x2069)) bidi++;
     else if (cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0xfeff || cp === 0x2060) zw++;
-    else if (cp < 0x20 && cp !== 0x09 && cp !== 0x0a && cp !== 0x0d) ctrl++;
-    else if (cp === 0x7f) ctrl++;
+    else if (codepointClass.isForbiddenControlChar(cp, { allowLf: true, allowCr: true })) ctrl++;
   }
   return {
     length:    input.length,

package/lib/ai-pref.js

@@ -152,13 +152,8 @@ function parseHeader(value) {
     label:      "aiPref.parseHeader",
   });
   var out = { train: null, infer: null, snippet: null, price: null };
-  var pairs = value.split(",");
-  for (var i = 0; i < pairs.length; i += 1) {
-    var p = pairs[i].trim();
-    var eq = p.indexOf("=");
-    if (eq === -1) continue;
-    var k = p.slice(0, eq).trim().toLowerCase();
-    var val = p.slice(eq + 1).trim();
+  var kvps = structuredFields.parseKeyValuePieces(value.split(","));
+  structuredFields.forEachKeyValue(kvps, function (k, val) {
     if (k === "train"      && TRAIN_VALUES.indexOf(val) !== -1)   out.train = val;
     else if (k === "infer"   && INFER_VALUES.indexOf(val) !== -1) out.infer = val;
     else if (k === "snippet" && SNIPPET_VALUES.indexOf(val) !== -1) out.snippet = val;
@@ -169,7 +164,7 @@ function parseHeader(value) {
       var pt = parseInt(val, 10);
       if (isFinite(pt) && pt > 0) out.price = Object.assign({ perTokens: pt }, out.price || {});
     }
-  }
+  });
   return out;
 }
 

package/lib/ai-quota.js

@@ -318,12 +318,7 @@ function create(opts) {
     return null;
   }
 
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} });
-    } catch (_e) { /* audit best-effort — drop-silent */ }
-  }
+  var _emitAudit = audit().namespaced(null, { audit: auditOn });
 
   function _emitMetric(name, n) {
     try { observability().safeEvent(name, n || 1, {}); }
@@ -507,14 +502,8 @@ function _validateLimitMap(map, label) {
 }
 
 function _validateStore(store) {
-  if (!store || typeof store !== "object" ||
-      typeof store.reserve !== "function" ||
-      typeof store.add !== "function" ||
-      typeof store.get !== "function" ||
-      typeof store.reset !== "function") {
-    throw new AiQuotaError("ai-quota/bad-store",
-      "ai.quota.create: store must expose reserve / add / get / reset functions");
-  }
+  validateOpts.requireMethods(store, ["reserve", "add", "get", "reset"],
+    "ai.quota.create: store", AiQuotaError, "ai-quota/bad-store");
 }
 
 module.exports = {

package/lib/api-key.js

@@ -134,37 +134,46 @@ function _validateIdentifier(name, value) {
 }
 
 function _validateCreateOpts(opts) {
-  validateOpts.requireObject(opts, "apiKey.create", ApiKeyError);
-  _validateIdentifier("apiKey.create: namespace", opts.namespace);
-  if (opts.prefix !== undefined) _validateIdentifier("apiKey.create: prefix", opts.prefix);
-  validateOpts.optionalPositiveInt(opts.idBytes, "apiKey.create: idBytes", ApiKeyError);
-  validateOpts.optionalPositiveInt(opts.secretBytes, "apiKey.create: secretBytes", ApiKeyError);
-  validateOpts.optionalBoolean(opts.trackLastUsedAt, "apiKey.create: trackLastUsedAt", ApiKeyError);
-  validateOpts.optionalBoolean(opts.auditFailures, "apiKey.create: auditFailures", ApiKeyError);
-  validateOpts.optionalBoolean(opts.auditSuccess, "apiKey.create: auditSuccess", ApiKeyError);
-  validateOpts.optionalFiniteNonNegative(opts.purgeAfterMs, "apiKey.create: purgeAfterMs", ApiKeyError);
-  if (opts.hashAlgo !== undefined) {
-    if (typeof opts.hashAlgo !== "string" ||
-        (opts.hashAlgo !== "shake256" && opts.hashAlgo !== "argon2id")) {
-      throw _err("BAD_OPT", "apiKey.create: hashAlgo must be 'shake256' or 'argon2id', got " +
-        JSON.stringify(opts.hashAlgo));
-    }
-  }
-  validateOpts.auditShape(opts.audit, "apiKey.create", ApiKeyError);
-  validateOpts.optionalFunction(opts.clock, "apiKey.create: clock", ApiKeyError);
+  validateOpts.shape(opts, {
+    namespace:       function (v, l) { _validateIdentifier(l, v); },
+    prefix:          function (v, l) { if (v !== undefined) _validateIdentifier(l, v); },
+    idBytes:         "optional-positive-int",
+    secretBytes:     "optional-positive-int",
+    trackLastUsedAt: "optional-boolean",
+    auditFailures:   "optional-boolean",
+    auditSuccess:    "optional-boolean",
+    purgeAfterMs:    "optional-non-negative",
+    hashAlgo:        function (v) {
+      if (v !== undefined) {
+        if (typeof v !== "string" || (v !== "shake256" && v !== "argon2id")) {
+          throw _err("BAD_OPT", "apiKey.create: hashAlgo must be 'shake256' or 'argon2id', got " +
+            JSON.stringify(v));
+        }
+      }
+    },
+    audit:           function (v) { validateOpts.auditShape(v, "apiKey.create", ApiKeyError); },
+    clock:           "optional-function",
+  }, "apiKey.create", ApiKeyError);
 }
 
 function _validateIssueOpts(opts) {
-  validateOpts.requireObject(opts, "apiKey.issue", ApiKeyError);
-  validateOpts.requireNonEmptyString(opts.ownerId, "apiKey.issue: ownerId", ApiKeyError, "MISSING_OWNER");
-  validateOpts.optionalNonEmptyStringArray(opts.scopes, "apiKey.issue: scopes", ApiKeyError, "BAD_SCOPES");
-  validateOpts.optionalPlainObject(opts.metadata, "apiKey.issue: metadata",
-    ApiKeyError, "BAD_METADATA");
-  if (opts.expiresAt !== undefined && opts.expiresAt !== null) {
-    if (typeof opts.expiresAt !== "number" || !isFinite(opts.expiresAt) || opts.expiresAt < 0) {
-      throw _err("BAD_OPT", "apiKey.issue: expiresAt must be a non-negative finite number (unix ms) or null");
-    }
-  }
+  validateOpts.shape(opts, {
+    ownerId:   { rule: "required-string",       code: "MISSING_OWNER" },
+    scopes:    { rule: "optional-string-array", code: "BAD_SCOPES" },
+    metadata:  { rule: "optional-plain-object", code: "BAD_METADATA" },
+    expiresAt: function (v) {
+      if (v !== undefined && v !== null) {
+        if (typeof v !== "number" || !isFinite(v) || v < 0) {
+          throw _err("BAD_OPT", "apiKey.issue: expiresAt must be a non-negative finite number (unix ms) or null");
+        }
+      }
+    },
+  }, "apiKey.issue", ApiKeyError, undefined, {
+    // `req` / `context` are the audit-actor pass-through bag — forwarded
+    // verbatim to requestHelpers.resolveActorWithOverride (via _actor)
+    // to populate the issue audit's 5 W's, not validated locally.
+    allow: ["req", "context"],
+  });
 }
 
 // ---- Token format ----

package/lib/archive-adapters.js

@@ -547,10 +547,8 @@ function http(url, opts) {
  *   for await (var e of reader.entries()) entries.push(e);
  */
 function trustedStream(readable, opts) {
-  if (!readable || typeof readable.pipe !== "function" || typeof readable.on !== "function") {
-    throw new AdapterError("adapter/bad-arg",
-      "trustedStream: arg must be a Readable (or pipe/on-compatible stream)");
-  }
+  validateOpts.requireMethods(readable, ["pipe", "on"],
+    "trustedStream: arg (Readable / pipe-on-compatible stream)", AdapterError, "adapter/bad-arg");
   if (!(readable instanceof nodeStream.Readable) && !readable.readable) {
     // Accept stream-like duck-typed objects; many libraries return
     // Readable-flavored bytes via Symbol.asyncIterator only.

package/lib/archive-entry-policy.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * lib/archive-entry-policy.js — the entry-type extraction policy shared by the
+ * ZIP (archive-read) and TAR (archive-tar-read) readers.
+ *
+ * Special archive entry types — symlinks, hardlinks, device nodes, FIFOs, and
+ * sockets — are a malicious-archive vector (symlink traversal out of the
+ * extraction root, device-node creation, etc.), so every type is DENIED by
+ * default; an operator opts a type in explicitly per archive. Both readers
+ * normalized the same default the same way, so the policy + its overlay live
+ * here once rather than drifting between the two formats.
+ */
+
+var DEFAULT_ENTRY_TYPE_POLICY = Object.freeze({
+  symlinks:  false,
+  hardlinks: false,
+  devices:   false,
+  fifos:     false,
+  sockets:   false,
+});
+
+// normalize(p) — overlay an operator policy onto the all-denied default and
+// freeze it. A falsy `p` returns the shared default object (no allocation).
+function normalize(p) {
+  if (!p) return DEFAULT_ENTRY_TYPE_POLICY;
+  return Object.freeze(Object.assign({}, DEFAULT_ENTRY_TYPE_POLICY, p));
+}
+
+module.exports = {
+  DEFAULT_ENTRY_TYPE_POLICY: DEFAULT_ENTRY_TYPE_POLICY,
+  normalize:                 normalize,
+};