@blamejs/blamejs-shop 0.4.30 → 0.4.32

package/lib/vendor/blamejs/lib/safe-icap.js

@@ -77,6 +77,7 @@
 
 var C                  = require("./constants");
 var { defineClass }    = require("./framework-error");
+var gateContract       = require("./gate-contract");
 
 var SafeIcapError = defineClass("SafeIcapError", { alwaysPermanent: true });
 
@@ -131,11 +132,15 @@ var PROFILES = Object.freeze({
   },
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
+
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: SafeIcapError,
+  codePrefix: "safe-icap",
+  byObject:   true,
 });
 
 /**
@@ -257,22 +262,6 @@ function parse(buf, opts) {
   };
 }
 
-/**
- * @primitive b.safeIcap.compliancePosture
- * @signature b.safeIcap.compliancePosture(posture)
- * @since     0.9.81
- * @status    stable
- *
- * Return the effective profile name for a compliance posture, or
- * `null` for unknown posture names.
- *
- * @example
- *   b.safeIcap.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
-
 // ---- internals ----
 
 function _findHeaderEnd(buf, maxHeaderBytes) {
@@ -479,25 +468,20 @@ function _detectThreat(statusCode, headers) {
   return { found: found, name: name };
 }
 
-function _resolveProfile(opts) {
-  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
-    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
-  }
-  var p = opts.profile || DEFAULT_PROFILE;
-  if (!PROFILES[p]) {
-    throw new SafeIcapError("safe-icap/bad-profile",
-      "safeIcap: unknown profile '" + p + "' (valid: strict / balanced / permissive)");
-  }
-  return PROFILES[p];
-}
-
-module.exports = {
-  parse:                parse,
-  compliancePosture:    compliancePosture,
-  PROFILES:             PROFILES,
-  COMPLIANCE_POSTURES:  COMPLIANCE_POSTURES,
-  ALLOWED_STATUS:       ALLOWED_STATUS,
-  SafeIcapError:        SafeIcapError,
-  NAME:                 "icap",
-  KIND:                 "icap-response",
-};
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
+module.exports = gateContract.defineParser({
+  name:       "icap",
+  entry:      parse,
+  entryName:  "parse",
+  errorClass: SafeIcapError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    ALLOWED_STATUS: ALLOWED_STATUS,
+    NAME:           "icap",
+    KIND:           "icap-response",
+  },
+});

package/lib/vendor/blamejs/lib/safe-sieve.js

@@ -49,6 +49,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var SafeSieveError = defineClass("SafeSieveError", { alwaysPermanent: true });
 
@@ -82,12 +83,7 @@ var PROFILES = Object.freeze({
   }),
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
-});
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
 
 // RFC 5228 §1.2 capability identifiers. Each entry lists whether the
 // framework's v0.9.55 interpreter implements the capability. Unknown
@@ -648,37 +644,22 @@ function validate(script, opts) {
   }
 }
 
-/**
- * @primitive  b.safeSieve.compliancePosture
- * @signature  b.safeSieve.compliancePosture(name)
- * @since      0.9.55
- * @status     stable
- * @related    b.safeSieve.parse, b.safeSieve.validate
- *
- * Look up the recommended profile name for a compliance posture
- * (`hipaa` / `pci-dss` / `gdpr` / `soc2`). Returns `"strict"` for any
- * known posture, `null` for unknown names. Operator-facing primitives
- * that thread `compliancePosture` opt through to safeSieve compose
- * this for the explicit-cast pattern when they need the name string
- * (rather than relying on `_resolveOpts` to do the lookup).
- *
- * @example
- *   b.safeSieve.compliancePosture("hipaa");            // → "strict"
- *   b.safeSieve.compliancePosture("loose");            // → null
- */
-function compliancePosture(name) {
-  return COMPLIANCE_POSTURES[name] || null;
-}
-
-module.exports = {
-  parse:              parse,
-  validate:           validate,
-  compliancePosture:  compliancePosture,
-  KNOWN_CAPABILITIES: KNOWN_CAPABILITIES,
-  PROFILES:           PROFILES,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  SafeSieveError:     SafeSieveError,
-  // Internal exports for the interpreter at lib/mail-sieve.js.
-  _tokenize:          _tokenize,
-  _resolveCaps:       _resolveCaps,
-};
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
+module.exports = gateContract.defineParser({
+  name:       "sieve",
+  entry:      parse,
+  entryName:  "parse",
+  errorClass: SafeSieveError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    validate:           validate,
+    KNOWN_CAPABILITIES: KNOWN_CAPABILITIES,
+    // Internal exports for the interpreter at lib/mail-sieve.js.
+    _tokenize:          _tokenize,
+    _resolveCaps:       _resolveCaps,
+  },
+});

package/lib/vendor/blamejs/lib/safe-sql.js

@@ -175,7 +175,7 @@ function validateIdentifier(name, opts) {
 
 /**
  * @primitive b.safeSql.quoteIdentifier
- * @signature b.safeSql.quoteIdentifier(name, dialect?)
+ * @signature b.safeSql.quoteIdentifier(name, dialect?, opts?)
  * @since     0.1.0
  * @status    stable
  * @related   b.safeSql.validateIdentifier, b.safeSql.quoteQualified
@@ -185,6 +185,17 @@ function validateIdentifier(name, opts) {
  * MySQL. Default dialect is `"sqlite"`. Throws `SafeSqlError` if the
  * identifier fails `validateIdentifier`.
  *
+ * `opts` is forwarded to `validateIdentifier` — pass
+ * `{ allowReserved: true }` to quote a name that collides with a SQL
+ * keyword (a column literally named `from` / `select`). Quoting is
+ * exactly what makes a reserved word safe in identifier position, so the
+ * query builder (`b.sql`) routes every identifier through here with
+ * `allowReserved` on; the default still rejects reserved words so a bare
+ * caller catches the likely typo.
+ *
+ * @opts
+ *   allowReserved:  boolean,   // default: false — permit SQL-keyword names (safe once quoted)
+ *
  * @example
  *   var b = require("blamejs");
  *   b.safeSql.quoteIdentifier("users");
@@ -193,11 +204,14 @@ function validateIdentifier(name, opts) {
  *   b.safeSql.quoteIdentifier("Order", "postgres");
  *   // → '"Order"'
  *
+ *   b.safeSql.quoteIdentifier("from", "postgres", { allowReserved: true });
+ *   // → '"from"'
+ *
  *   b.safeSql.quoteIdentifier("users", "mysql");
  *   // → "`users`"
  */
-function quoteIdentifier(name, dialect) {
-  validateIdentifier(name);
+function quoteIdentifier(name, dialect, opts) {
+  validateIdentifier(name, opts);
   dialect = (dialect || "sqlite").toLowerCase();
   if (dialect === "mysql") return "`" + name + "`";
   // sqlite + postgres both use double-quote per SQL standard
@@ -258,6 +272,53 @@ function quoteQualified(parts, dialect) {
   return quoted.join(".");
 }
 
+/**
+ * @primitive b.safeSql.quoteList
+ * @signature b.safeSql.quoteList(names, dialect?, opts?)
+ * @since     0.15.0
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.quoteQualified, b.sql
+ *
+ * Quote a list of identifiers into a comma-joined fragment — each name
+ * validated + quoted via `quoteIdentifier`. The "many" companion to
+ * `quoteIdentifier` (one) and `quoteQualified` (a dotted name): use it for
+ * SELECT projections and INSERT column lists so the recurring
+ * `cols.map(quoteIdentifier).join(", ")` shape is composed, not hand-rolled.
+ *
+ * There is deliberately NO value/string-literal quoter in this module:
+ * values flow as bound placeholders (`?` / `$N`), never interpolated, which
+ * is what makes the injection class structurally impossible. Quoting a
+ * literal would reopen it — use the query builder's parameter binding.
+ *
+ * `opts` is forwarded to each `quoteIdentifier` (e.g.
+ * `{ allowReserved: true }` for column lists that may contain SQL-keyword
+ * names, as `b.sql` does).
+ *
+ * Throws `SafeSqlError` (`sql/empty`) on an empty array and (per
+ * `quoteIdentifier`) on any invalid identifier.
+ *
+ * @opts
+ *   allowReserved:  boolean,   // default: false — forwarded to quoteIdentifier
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.quoteList(["id", "createdAt"], "postgres");
+ *   // → '"id", "createdAt"'
+ *
+ *   b.safeSql.quoteList(["queueName", "status"], "mysql");
+ *   // → "`queueName`, `status`"
+ */
+function quoteList(names, dialect, opts) {
+  if (!Array.isArray(names) || names.length === 0) {
+    throw new SafeSqlError("quoteList requires a non-empty array of identifiers", "sql/empty");
+  }
+  var out = [];
+  for (var i = 0; i < names.length; i++) {
+    out.push(quoteIdentifier(names[i], dialect, opts));
+  }
+  return out.join(", ");
+}
+
 /**
  * @primitive b.safeSql.assertOneOf
  * @signature b.safeSql.assertOneOf(name, allowlist)
@@ -310,6 +371,64 @@ function assertOneOf(name, allowlist) {
   return name;
 }
 
+/**
+ * @primitive b.safeSql.countPlaceholders
+ * @signature b.safeSql.countPlaceholders(sql)
+ * @since     0.14.29
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.validateIdentifier
+ *
+ * Count the bound `?` placeholders in a SQL string, skipping any `?`
+ * that appears inside a string literal (`'...'` / `"..."`, doubled-quote
+ * escape aware) or inside a line or block comment. The canonical quote-
+ * and comment-aware scanner the query builder uses to check placeholder /
+ * param parity and the residency write-gate uses to align bound values;
+ * both compose this so the skip rules live in one place.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeSql.countPlaceholders("a = ? AND b = ?");
+ *   // → 2
+ *
+ *   b.safeSql.countPlaceholders("note = 'is ? literal' AND id = ?");
+ *   // → 1
+ */
+function countPlaceholders(sql) {
+  var count = 0;
+  var i = 0;
+  var len = sql.length;
+  while (i < len) {
+    var ch = sql.charAt(i);
+    var next = i + 1 < len ? sql.charAt(i + 1) : "";
+    if (ch === "'" || ch === '"') {
+      var quote = ch;
+      i += 1;
+      while (i < len) {
+        if (sql.charAt(i) === quote) {
+          // SQL doubles the quote char to escape it within a literal.
+          if (sql.charAt(i + 1) === quote) { i += 2; continue; }
+          i += 1; break;
+        }
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === "-" && next === "-") {
+      while (i < len && sql.charAt(i) !== "\n") i += 1;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    if (ch === "?") count += 1;
+    i += 1;
+  }
+  return count;
+}
+
 /**
  * @primitive b.safeSql.DEFAULT_IDENTIFIER_RE
  * @signature b.safeSql.DEFAULT_IDENTIFIER_RE
@@ -351,11 +470,101 @@ function assertOneOf(name, allowlist) {
  *   // → 63
  */
 
+/**
+ * @primitive b.safeSql.assertSingleStatement
+ * @signature b.safeSql.assertSingleStatement(sql, opts?)
+ * @since     0.15.4
+ * @status    stable
+ * @related   b.safeSql.quoteIdentifier, b.safeSql.countPlaceholders, b.sql
+ *
+ * The one quote/comment-aware single-statement gate for any FINISHED SQL
+ * string that reaches a driver. Refuses a NUL, a lone surrogate, a
+ * top-level ';' (stacked statement), an unterminated quote, and unbalanced
+ * parentheses - while CORRECTLY allowing those characters inside a balanced
+ * quoted label (e.g. a MySQL ENUM('a;b')). Hand-rolled DDL (schema
+ * reconcile, the DSR store, migrations) and the b.sql builder's own output
+ * gates route through this single scan so the injection backstop cannot
+ * drift between the structured builder and the raw-DDL paths. Returns the
+ * input string so a caller can wrap inline:
+ *   runSql(db, safeSql.assertSingleStatement(ddl, { label: "schema" }));
+ *
+ * @opts
+ *   label:     string,    // message prefix (default: "sql")
+ *   makeError: function,  // (message, codeSuffix) => Error  (default: SafeSqlError "sql/<suffix>")
+ *
+ * @example
+ *   var ddl = b.safeSql.assertSingleStatement("CREATE TABLE t (id INTEGER)", { label: "schema" });
+ *   // returns the input string; throws sql/stacked-statement on a stacked DDL
+ */
+function assertSingleStatement(sql, opts) {
+  opts = opts || {};
+  var label = typeof opts.label === "string" ? opts.label : "sql";
+  var mkErr = typeof opts.makeError === "function"
+    ? opts.makeError
+    : function (msg, suffix) { return new SafeSqlError(msg, "sql/" + suffix); };
+  // Backtick written via its code point so no NUL byte can reach this source.
+  var BACKTICK = String.fromCharCode(96);
+  if (typeof sql !== "string" || sql.length === 0) {
+    throw mkErr(label + ": SQL must be a non-empty string", "empty-sql");
+  }
+  if (sql.indexOf(String.fromCharCode(0)) !== -1) {
+    throw mkErr(label + ": SQL contains a NUL byte - rejected", "null-byte-sql");
+  }
+  if (typeof sql.isWellFormed === "function" && !sql.isWellFormed()) {
+    throw mkErr(label + ": SQL contains invalid Unicode (lone surrogates) - rejected",
+      "invalid-encoding-sql");
+  }
+  var i = 0;
+  var len = sql.length;
+  var depth = 0;
+  while (i < len) {
+    var ch = sql.charAt(i);
+    var next = i + 1 < len ? sql.charAt(i + 1) : "";
+    if (ch === "'" || ch === '"' || ch === BACKTICK) {
+      var qch = ch;
+      var closed = false;
+      i += 1;
+      while (i < len) {
+        if (sql.charAt(i) === qch) {
+          if (sql.charAt(i + 1) === qch) { i += 2; continue; }  // doubled quote = escaped literal
+          i += 1; closed = true; break;
+        }
+        i += 1;
+      }
+      if (!closed) {
+        throw mkErr(label + ": unterminated quote in SQL (quote-jump / breakout risk)",
+          "unterminated-quote");
+      }
+      continue;
+    }
+    if (ch === "-" && next === "-") { while (i < len && sql.charAt(i) !== "\n") i += 1; continue; }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < len && !(sql.charAt(i) === "*" && sql.charAt(i + 1) === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    if (ch === "(") { depth += 1; }
+    else if (ch === ")") { depth -= 1; }
+    else if (ch === ";") {
+      throw mkErr(label + ": emitted a top-level ';' - exactly one statement", "stacked-statement");
+    }
+    i += 1;
+  }
+  if (depth !== 0) {
+    throw mkErr(label + ": unbalanced parentheses in SQL", "unbalanced");
+  }
+  return sql;
+}
+
 module.exports = {
   validateIdentifier:  validateIdentifier,
+  assertSingleStatement: assertSingleStatement,
   quoteIdentifier:     quoteIdentifier,
   quoteQualified:      quoteQualified,
+  quoteList:           quoteList,
   assertOneOf:         assertOneOf,
+  countPlaceholders:   countPlaceholders,
   SafeSqlError:        SafeSqlError,
   // Exposed so consumers can compose their own validators
   DEFAULT_IDENTIFIER_RE: DEFAULT_IDENTIFIER_RE,

package/lib/vendor/blamejs/lib/safe-url.js

@@ -53,6 +53,11 @@ var nodeUrl = require("node:url");
 var { URL } = require("node:url");
 
 var audit = lazyRequire(function () { return require("./audit"); });
+// ssrf-guard requires safe-url at top of file (the SSRF gate parses through
+// the framework's defensive URL parser); lazyRequire breaks that cycle so the
+// canonicalizer can reuse ssrf-guard's IP-literal canonicalization without an
+// at-load circular require.
+var ssrfGuard = lazyRequire(function () { return require("./ssrf-guard"); });
 
 /**
  * @primitive b.safeUrl.ALLOW_HTTP_TLS
@@ -168,9 +173,9 @@ var ALLOW_ANY      = Object.freeze(["http:", "https:", "ws:", "wss:"]);
  * Extends `FrameworkError`. Carries a stable `.code`:
  * `safe-url/missing` / `safe-url/too-long` / `safe-url/malformed` /
  * `safe-url/protocol-disallowed` / `safe-url/userinfo-disallowed` /
- * `safe-url/idn-homograph` / `safe-url/bad-opt`. HTTP middleware
- * inspects `.code` to translate the throw into a 400 without
- * leaking parser internals.
+ * `safe-url/idn-homograph` / `safe-url/uncanonicalizable` /
+ * `safe-url/bad-opt`. HTTP middleware inspects `.code` to translate
+ * the throw into a 400 without leaking parser internals.
  *
  * @example
  *   var b = require("blamejs");
@@ -205,6 +210,38 @@ function _makeError(errorClass, code, message) {
 // payloads) override via opts.maxUrlLength.
 var DEFAULT_MAX_URL_LENGTH = C.BYTES.kib(8);
 
+// RFC 3986 §6.2.2 percent-encoding normalization applied CONSERVATIVELY to a
+// path segment string: uppercase the two hex digits of every valid escape
+// (§6.2.2.2) and decode an escape of an unreserved character to its literal
+// (§6.2.2.3). A malformed escape (`%`, `%g`, `%4`) is passed through verbatim
+// so no information is invented. Query and fragment are NOT touched —
+// reordering / re-decoding there can change application semantics (a `%26`
+// inside a value is NOT the same as a literal `&`).
+function _normalizePctPath(path) {
+  if (typeof path !== "string" || path.indexOf("%") === -1) return path;
+  var out = "";
+  for (var i = 0; i < path.length; i += 1) {
+    var ch = path.charAt(i);
+    if (ch === "%") {
+      // The escape's two hex digits — sliced to a fixed two-char window so
+      // the regex test runs on a length-bounded string (no ReDoS surface).
+      var pair = path.slice(i + 1, i + 3);
+      if (pair.length === 2 && codepointClass.HEX_PAIR_RE.test(pair)) {
+        var cc = parseInt(pair, 16);
+        if (codepointClass.isUnreserved(cc)) {
+          out += String.fromCharCode(cc);
+        } else {
+          out += "%" + pair.toUpperCase();
+        }
+        i += 2;
+        continue;
+      }
+    }
+    out += ch;
+  }
+  return out;
+}
+
 /**
  * @primitive b.safeUrl.parse
  * @signature b.safeUrl.parse(url, opts?)
@@ -416,9 +453,139 @@ function format(url) {
   }
 }
 
+/**
+ * @primitive b.safeUrl.canonicalize
+ * @signature b.safeUrl.canonicalize(input, opts?)
+ * @since     0.15.6
+ * @status    stable
+ * @related   b.safeUrl.parse, b.ssrfGuard.canonicalizeHost, b.ssrfGuard.checkUrl
+ *
+ * Return the single canonical, comparable form of a URL so two
+ * spellings of the same destination compare equal as strings. The use
+ * cases are host allowlists, dedup / cache keys, and SSRF pre-checks —
+ * exactly the places an attacker reaches for an obfuscated host
+ * (`http://0177.0.0.1/`, `http://2130706433/`, `http://[::ffff:7f00:1]/`,
+ * an IDN homograph, a trailing-dot or default-port variation) to slip
+ * past a naive `===` allowlist. Routing every comparison through one
+ * audited canonicalizer closes that class instead of leaving each
+ * caller to re-derive normalization (which is how the bypasses happen).
+ *
+ * The canonical form is built from `parse`'s defensive gates plus the
+ * security-relevant normalization set:
+ *
+ *   - Scheme and host lowercased (the WHATWG URL parser does this).
+ *   - Host IDN labels emitted as their punycode `xn--` A-label; a
+ *     mixed-script / confusable host label THROWS exactly as
+ *     `parse` does (a homograph is never silently passed) unless the
+ *     caller opts in via `allowMixedScript` / `allowedScripts`.
+ *   - A trailing dot on the host is removed (`example.com.` →
+ *     `example.com`) — DNS-equivalent but breaks string comparison.
+ *   - An IP-literal host in ANY notation collapses to one canonical
+ *     string via `b.ssrfGuard.canonicalizeHost` (the SAME byte parser
+ *     the SSRF classifier matches on): IPv4 decimal / octal / hex /
+ *     shorthand → dotted-quad; IPv6 (incl. IPv4-mapped + any
+ *     zero-compression) → RFC 5952 lower-hex, bracketed.
+ *   - The default port for the scheme is stripped (`:80` http/ws,
+ *     `:443` https/wss — the parser does this).
+ *   - Path `.` / `..` segments resolved (WHATWG), then RFC 3986 §6.2.2
+ *     percent-normalization applied to the path: hex digits uppercased,
+ *     escapes of unreserved characters decoded. Query and fragment are
+ *     left BYTE-FOR-BYTE as parsed — reordering or re-decoding there can
+ *     change application semantics.
+ *
+ * Throws `SafeUrlError` (or `opts.errorClass`): the `parse` codes for a
+ * missing / too-long / malformed / disallowed-scheme / userinfo /
+ * homograph input, plus `safe-url/uncanonicalizable` when a parsed URL
+ * cannot be reduced to a safe canonical form. This is a config /
+ * entry-point validator — it THROWS on bad input, it does NOT return a
+ * best-effort string.
+ *
+ * @opts
+ *   allowedSchemes:   string[],   // default ALLOW_ANY (http/https/ws/wss); canonicalize is a compare tool, not a fetch gate
+ *   allowUserinfo:    boolean,    // default false; opt-in to keep user:pass@ (still discouraged)
+ *   allowMixedScript: boolean,    // default false; opt-in to mixed-script host labels
+ *   allowedScripts:   string[],   // narrow mixed-script allowlist (e.g. ["latin","cyrillic"])
+ *   maxUrlLength:     number,     // default 8192 (RFC 7230 §3.1.1)
+ *   errorClass:       Function,   // throw this instead of SafeUrlError
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Every obfuscated loopback spelling collapses to one string.
+ *   b.safeUrl.canonicalize("http://0177.0.0.1/");      // → "http://127.0.0.1/"
+ *   b.safeUrl.canonicalize("http://2130706433/");      // → "http://127.0.0.1/"
+ *   b.safeUrl.canonicalize("http://127.1/");           // → "http://127.0.0.1/"
+ *
+ *   // Case, default port, trailing dot, and `..` all normalize.
+ *   b.safeUrl.canonicalize("https://Example.COM:443/a/../b");
+ *   // → "https://example.com/b"
+ *
+ *   // A disallowed scheme throws SafeUrlError.
+ *   try { b.safeUrl.canonicalize("ftp://example.com/"); }
+ *   catch (e) { e.code; }   // → "safe-url/protocol-disallowed"
+ */
+function canonicalize(input, opts) {
+  opts = opts || {};
+  var allowedSchemes = Array.isArray(opts.allowedSchemes) && opts.allowedSchemes.length > 0
+    ? opts.allowedSchemes
+    : ALLOW_ANY;
+
+  // Route through parse — it owns the length cap, the scheme allowlist,
+  // userinfo refusal, and the IDN-homograph defense. A parse throw (with
+  // its stable .code) propagates unchanged so callers branch on the same
+  // codes parse documents.
+  var parsed = parse(input, {
+    allowedProtocols: allowedSchemes,
+    maxUrlLength:     opts.maxUrlLength,
+    allowUserinfo:    opts.allowUserinfo,
+    allowMixedScript: opts.allowMixedScript,
+    allowedScripts:   opts.allowedScripts,
+    errorClass:       opts.errorClass,
+  });
+
+  try {
+    // The parser already lowercased the scheme + host, stripped the
+    // default port, emitted IDN as punycode, and resolved `.`/`..`. The
+    // canonicalizer adds: IP-literal collapse (shared with the SSRF
+    // classifier), trailing-dot removal, and path percent-normalization.
+    var scheme = parsed.protocol;                 // e.g. "https:"
+    var rawHost = parsed.hostname;                // already lowercase / punycode / default-port-free
+    var canonHost = ssrfGuard().canonicalizeHost(rawHost);
+    // canonicalizeHost returns IPv6 UNbracketed; a URL authority needs the
+    // brackets back. net.isIP via the colon is a sufficient discriminator
+    // (a DNS label can't contain a colon).
+    var host = canonHost.indexOf(":") !== -1 ? "[" + canonHost + "]" : canonHost;
+
+    // Userinfo (`user:pass@`) is deliberately DROPPED from the canonical form.
+    // The canonical string is built to be compared, used as a dedup / cache
+    // key, or logged; carrying a credential into any of those leaks it, and
+    // the username/password are not part of the resource's target identity for
+    // an allowlist / SSRF decision. parse() already refuses userinfo unless
+    // allowUserinfo:true; even then, the canonical output omits it (never reads
+    // parsed.password), so two URLs that differ only in credentials canonicalize
+    // equal.
+
+    var port = parsed.port !== "" ? ":" + parsed.port : "";
+    var path = _normalizePctPath(parsed.pathname);
+    // Query + fragment: byte-for-byte as the parser emitted them. Reordering
+    // a query or re-decoding a value changes semantics — out of scope for a
+    // safe canonicalizer.
+    var query = parsed.search;
+    var fragment = parsed.hash;
+
+    return scheme + "//" + host + port + path + query + fragment;
+  } catch (e) {
+    if (e && e.isSafeUrlError) throw e;
+    throw _makeError(opts.errorClass, "safe-url/uncanonicalizable",
+      "safeUrl.canonicalize could not reduce the URL to a canonical form: " +
+        ((e && e.message) || String(e)));
+  }
+}
+
 module.exports = {
   parse:           parse,
   format:          format,
+  canonicalize:    canonicalize,
   SafeUrlError:    SafeUrlError,
   ALLOW_HTTP_TLS:  ALLOW_HTTP_TLS,
   ALLOW_HTTP_ALL:  ALLOW_HTTP_ALL,