hazo_secure 1.5.0 → 1.6.0

package/CHANGE_LOG.md

@@ -1,5 +1,54 @@
 # Change Log
 
+## Unreleased — fetch dispatcher bugfix (2026-07-22)
+
+**NOTE (extractor_asx build session):** found and fixed while wiring
+`extractor_asx`'s live dividends-extraction smoke test. Left un-numbered
+since `1.6.0` above already has substantial unrelated in-progress work
+staged in this working tree — fold into `1.6.0` or ship as `1.6.1`,
+whichever fits how you're cutting the release.
+
+### Fixed: `hazo_secure/fetch` — `createSecureDispatcher`'s DNS lookup broke EVERY real fetch
+
+- `src/fetch/dispatcher.ts`'s custom undici `Agent` `connect.lookup` ignored
+  the `options` undici actually passes (`{hints, all:true}` on every real
+  request — confirmed by logging it), always calling back with a single
+  `(address, family)` pair regardless. Node's `net` connect logic expects an
+  array of `{address,family}` records when `all:true` was requested; getting
+  a bare string instead threw `TypeError [ERR_INVALID_IP_ADDRESS]: Invalid
+  IP address: undefined` deep inside `net`, which undici's `fetch` wrapped
+  as an opaque `TypeError: fetch failed` with the real cause hidden in
+  `.cause`. **This broke every real HTTPS fetch through `safeFetch`** —
+  reproduced against multiple unrelated hosts, not specific to one site.
+- Fix: `lookup` now always resolves via `dns.lookup(hostname, {all:true},
+  cb)` internally, validates (SSRF-checks) **every** returned address (not
+  just the first — a multi-record response could mix a public and a
+  private/rebound IP), then reshapes the result to match what the caller
+  actually asked for (single pair vs array) via a new exported pure
+  function, `shapeLookupResult`, added specifically so this logic is
+  unit-testable without mocking `node:dns` (this package's `test/` has no
+  existing DNS-mocking seam).
+- New tests in `test/fetch/dispatcher.test.ts` (`describe('shapeLookupResult', ...)`)
+  cover the `all:true`/`all:false` shaping and confirm a private IP anywhere
+  in a multi-record response is caught, not just the first record.
+- Verified against the real failing case: `safeFetch('https://www.macquarie.com/...')`
+  went from throwing `fetch failed` to a real `200` with the full page body.
+
+## 1.6.0 — 2026-07-22
+
+### New: `hazo_secure/mask/display` — client-safe display masks
+
+- **`maskTFN` / `maskABN` moved to a new `hazo_secure/mask/display` subpath**
+  (`src/mask/display.ts`), a pure module with **no Node built-in imports**.
+  `hazo_secure/mask` (`src/mask/index.ts`) statically imports `node:crypto`
+  and `node:module` (`createRequire`, for the lazy `wink-nlp` load in
+  `redact_pii`), so it cannot be bundled for the browser. Consumers that only
+  need the display masks in client/browser code must import from
+  `hazo_secure/mask/display`.
+- **Back-compat:** `hazo_secure/mask` still re-exports `maskTFN`/`maskABN`
+  (via `export { maskTFN, maskABN } from './display'`), so existing
+  server-side imports are unchanged. No API surface removed.
+
 ## 1.5.0 — 2026-07-21
 
 ### New: `hazo_secure/mask` — `maskTFN` / `maskABN` display masks

package/dist/fetch/index.d.ts

@@ -16,6 +16,23 @@ declare function validateConnectIp(ip: string): void;
  * record flips after the pre-flight check, the IP is re-validated here.
  *
  * Node 18+ ships undici as a built-in; we pin an explicit dep for stability.
+ *
+ * BUGFIX (2026-07-22): undici's Agent invokes this `lookup` with
+ * `{hints, all:true}` on every real request (confirmed by logging the actual
+ * options undici passes) — the previous implementation ignored `_options`
+ * entirely and always called back with a single `(address, family)` pair.
+ * When `net`'s internal connect logic expects an array (because it asked for
+ * `all:true`) but gets a bare string instead, it throws
+ * `TypeError [ERR_INVALID_IP_ADDRESS]: Invalid IP address: undefined` —
+ * which undici's fetch wraps as a generic `TypeError: fetch failed` with no
+ * indication of the real cause. This broke EVERY real HTTPS fetch through
+ * this dispatcher (reproduced against multiple unrelated hosts, not
+ * something specific to one site) — pre-flight `validateUrl`'s DNS check
+ * passing gave false confidence that fetches would actually succeed.
+ * `dns.lookup` is now always called with `{all:true}` internally regardless
+ * of what the caller asked for, so every resolved address gets SSRF-checked
+ * (see `shapeLookupResult`'s doc comment), then reshaped to match what the
+ * caller actually requested.
  */
 declare function createSecureDispatcher(): Agent;
 

package/dist/fetch/index.js

@@ -86,18 +86,30 @@ function validateConnectIp(ip) {
     throw err;
   }
 }
+function shapeLookupResult(records, wantsAll) {
+  for (const record of records) validateConnectIp(record.address);
+  if (wantsAll) {
+    return { address: records.map((r) => ({ address: r.address, family: r.family })), family: 0 };
+  }
+  const first = records[0];
+  return { address: first.address, family: first.family };
+}
 function createSecureDispatcher() {
   return new Agent({
     connect: {
-      lookup(hostname, _options, callback) {
-        dns.lookup(hostname, (err, address, family) => {
-          if (err) return callback(err, "", 4);
+      lookup(hostname, options, callback) {
+        const wantsAll = typeof options === "object" && options !== null && options.all === true;
+        dns.lookup(hostname, { all: true }, (err, records) => {
+          if (err) return callback(err, wantsAll ? [] : "", 4);
+          if (records.length === 0) {
+            return callback(new Error(`DNS lookup for ${hostname} returned no records`), wantsAll ? [] : "", 4);
+          }
           try {
-            validateConnectIp(address);
+            const shaped = shapeLookupResult(records, wantsAll);
+            callback(null, shaped.address, shaped.family);
           } catch (ssrfErr) {
-            return callback(ssrfErr, "", 4);
+            callback(ssrfErr, wantsAll ? [] : "", 4);
           }
-          callback(null, address, family);
         });
       }
     }

package/dist/mask/display.d.ts

@@ -0,0 +1,28 @@
+/**
+ * maskTFN — mask an Australian Tax File Number for display, revealing only
+ * the last 3 digits.
+ *
+ * TFNs are commonly rendered/entered as `123 456 789` or `123456789`;
+ * whitespace is stripped before masking so both forms produce the same
+ * output. Returns `"***"` for inputs too short to safely reveal 3 digits,
+ * and `""` for null/undefined/empty input.
+ *
+ * @param tfn - raw or space-formatted TFN, or null/undefined
+ * @returns a `"***-***-789"`-shaped string, `"***"`, or `""`
+ */
+declare function maskTFN(tfn: string | null | undefined): string;
+/**
+ * maskABN — mask an Australian Business Number for display, revealing only
+ * the last 3 digits.
+ *
+ * ABNs are commonly rendered/entered as `12 345 678 901` or `12345678901`;
+ * whitespace is stripped before masking so both forms produce the same
+ * output. Returns `"***"` for inputs too short to safely reveal 3 digits,
+ * and `""` for null/undefined/empty input.
+ *
+ * @param abn - raw or space-formatted ABN, or null/undefined
+ * @returns a `"**-***-***-901"`-shaped string, `"***"`, or `""`
+ */
+declare function maskABN(abn: string | null | undefined): string;
+
+export { maskABN, maskTFN };

package/dist/mask/display.js

@@ -0,0 +1,17 @@
+// src/mask/display.ts
+function maskTFN(tfn) {
+  if (!tfn) return "";
+  const cleaned = tfn.replace(/\s/g, "");
+  if (cleaned.length < 3) return "***";
+  return `***-***-${cleaned.slice(-3)}`;
+}
+function maskABN(abn) {
+  if (!abn) return "";
+  const cleaned = abn.replace(/\s/g, "");
+  if (cleaned.length < 3) return "***";
+  return `**-***-***-${cleaned.slice(-3)}`;
+}
+export {
+  maskABN,
+  maskTFN
+};

package/dist/mask/index.d.ts

@@ -1,3 +1,5 @@
+export { maskABN, maskTFN } from './display.js';
+
 /**
  * mask_email — replace with deterministic masked email.
  * alice@example.com → a3f9b12c1d2e@masked.example
@@ -34,32 +36,7 @@ declare function drop(_value: unknown, _col: string, _maskKey: string): unknown;
  * nullify — replace with null (less aggressive than drop; preserves column semantics).
  */
 declare function nullify(_value: unknown, _col: string, _maskKey: string): unknown;
-/**
- * maskTFN — mask an Australian Tax File Number for display, revealing only
- * the last 3 digits.
- *
- * TFNs are commonly rendered/entered as `123 456 789` or `123456789`;
- * whitespace is stripped before masking so both forms produce the same
- * output. Returns `"***"` for inputs too short to safely reveal 3 digits,
- * and `""` for null/undefined/empty input.
- *
- * @param tfn - raw or space-formatted TFN, or null/undefined
- * @returns a `"***-***-789"`-shaped string, `"***"`, or `""`
- */
-declare function maskTFN(tfn: string | null | undefined): string;
-/**
- * maskABN — mask an Australian Business Number for display, revealing only
- * the last 3 digits.
- *
- * ABNs are commonly rendered/entered as `12 345 678 901` or `12345678901`;
- * whitespace is stripped before masking so both forms produce the same
- * output. Returns `"***"` for inputs too short to safely reveal 3 digits,
- * and `""` for null/undefined/empty input.
- *
- * @param abn - raw or space-formatted ABN, or null/undefined
- * @returns a `"**-***-***-901"`-shaped string, `"***"`, or `""`
- */
-declare function maskABN(abn: string | null | undefined): string;
+
 /**
  * redact_pii — NER-based PII redaction (wink-nlp lite model).
  * Detects named entities (dates, cardinals, etc.) and replaces them with [REDACTED_TYPE].
@@ -71,4 +48,4 @@ declare function redact_pii(value: unknown, _col: string, _maskKey: string): unk
 declare const BUILTIN_TRANSFORMS: Record<string, (value: unknown, col: string, maskKey: string) => unknown>;
 type MaskTransformFn = (value: unknown, col: string, maskKey: string) => unknown;
 
-export { BUILTIN_TRANSFORMS, type MaskTransformFn, drop, fake_name, hash, jitter_date, maskABN, maskTFN, mask_email, mask_phone, nullify, redact_pii, tokenize };
+export { BUILTIN_TRANSFORMS, type MaskTransformFn, drop, fake_name, hash, jitter_date, mask_email, mask_phone, nullify, redact_pii, tokenize };

package/dist/mask/index.js

@@ -1,5 +1,21 @@
 // src/mask/index.ts
 import { createHmac } from "crypto";
+
+// src/mask/display.ts
+function maskTFN(tfn) {
+  if (!tfn) return "";
+  const cleaned = tfn.replace(/\s/g, "");
+  if (cleaned.length < 3) return "***";
+  return `***-***-${cleaned.slice(-3)}`;
+}
+function maskABN(abn) {
+  if (!abn) return "";
+  const cleaned = abn.replace(/\s/g, "");
+  if (cleaned.length < 3) return "***";
+  return `**-***-***-${cleaned.slice(-3)}`;
+}
+
+// src/mask/index.ts
 import { createRequire } from "module";
 function hmacHex(value, maskKey, context) {
   return createHmac("sha256", maskKey).update(`${context}:${value}`).digest("hex");
@@ -58,18 +74,6 @@ function drop(_value, _col, _maskKey) {
 function nullify(_value, _col, _maskKey) {
   return null;
 }
-function maskTFN(tfn) {
-  if (!tfn) return "";
-  const cleaned = tfn.replace(/\s/g, "");
-  if (cleaned.length < 3) return "***";
-  return `***-***-${cleaned.slice(-3)}`;
-}
-function maskABN(abn) {
-  if (!abn) return "";
-  const cleaned = abn.replace(/\s/g, "");
-  if (cleaned.length < 3) return "***";
-  return `**-***-***-${cleaned.slice(-3)}`;
-}
 var _esmReq = createRequire(import.meta.url);
 var _nlpInstance = null;
 var _nlpIts = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_secure",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Security & compliance primitives — SSRF-safe fetch, rate limiting, field-level encryption, GDPR orchestration, CSRF. Five subpath modules, pick the ones you need.",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,6 +42,11 @@
       "import": "./dist/mask/index.js",
       "default": "./dist/mask/index.js"
     },
+    "./mask/display": {
+      "types": "./dist/mask/display.d.ts",
+      "import": "./dist/mask/display.js",
+      "default": "./dist/mask/display.js"
+    },
     "./secrets": {
       "types": "./dist/secrets/index.d.ts",
       "import": "./dist/secrets/index.js",