@blamejs/core 0.8.42 → 0.8.49

package/lib/guard-image.js

@@ -1,36 +1,62 @@
 "use strict";
 /**
- * guard-image — Image identifier-safety primitive (b.guardImage).
+ * @module b.guardImage
+ * @nav    Guards
+ * @title  Guard Image
  *
- * Validates image-format inputs without vendoring a full decoder.
- * The framework's stance: operators bring their own decoder (sharp,
- * jimp, libvips wrappers, etc.). guardImage closes the magic-byte
- * vs declared-Content-Type mismatch class, the polyglot file class,
- * and operator-supplied metadata bounds (oversized dimensions, frame
- * count, color depth). KIND="metadata" — consumes
- * `ctx.metadata` shape: `{ bytes?, declaredMime?, width?, height?,
- * frames?, colorDepth?, hasAlpha? }`.
+ * @intro
+ *   Image content-safety guard — closes the magic-byte / declared-MIME
+ *   mismatch class and the polyglot-file class without vendoring a
+ *   raster decoder. Operators bring their own decoder (sharp, jimp,
+ *   libvips bindings) and feed structural metadata to the guard.
+ *   `KIND="metadata"` — consumes `ctx.metadata` shape `{ bytes?,
+ *   declaredMime?, width?, height?, frames?, colorDepth?, hasAlpha? }`.
  *
- * Threat catalog:
- *   - Magic-byte vs declared-MIME mismatch — `Content-Type:
- *     image/png` with JPEG bytes (drive-by content-type confusion;
- *     downstream decoder picks wrong path).
- *   - Polyglot file — multiple format magic bytes detected in the
- *     same buffer (PHP-in-JPEG, JS-in-PNG class).
- *   - Oversized dimensions — operator passes width / height; the
- *     guard refuses against maxWidth / maxHeight.
- *   - Excessive frame count (animated GIF / WebP / APNG / AVIF
- *     image sequences) — operator passes frames; refused against
- *     maxFrames.
- *   - SVG content — delegates to b.guardSvg (this guard refuses
- *     SVG bytes directly so operators don't bypass the SVG guard
- *     by routing through guardImage).
- *   - Unknown / no magic-byte match.
+ *   Magic-byte dispatch: `inspectMagic(bytes)` walks a signature table
+ *   covering PNG (`89 50 4E 47 0D 0A 1A 0A`), JPEG (`FF D8 FF`),
+ *   GIF87a / GIF89a, WebP (RIFF + WEBP at offset 8), BMP, ICO, TIFF
+ *   (II / MM), AVIF / HEIC (`ftyp` boxes at offset 4), and SVG (`<?xml`
+ *   / `<svg`). Returns the list of distinct MIMEs that match. Multiple
+ *   matches signals a polyglot file (PHP-in-JPEG / JS-in-PNG class) —
+ *   refused under every profile.
  *
- *   var rv = b.guardImage.validate({ bytes, declaredMime: "image/png",
- *                                   width: 1024, height: 768 },
- *                                  { profile: "strict" });
- *   var g  = b.guardImage.gate({ profile: "strict" });
+ *   Dimension caps: oversized width / height refused against
+ *   `maxWidth` / `maxHeight` (strict 8 192 px, balanced 16 384 px,
+ *   permissive 65 536 px). Frame caps for animated GIF / WebP / APNG /
+ *   AVIF image sequences refused against `maxFrames` (strict 60,
+ *   balanced 200, permissive 1000). Operator-supplied — the guard
+ *   does not decode bytes itself; the operator's decoder reports the
+ *   metadata before passing it to the gate.
+ *
+ *   Polyglot rejection: when `_detectMagicMimes` returns more than one
+ *   distinct format, the buffer carries multiple magic-byte signatures
+ *   (e.g. JPEG marker followed by an embedded ZIP central directory) —
+ *   refused at every profile.
+ *
+ *   EXIF / XMP metadata strip: handled by the operator's decoder
+ *   (sharp's `withMetadata: false`, libvips `metadata-strip`). The
+ *   guard does not parse byte streams; it enforces the policy boundary
+ *   and refuses the upload when the decoder's reported metadata
+ *   violates a cap.
+ *
+ *   SVG routing: bytes that match the SVG magic are refused under every
+ *   profile — operators must route SVG explicitly to `b.guardSvg`
+ *   because the SVG threat catalog (XXE, billion-laughs, animation
+ *   href injection, foreignObject namespace shift) is distinct from
+ *   raster threats.
+ *
+ *   Operator-feeds-metadata pattern: the gate trusts the metadata
+ *   object the operator supplies. The operator's decoder is the
+ *   ground truth for `width` / `height` / `frames`; the guard refuses
+ *   based on those values. This keeps the framework's no-deps stance
+ *   intact while still closing the policy gaps.
+ *
+ *   Profiles `strict` / `balanced` / `permissive` and compliance
+ *   postures `hipaa` / `pci-dss` / `gdpr` / `soc2` overlay on the
+ *   profile baseline.
+ *
+ * @card
+ *   Image content-safety guard — closes the magic-byte / declared-MIME mismatch class and the polyglot-file class without vendoring a raster decoder.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -274,6 +300,57 @@ function _detectIssues(metadata, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardImage.validate
+ * @signature  b.guardImage.validate(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardImage.sanitize, b.guardImage.gate, b.guardImage.inspectMagic
+ *
+ * Inspect an image-metadata bag `{ bytes?, declaredMime?, width?,
+ * height?, frames? }` and return `{ ok, issues }`. Issues carry
+ * `{ kind, severity, ruleId, snippet }`. Detected: magic-byte / MIME
+ * mismatch (`mime-mismatch`), polyglot file (`polyglot`, refused
+ * under every profile), SVG bytes routed through guardImage
+ * (`svg-routing`, must go to `b.guardSvg`), unknown magic
+ * (`unknown-magic`), oversized width / height (`width-cap` /
+ * `height-cap`), excessive frame count (`frames-cap`), oversized
+ * byte length (`image-cap`). Pure inspection — never mutates input
+ * or throws on hostile metadata.
+ *
+ * @opts
+ *   profile:           "strict"|"balanced"|"permissive",
+ *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   mismatchPolicy:     "reject"|"audit"|"allow",
+ *   polyglotPolicy:     "reject"|"audit"|"allow",
+ *   unknownMagicPolicy: "reject"|"audit"|"allow",
+ *   svgRoutingPolicy:   "reject"|"audit"|"allow",
+ *   dimensionsPolicy:   "reject"|"audit"|"allow",
+ *   framesPolicy:       "reject"|"audit"|"allow",
+ *   maxWidth:           number,    // strict 8192, balanced 16384, permissive 65536
+ *   maxHeight:          number,    // strict 8192, balanced 16384, permissive 65536
+ *   maxFrames:          number,    // strict 60, balanced 200, permissive 1000
+ *   maxBytes:           number,    // strict 32 MiB, balanced 64 MiB, permissive 256 MiB
+ *
+ * @example
+ *   // Mismatch — declared image/png but bytes are JPEG.
+ *   var rv = b.guardImage.validate({
+ *     bytes: Buffer.from([0xFF, 0xD8, 0xFF]),
+ *     declaredMime: "image/png",
+ *   }, { profile: "strict" });
+ *   rv.ok;                                               // → false
+ *   rv.issues[0].kind;                                   // → "mime-mismatch"
+ *
+ *   // Oversized width refused under strict (8192 px cap).
+ *   var big = b.guardImage.validate({
+ *     bytes: Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]),
+ *     declaredMime: "image/png",
+ *     width: 16384, height: 16384,
+ *   }, { profile: "strict" });
+ *   big.issues.some(function (i) { return i.kind === "width-cap"; });
+ *   //                                                   → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -282,6 +359,35 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive b.guardImage.sanitize
+ * @signature b.guardImage.sanitize(input, opts)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardImage.validate, b.guardImage.gate
+ *
+ * Best-effort metadata pass-through. Image-byte sanitization
+ * (transcoding, EXIF strip, dimension downscale) is the operator
+ * decoder's responsibility — the guard cannot rewrite raster bytes
+ * without a vendored decoder. `sanitize` validates the metadata
+ * against the active profile and re-throws `GuardImageError` when
+ * any issue is `critical` or `high`. Returns the input unchanged
+ * when every issue is `warn` or below.
+ *
+ * @opts
+ *   profile:           "strict"|"balanced"|"permissive",
+ *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *
+ * @example
+ *   try {
+ *     b.guardImage.sanitize({
+ *       bytes: Buffer.from([0xFF, 0xD8, 0xFF]),
+ *       declaredMime: "image/png",
+ *     }, { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                            // → "image.mime-mismatch"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (!input || typeof input !== "object") {
@@ -297,6 +403,41 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardImage.gate
+ * @signature  b.guardImage.gate(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardImage.validate, b.guardImage.sanitize, b.fileUpload, b.staticServe
+ *
+ * Build a `b.gateContract` gate suitable for `b.fileUpload({ contentSafety:
+ * { "image/png": gate, "image/jpeg": gate } })` or `b.staticServe`.
+ * Operators pass `ctx.metadata` (the decoder's reported shape) plus
+ * the original `bytes`. Action chain: `serve` (no issues) →
+ * `audit-only` (warn-only) → `refuse` (any critical / high). No
+ * `sanitize` action — image bytes can't be transcoded without a
+ * vendored decoder.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,
+ *   ...:        any validate opt
+ *
+ * @example
+ *   var imgGate = b.guardImage.gate({ profile: "strict" });
+ *
+ *   var verdict = await imgGate.check({
+ *     metadata: {
+ *       bytes: Buffer.from([0xFF, 0xD8, 0xFF]),
+ *       declaredMime: "image/png",
+ *       width: 1024, height: 768, frames: 1,
+ *     },
+ *   });
+ *   verdict.action;                                      // → "refuse"
+ *   verdict.issues[0].kind;                              // → "mime-mismatch"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -320,18 +461,90 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive b.guardImage.buildProfile
+ * @signature b.guardImage.buildProfile(opts)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardImage.compliancePosture, b.guardImage.gate
+ *
+ * Resolve a named profile against the guard's PROFILES catalog and
+ * return the merged options bag. Throws
+ * `GuardImageError("image.bad-profile")` on unknown name.
+ *
+ * @opts
+ *   profile: "strict"|"balanced"|"permissive",
+ *
+ * @example
+ *   var resolved = b.guardImage.buildProfile({ profile: "strict" });
+ *   resolved.maxWidth;                                   // → 8192
+ *   resolved.polyglotPolicy;                             // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardImage.compliancePosture
+ * @signature  b.guardImage.compliancePosture(name)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardImage.gate, b.guardImage.buildProfile
+ *
+ * Return the option overlay for a named compliance posture
+ * (`"hipaa"` / `"pci-dss"` / `"gdpr"` / `"soc2"`). Throws
+ * `GuardImageError("image.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardImage.compliancePosture("hipaa");
+ *   posture.mismatchPolicy;                              // → "reject"
+ *   posture.forensicSnippetBytes;                        // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "image");
 }
 
 var _imgRulePacks = gateContract.makeRulePackLoader(GuardImageError, "image");
+/**
+ * @primitive b.guardImage.loadRulePack
+ * @signature b.guardImage.loadRulePack(pack)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardImage.gate
+ *
+ * Register an operator-supplied rule pack (extra MIME / dimension /
+ * polyglot overrides) into the guard's private store. Throws
+ * `GuardImageError("image.bad-opt")` when `pack` is missing or
+ * `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardImage.loadRulePack({
+ *     id: "kb-2026-image",
+ *     extraMaxFrames: 30,
+ *   });
+ *   pack.id;                                             // → "kb-2026-image"
+ */
 var loadRulePack = _imgRulePacks.load;
 
-// Operator helper: surface the magic-byte detection result so callers
-// can run their own dispatch without re-implementing the table.
+/**
+ * @primitive b.guardImage.inspectMagic
+ * @signature b.guardImage.inspectMagic(bytes)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardImage.validate, b.guardImage.gate
+ *
+ * Read the leading bytes of `bytes` and return an array of distinct
+ * MIMEs that match a known image-format magic-byte signature. Empty
+ * array on no match; multiple entries signals a polyglot file. Pure
+ * inspection — never mutates input or throws.
+ *
+ * @example
+ *   var pngBytes = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+ *   b.guardImage.inspectMagic(pngBytes);                 // → ["image/png"]
+ *
+ *   b.guardImage.inspectMagic(Buffer.from([0xFF, 0xD8, 0xFF]));
+ *   //                                                   → ["image/jpeg"]
+ */
 function inspectMagic(bytes) {
   return _detectMagicMimes(bytes);
 }