@blamejs/core 0.8.42 → 0.8.49

package/lib/safe-json.js

@@ -1,63 +1,37 @@
 "use strict";
 /**
- * Security-focused, fault-tolerant JSON utilities + lightweight schema
- * validation with extensible format registry.
- *
- * Native JSON.parse leaves several footguns to the caller:
- *   - No size limit — large inputs DoS the parser thread
- *   - No depth limit — deeply nested input can stack-overflow downstream code
- *   - __proto__ / constructor / prototype keys land in the result and can be
- *     turned into prototype pollution by any later object-merge / clone
- *   - Errors include only a character position, no surrounding context
- *
- * This module fixes all of the above with conservative defaults and adds a
- * lightweight schema validator (a strict subset of JSON Schema) so apps
- * can declare what they expect at the trust boundary.
- *
- * Public API:
- *
- *   json.parse(input, opts?)               → value | throws SafeJsonError
- *                                            (with opts.collectErrors: { ok, value, errors[] })
- *   json.parseOrDefault(input, fallback, opts?) → value (no throw)
- *   json.stringify(value, opts?)           → string | throws SafeJsonError
- *   json.canonical(value, opts?)           → string (sorted keys)
- *   json.validate(value, schema, opts?)    → value | throws
- *                                            (with opts.collectErrors: { ok, value, errors[] })
- *   json.registerFormat(name, validator)   → register a custom format
- *   json.formats                           → built-in format names
- *   json.SafeJsonError                     → error class
- *
- * Validation modes (opts.collectErrors):
- *   - default (throw):    fails loudly on first error — right for trust boundaries
- *                         (HTTP body parse, sealed payload deserialize, config load).
- *                         The throw IS the security signal; HTTP middleware catches
- *                         it and emits a 400 with .path / .code.
- *   - collectErrors:true: returns { ok, value, errors[] } — right for form-style
- *                         bulk validation where the user needs to see every field
- *                         that failed in one round-trip.
- *
- * Defaults:
- *   maxBytes:    1 MiB
- *   maxDepth:    100
- *   allowProto:  false
- *   onCircular:  "throw"
- *
- * Schema dialect (JSON Schema subset):
- *   { type: 'string'|'number'|'integer'|'boolean'|'null'|'array'|'object',
- *     enum: [...],
- *     // string
- *     minLength, maxLength, pattern, format,
- *     // number
- *     minimum, maximum, exclusiveMinimum, exclusiveMaximum,
- *     // array
- *     minItems, maxItems, items: <schema>,
- *     // object
- *     required: [...], properties: { key: <schema>, ... }, additionalProperties: bool
- *   }
+ * @module b.safeJson
+ * @featured true
+ * @nav    Validation
+ * @title  Safe Json
+ *
+ * @intro
+ *   Hardened JSON parse + stringify + schema validation. Native
+ *   `JSON.parse` leaves four footguns to the caller — no size cap (DoS
+ *   the parser thread), no depth cap (stack-overflow downstream), no
+ *   guard on `__proto__` / `constructor` / `prototype` keys (prototype
+ *   pollution after any later merge/clone), and errors that report
+ *   only a character offset with no surrounding context. `b.safeJson`
+ *   closes all four with conservative defaults.
+ *
+ *   Defaults: 1 MiB body cap, depth 100, 10 000 keys per object
+ *   (CVE-2026-21717 V8 HashDoS guard), poisoned keys stripped.
+ *   Stringify refuses circular references unless the caller asks for
+ *   the `[Circular]` placeholder. `canonical` produces RFC 8785 JCS
+ *   key-sorted output for signature inputs.
+ *
+ *   The validator is a strict subset of JSON Schema (`type` / `enum`
+ *   / `minLength` etc. / `required` / `properties` / `additionalProperties`),
+ *   pluggable formats via `b.safeJson.registerFormat`, two modes:
+ *   throw on first error (trust-boundary parse) or collect every
+ *   error (form-style bulk validation).
  *
- * Schemas are app-developer-supplied (not user-controlled); regex patterns
- * are trusted not to be ReDoS-prone. Format validators in the built-in
- * registry are anchored / bounded.
+ *   Validation policy: opts and inputs are validated at the call site
+ *   and throw `SafeJsonError`. The throw IS the security signal; HTTP
+ *   middleware catches it and emits 400 with `.code` / `.path`.
+ *
+ * @card
+ *   Hardened JSON parse + stringify + schema validation.
  */
 
 // ---- Error class ----
@@ -68,6 +42,30 @@ var safeUrl = require("./safe-url");
 var time = require("./time");
 var { FrameworkError } = require("./framework-error");
 
+/**
+ * @primitive b.safeJson.SafeJsonError
+ * @signature b.safeJson.SafeJsonError
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.validate
+ *
+ * Error class thrown by every `b.safeJson` primitive on bad input,
+ * cap exceedance, or schema-validation failure. Extends
+ * `FrameworkError`. Carries a stable `.code` (e.g. `json/too-large`,
+ * `json/syntax`, `json/validation`, `json/circular`) plus an
+ * optional JSON-pointer-shaped `.path` (e.g. `$.user.email`) for
+ * schema-validation errors. HTTP middleware translates these into
+ * 400 responses without leaking parser internals.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   try {
+ *     b.safeJson.parse("{not json");
+ *   } catch (e) {
+ *     e instanceof b.safeJson.SafeJsonError;   // → true
+ *     e.code;                                  // → "json/syntax"
+ *   }
+ */
 class SafeJsonError extends FrameworkError {
   constructor(message, code, path) {
     super(message);
@@ -86,11 +84,71 @@ var ABSOLUTE_MAX_DEPTH = 1_000;
 var IPV6_HEXTET_COUNT = 0x8;
 var DEFAULT_MAX_BYTES = C.BYTES.mib(1);
 var DEFAULT_MAX_DEPTH = 100;
+// CVE-2026-21717 — V8 HashDoS via integer-like keys. V8's object-shape
+// transition cache degrades to O(n^2) when an object accumulates many
+// distinct integer-string-shaped keys; a JSON body with thousands of
+// `"0"`, `"1"`, ... keys spends O(n^2) CPU on the parse path itself.
+// Cap object-literal-key count per node so a hostile payload cannot
+// reach the degenerate shape.
+var DEFAULT_MAX_KEYS = 10_000;
+var ABSOLUTE_MAX_KEYS = 1_000_000;
 
 var POISONED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 // ---- parse ----
 
+/**
+ * @primitive b.safeJson.parse
+ * @signature b.safeJson.parse(input, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parseOrDefault, b.safeJson.stringify, b.safeJson.validate
+ *
+ * Hardened JSON parse. Accepts string / Buffer / Uint8Array,
+ * normalizes to UTF-8 text, enforces the byte cap BEFORE the parser
+ * sees the input, then bounds nesting depth and per-object key count
+ * so a hostile body can't DoS the parse thread or trip V8's HashDoS
+ * shape-cache degeneracy (CVE-2026-21717). Strips `__proto__` /
+ * `constructor` / `prototype` keys via the `JSON.parse` reviver so a
+ * later spread / merge / clone can't pivot into prototype pollution.
+ *
+ * Throws `SafeJsonError` with a documented `.code`:
+ * `json/too-large` / `json/syntax` / `json/too-deep` /
+ * `json/too-many-keys` / `json/wrong-input-type` /
+ * `json/type-mismatch` / `json/missing-key` / `json/validation`.
+ *
+ * @opts
+ *   maxBytes:      number,  // default 1 MiB; capped at 64 MiB
+ *   maxDepth:      number,  // default 100; capped at 1000
+ *   maxKeys:       number,  // default 10 000; capped at 1 000 000
+ *   allowProto:    boolean, // default false; keep __proto__/constructor/prototype keys
+ *   schema:        object,  // optional JSON-Schema subset; runs b.safeJson.validate
+ *   collectErrors: boolean, // pair with `schema`: return { ok, value, errors[] } instead of throwing
+ *   expectType:    string,  // legacy: "string"|"number"|"boolean"|"null"|"array"|"object"
+ *   requiredKeys:  string[],// legacy: required top-level keys (prefer `schema.required`)
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var obj = b.safeJson.parse('{"name":"alice","age":30}');
+ *   obj.name;
+ *   // → "alice"
+ *
+ *   // Prototype-pollution payload: poisoned keys stripped silently.
+ *   var clean = b.safeJson.parse('{"__proto__":{"isAdmin":true},"id":1}');
+ *   Object.prototype.hasOwnProperty.call(clean, "__proto__");
+ *   // → false
+ *
+ *   // Size cap rejects oversized input before parsing.
+ *   var big = '"' + "x".repeat(2000) + '"';
+ *   try { b.safeJson.parse(big, { maxBytes: 1024 }); }
+ *   catch (e) { e.code; }
+ *   // → "json/too-large"
+ *
+ *   // Depth cap bounds nesting.
+ *   try { b.safeJson.parse('[[[[[[1]]]]]]', { maxDepth: 3 }); }
+ *   catch (e) { e.code; }
+ *   // → "json/too-deep"
+ */
 function parse(input, opts) {
   opts = opts || {};
 
@@ -104,6 +162,7 @@ function parse(input, opts) {
   });
 
   var maxDepth   = _capInt(opts.maxDepth, DEFAULT_MAX_DEPTH, ABSOLUTE_MAX_DEPTH);
+  var maxKeys    = _capInt(opts.maxKeys, DEFAULT_MAX_KEYS, ABSOLUTE_MAX_KEYS);
   var allowProto = !!opts.allowProto;
 
   var parsed;
@@ -113,7 +172,7 @@ function parse(input, opts) {
     throw new SafeJsonError("invalid JSON: " + e.message, "json/syntax");
   }
 
-  _walkAndCheck(parsed, 0, maxDepth, allowProto);
+  _walkAndCheck(parsed, 0, maxDepth, allowProto, maxKeys);
 
   // Optional schema validation (preferred over expectType / requiredKeys)
   if (opts.schema) {
@@ -146,6 +205,37 @@ function parse(input, opts) {
   return parsed;
 }
 
+/**
+ * @primitive b.safeJson.parseOrDefault
+ * @signature b.safeJson.parseOrDefault(input, fallback, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse
+ *
+ * Best-effort parse: returns `fallback` on any failure (size cap,
+ * syntax error, depth/key cap, schema mismatch). Useful for cache
+ * thaw / config files / optional metadata where a malformed payload
+ * shouldn't crash the caller. Same caps and prototype-pollution
+ * defense as `parse`.
+ *
+ * @opts
+ *   maxBytes:      number,  // default 1 MiB; capped at 64 MiB
+ *   maxDepth:      number,  // default 100; capped at 1000
+ *   maxKeys:       number,  // default 10 000; capped at 1 000 000
+ *   allowProto:    boolean, // default false; keep __proto__/constructor/prototype keys
+ *   schema:        object,  // optional JSON-Schema subset (see b.safeJson.validate)
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.parseOrDefault('{"x":1}', {});
+ *   // → { x: 1 }
+ *
+ *   b.safeJson.parseOrDefault("{not json", { x: 0 });
+ *   // → { x: 0 }
+ *
+ *   b.safeJson.parseOrDefault(null, []);
+ *   // → []
+ */
 function parseOrDefault(input, fallback, opts) {
   try { return parse(input, opts); }
   catch (_e) { return fallback; }
@@ -156,13 +246,13 @@ function _stripProtoKeys(key, value) {
   return value;
 }
 
-function _walkAndCheck(value, depth, maxDepth, allowProto) {
+function _walkAndCheck(value, depth, maxDepth, allowProto, maxKeys) {
   if (depth > maxDepth) {
     throw new SafeJsonError("nesting exceeds maxDepth (" + maxDepth + ")", "json/too-deep");
   }
   if (value === null || typeof value !== "object") return;
   if (Array.isArray(value)) {
-    for (var i = 0; i < value.length; i++) _walkAndCheck(value[i], depth + 1, maxDepth, allowProto);
+    for (var i = 0; i < value.length; i++) _walkAndCheck(value[i], depth + 1, maxDepth, allowProto, maxKeys);
     return;
   }
   if (!allowProto) {
@@ -170,9 +260,17 @@ function _walkAndCheck(value, depth, maxDepth, allowProto) {
       if (Object.prototype.hasOwnProperty.call(value, k)) delete value[k];
     });
   }
+  // CVE-2026-21717 — refuse object literals beyond maxKeys before V8's
+  // hidden-class transition cache degrades to O(n^2) on integer-shaped
+  // keys.
+  var keyCount = 0;
   for (var k in value) {
     if (Object.prototype.hasOwnProperty.call(value, k)) {
-      _walkAndCheck(value[k], depth + 1, maxDepth, allowProto);
+      keyCount += 1;
+      if (keyCount > maxKeys) {
+        throw new SafeJsonError("object exceeds maxKeys (" + maxKeys + ")", "json/too-many-keys");
+      }
+      _walkAndCheck(value[k], depth + 1, maxDepth, allowProto, maxKeys);
     }
   }
 }
@@ -185,6 +283,44 @@ function _typeName(v) {
 
 // ---- stringify ----
 
+/**
+ * @primitive b.safeJson.stringify
+ * @signature b.safeJson.stringify(value, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.canonical
+ *
+ * JSON-encode a value with two safeguards `JSON.stringify` doesn't
+ * provide: a documented circular-reference policy (throw, or
+ * substitute every cycle with a placeholder string) and prototype-
+ * key suppression so an object built from a tainted parse can't leak
+ * `__proto__` / `constructor` / `prototype` keys back out.
+ *
+ * Throws `SafeJsonError` with `.code = "json/circular"` when
+ * `onCircular: "throw"` (default) hits a cycle.
+ *
+ * @opts
+ *   onCircular:          "throw" | "replace", // default "throw"
+ *   circularReplacement: any,                 // default "[Circular]" (used when onCircular === "replace")
+ *   allowProto:          boolean,             // default false; keep __proto__/constructor/prototype keys
+ *   indent:              number | string,     // forwarded to JSON.stringify
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.stringify({ a: 1, b: 2 });
+ *   // → '{"a":1,"b":2}'
+ *
+ *   // Cycles throw by default.
+ *   var cyclic = { name: "root" };
+ *   cyclic.self = cyclic;
+ *   try { b.safeJson.stringify(cyclic); }
+ *   catch (e) { e.code; }
+ *   // → "json/circular"
+ *
+ *   // Opt into placeholder-substitution.
+ *   var out = b.safeJson.stringify(cyclic, { onCircular: "replace" });
+ *   // → '{"name":"root","self":"[Circular]"}'
+ */
 function stringify(value, opts) {
   opts = opts || {};
   var onCircular = opts.onCircular || "throw";
@@ -250,7 +386,39 @@ function _cleanCycles(value, replacement, allowProto) {
 
 // ---- canonical ----
 
-function canonical(value, _opts) {
+/**
+ * @primitive b.safeJson.canonical
+ * @signature b.safeJson.canonical(value)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.stringify, b.crypto.sign
+ *
+ * RFC 8785 (JSON Canonicalization Scheme) serialization — produces
+ * deterministic output suitable as a hash / signature input. Object
+ * keys are lexicographically sorted at every depth, no whitespace is
+ * emitted, poisoned keys are stripped, and non-finite numbers
+ * (`NaN` / `Infinity`) throw `SafeJsonError` with
+ * `.code = "json/non-finite"` instead of silently round-tripping
+ * through `null`. Two semantically-equal values produce byte-
+ * identical output, which is what signature inputs require.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.canonical({ b: 2, a: 1 });
+ *   // → '{"a":1,"b":2}'
+ *
+ *   // Two equivalent objects produce identical bytes.
+ *   var x = b.safeJson.canonical({ name: "alice", age: 30 });
+ *   var y = b.safeJson.canonical({ age: 30, name: "alice" });
+ *   x === y;
+ *   // → true
+ *
+ *   // Non-finite numbers refuse to canonicalize.
+ *   try { b.safeJson.canonical({ ratio: Infinity }); }
+ *   catch (e) { e.code; }
+ *   // → "json/non-finite"
+ */
+function canonical(value) {
   if (typeof value === "undefined") return "null";
 
   function ser(v) {
@@ -277,6 +445,32 @@ function canonical(value, _opts) {
 // ---- format registry ----
 
 // Anchored and bounded — nothing here is ReDoS-prone.
+/**
+ * @primitive b.safeJson.formats
+ * @signature b.safeJson.formats
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.registerFormat, b.safeJson.validate
+ *
+ * The built-in format-validator registry consulted by `validate`
+ * when a schema declares `{ format: "<name>" }` on a string field.
+ * Every entry is anchored, length-bounded, and non-backtracking —
+ * safe against ReDoS. Built-ins: `email` / `url` / `uuid` / `ulid`
+ * / `iso8601-date` / `iso8601-datetime` / `ipv4` / `ipv6` / `ip`
+ * / `hex` / `slug`. Add operator-specific formats with
+ * `b.safeJson.registerFormat`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.formats.uuid("f47ac10b-58cc-4372-a567-0e02b2c3d479");
+ *   // → true
+ *
+ *   b.safeJson.formats.email("alice@example.com");
+ *   // → true
+ *
+ *   b.safeJson.formats.ipv4("256.0.0.1");
+ *   // → false
+ */
 var formats = {
   // Structural-only email check (no RFC 5322 attempt). Keeps complexity O(n).
   // Length cap prevents pathological backtracking against long inputs.
@@ -380,6 +574,32 @@ var formats = {
   slug: function (v) { return typeof v === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v); },
 };
 
+/**
+ * @primitive b.safeJson.registerFormat
+ * @signature b.safeJson.registerFormat(name, validator)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.formats, b.safeJson.validate
+ *
+ * Register an operator-supplied format validator. `name` must be
+ * lowercase-kebab `[a-z][a-z0-9-]*`; `validator` is `(value) => boolean`.
+ * Once registered, schemas can declare `{ type: "string", format:
+ * "<name>" }` and the validator runs at every matching node.
+ * Throws `SafeJsonError` (`json/bad-format-name` /
+ * `json/bad-format-validator`) on invalid arguments.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.registerFormat("aws-region", function (v) {
+ *     return typeof v === "string" && /^[a-z]{2}-[a-z]+-\d$/.test(v);
+ *   });
+ *
+ *   b.safeJson.formats["aws-region"]("us-east-1");
+ *   // → true
+ *
+ *   b.safeJson.formats["aws-region"]("invalid");
+ *   // → false
+ */
 function registerFormat(name, validator) {
   if (typeof name !== "string" || !/^[a-z][a-z0-9-]*$/.test(name)) {
     throw new SafeJsonError("format name must match [a-z][a-z0-9-]*: " + name, "json/bad-format-name");
@@ -392,6 +612,61 @@ function registerFormat(name, validator) {
 
 // ---- validate ----
 
+/**
+ * @primitive b.safeJson.validate
+ * @signature b.safeJson.validate(value, schema, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.registerFormat
+ *
+ * Strict-subset JSON Schema validator. Supported keywords: `type`
+ * (`string` / `number` / `integer` / `boolean` / `null` / `array` /
+ * `object`), `enum`, `minLength` / `maxLength` / `pattern` /
+ * `format` (string), `minimum` / `maximum` / `exclusiveMinimum` /
+ * `exclusiveMaximum` (number), `minItems` / `maxItems` / `items`
+ * (array), `required` / `properties` / `additionalProperties`
+ * (object).
+ *
+ * Two modes — throw on the first failure (default; ideal for trust-
+ * boundary parses) or collect every error with
+ * `{ collectErrors: true }` (returns `{ ok, value, errors[] }` for
+ * form-style bulk validation). Errors carry a JSON-pointer-shaped
+ * `.path` (e.g. `$.user.email`).
+ *
+ * @opts
+ *   collectErrors: boolean,  // default false; collect every error instead of throwing on first
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var schema = {
+ *     type: "object",
+ *     required: ["email", "age"],
+ *     properties: {
+ *       email: { type: "string", format: "email", maxLength: 254 },
+ *       age:   { type: "integer", minimum: 0, maximum: 150 },
+ *     },
+ *     additionalProperties: false,
+ *   };
+ *
+ *   b.safeJson.validate({ email: "a@b.com", age: 30 }, schema);
+ *   // → { email: "a@b.com", age: 30 }
+ *
+ *   // Throw mode: first failure throws SafeJsonError.
+ *   try { b.safeJson.validate({ email: "nope", age: -1 }, schema); }
+ *   catch (e) { e.code; }
+ *   // → "json/validation"
+ *
+ *   // Collect mode: every failure surfaced.
+ *   var report = b.safeJson.validate(
+ *     { email: "nope", age: -1 },
+ *     schema,
+ *     { collectErrors: true }
+ *   );
+ *   report.ok;
+ *   // → false
+ *   report.errors.length >= 2;
+ *   // → true
+ */
 function validate(value, schema, opts) {
   opts = opts || {};
   if (!schema || typeof schema !== "object") {
@@ -524,6 +799,134 @@ function _capInt(value, defaultValue, ceiling) {
   return Math.min(Math.floor(value), ceiling);
 }
 
+/**
+ * @primitive b.safeJson.DEFAULT_MAX_BYTES
+ * @signature b.safeJson.DEFAULT_MAX_BYTES
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.ABSOLUTE_MAX_BYTES
+ *
+ * Default body cap applied by `parse` when the caller doesn't pass
+ * `opts.maxBytes` — 1 MiB. Keeps a hostile request from spending
+ * arbitrary CPU on the parse thread before the cap kicks in.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.DEFAULT_MAX_BYTES;
+ *   // → 1048576
+ */
+
+/**
+ * @primitive b.safeJson.DEFAULT_MAX_DEPTH
+ * @signature b.safeJson.DEFAULT_MAX_DEPTH
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.ABSOLUTE_MAX_DEPTH
+ *
+ * Default nesting-depth cap applied by `parse` when the caller
+ * doesn't pass `opts.maxDepth` — 100 levels. Bounds stack-overflow
+ * risk for downstream walkers (clone / merge / serializers).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.DEFAULT_MAX_DEPTH;
+ *   // → 100
+ */
+
+/**
+ * @primitive b.safeJson.DEFAULT_MAX_KEYS
+ * @signature b.safeJson.DEFAULT_MAX_KEYS
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.ABSOLUTE_MAX_KEYS
+ *
+ * Default per-object key cap applied by `parse` when the caller
+ * doesn't pass `opts.maxKeys` — 10 000 keys. Defends against
+ * CVE-2026-21717 V8 HashDoS (integer-shaped keys degrading the
+ * shape-transition cache to O(n^2)).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.DEFAULT_MAX_KEYS;
+ *   // → 10000
+ */
+
+/**
+ * @primitive b.safeJson.ABSOLUTE_MAX_BYTES
+ * @signature b.safeJson.ABSOLUTE_MAX_BYTES
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.DEFAULT_MAX_BYTES
+ *
+ * Hard ceiling for `opts.maxBytes` — 64 MiB. Operator-supplied caps
+ * above this clamp down silently so a typo can't disable the
+ * defense entirely.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.ABSOLUTE_MAX_BYTES;
+ *   // → 67108864
+ */
+
+/**
+ * @primitive b.safeJson.ABSOLUTE_MAX_DEPTH
+ * @signature b.safeJson.ABSOLUTE_MAX_DEPTH
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.DEFAULT_MAX_DEPTH
+ *
+ * Hard ceiling for `opts.maxDepth` — 1000 levels. Caller requests
+ * above this clamp down silently.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.ABSOLUTE_MAX_DEPTH;
+ *   // → 1000
+ */
+
+/**
+ * @primitive b.safeJson.ABSOLUTE_MAX_KEYS
+ * @signature b.safeJson.ABSOLUTE_MAX_KEYS
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.DEFAULT_MAX_KEYS
+ *
+ * Hard ceiling for `opts.maxKeys` — 1 000 000 keys per object.
+ * Clamps caller-supplied caps so the HashDoS guard cannot be
+ * accidentally disabled by a too-large value.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.ABSOLUTE_MAX_KEYS;
+ *   // → 1000000
+ */
+
+/**
+ * @primitive b.safeJson.POISONED_KEYS
+ * @signature b.safeJson.POISONED_KEYS
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeJson.parse, b.safeJson.stringify
+ *
+ * The list of object keys treated as prototype-pollution vectors —
+ * `__proto__`, `constructor`, `prototype`. `parse` strips them on
+ * the way in (unless `opts.allowProto: true`); `stringify` and
+ * `canonical` strip them on the way out. Exposed as an array so
+ * operator code that does its own object hygiene can reuse the
+ * same canonical list.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.POISONED_KEYS;
+ *   // → ["__proto__", "constructor", "prototype"]
+ *
+ *   // Reuse for operator-side sanitization.
+ *   var clean = {};
+ *   Object.keys(input).forEach(function (k) {
+ *     if (b.safeJson.POISONED_KEYS.indexOf(k) === -1) clean[k] = input[k];
+ *   });
+ */
+
 module.exports = {
   parse:          parse,
   parseOrDefault: parseOrDefault,
@@ -535,7 +938,9 @@ module.exports = {
   SafeJsonError:  SafeJsonError,
   DEFAULT_MAX_BYTES:  DEFAULT_MAX_BYTES,
   DEFAULT_MAX_DEPTH:  DEFAULT_MAX_DEPTH,
+  DEFAULT_MAX_KEYS:   DEFAULT_MAX_KEYS,
   ABSOLUTE_MAX_BYTES: ABSOLUTE_MAX_BYTES,
   ABSOLUTE_MAX_DEPTH: ABSOLUTE_MAX_DEPTH,
+  ABSOLUTE_MAX_KEYS:  ABSOLUTE_MAX_KEYS,
   POISONED_KEYS:      Array.from(POISONED_KEYS),
 };