hazo_secure 1.3.0 → 1.5.0

package/CHANGE_LOG.md

@@ -1,5 +1,57 @@
 # Change Log
 
+## 1.5.0 — 2026-07-21
+
+### New: `hazo_secure/mask` — `maskTFN` / `maskABN` display masks
+
+- **`maskTFN(tfn)`** — masks an Australian Tax File Number for display,
+  revealing only the last 3 digits (`"***-***-789"`). Strips whitespace
+  before masking so both `"123456789"` and `"123 456 789"` normalise the
+  same way. Returns `"***"` for inputs too short to safely reveal 3 digits,
+  `""` for null/undefined/empty.
+- **`maskABN(abn)`** — same shape for Australian Business Numbers
+  (`"**-***-***-901"`).
+- Deliberately not added to `BUILTIN_TRANSFORMS` — these take no `maskKey`
+  and aren't deterministic-by-key like the existing DB-anonymisation
+  transforms; they're pure display formatting. Ported from Hazodocs
+  `lib/formatting.ts` (`maskTFN`/`maskABN`, previously app-local per D-011).
+
+### New: `hazo_secure/crypto` — `randomCode` / `randomToken` / `hashToken` / `verifyToken`
+
+- **`randomCode(length = 16)`** — cryptographically secure code from a
+  human-readable alphabet (`[A-Z2-9]`, excludes ambiguous `0`/`O`/`1`/`I`/`L`).
+  Throws for `length < 8` (inadequate entropy).
+- **`randomToken(bytes = 32)`** — cryptographically secure base64url token
+  (43 chars at the default byte length).
+- **`hashToken(raw)`** — scrypt-hashes a raw token under a random 16-byte
+  salt for at-rest storage; returns `"<saltHex>:<hashHex>"`.
+- **`verifyToken(raw, stored)`** — recomputes the scrypt hash under the
+  embedded salt and compares in constant time via `timingSafeEqual`. Fails
+  closed (`false`, never throws) for a malformed `stored` value.
+- Added as a sibling module (`src/crypto/tokens.ts`) alongside the existing
+  `signHmac`/`verifyHmac` primitives in the same `./crypto` subpath — no new
+  subpath export. Ported from Hazodocs `lib/security/random.ts` and
+  `lib/invitations/tokens.ts`.
+
+## 1.4.0 — 2026-07-12
+
+### New: `hazo_secure/crypto` — generic HMAC sign/verify primitive
+
+- **`signHmac(payload, secret)`** — signs an arbitrary UTF-8 payload string
+  with HMAC-SHA256, returning a `<payloadB64url>.<sigB64url>` token. No
+  expiry/claims logic — callers put their own JSON in the payload and handle
+  their own expiry/revocation.
+- **`verifyHmac(token, secret)`** — constant-time verification via
+  `timingSafeEqual`, with a length pre-check on the signature against a
+  fixed constant before comparing, and a caught missing/empty-secret path
+  that fails closed with `{ valid: false, reason: "malformed" }` instead of
+  throwing. Returns `{ valid: true, payload }` with the decoded original
+  payload string on success.
+- **`HmacVerifyResult`** type: `{ valid: true; payload: string } | { valid: false; reason: "malformed" | "signature_mismatch" }`.
+- Dependency-free (only `node:crypto`); added to the existing `./crypto`
+  subpath export, no new subpath. Motivated by `hazo_embed`'s need for
+  domain-locked embed-key token signing, but kept fully generic.
+
 ## 1.3.0 — 2026-06-12
 
 ### New: `hazo_secure/secrets` — SecretsProvider

package/README.md

@@ -93,6 +93,33 @@ gdpr.registerExporter({
 });
 ```
 
+## New in 1.5.0
+
+### `hazo_secure/mask` — `maskTFN` / `maskABN` display masks
+
+```ts
+import { maskTFN, maskABN } from "hazo_secure/mask";
+
+maskTFN("123 456 789");    // "***-***-789"
+maskABN("12 345 678 901"); // "**-***-***-901"
+```
+
+Pure display formatting for Australian Tax File Numbers / ABNs — reveals only the last 3 digits, tolerant of space-formatted input, `""` for null/undefined/empty. Not part of `BUILTIN_TRANSFORMS` (no `maskKey`, not a DB-anonymisation transform).
+
+### `hazo_secure/crypto` — `randomCode` / `randomToken` / `hashToken` / `verifyToken`
+
+```ts
+import { randomCode, randomToken, hashToken, verifyToken } from "hazo_secure/crypto";
+
+const code = randomCode();          // "K7XQ9M2Z4RHY8VNC" — human-readable, no 0/O/1/I/L
+const token = randomToken();        // base64url, 32 random bytes by default
+
+const stored = await hashToken(token);          // "<saltHex>:<hashHex>" — store this
+const ok = await verifyToken(token, stored);     // true
+```
+
+`hashToken`/`verifyToken` use scrypt with a random per-token salt; `verifyToken` fails closed (`false`, never throws) for a malformed stored value.
+
 ## New in 1.0.0
 
 ### `hazo_secure/ratelimit` — ConnectRateLimitStore (token bucket)

package/dist/crypto/index.d.ts

@@ -31,6 +31,75 @@ declare class HttpKeyProvider implements KeyProvider {
     clearCache(): void;
 }
 
+/**
+ * Sign an arbitrary UTF-8 payload string with HMAC-SHA256, returning a
+ * `<payloadB64url>.<sigB64url>` token. The payload is opaque to this
+ * module — callers put their own JSON (or any string) in it and are
+ * responsible for their own expiry/revocation semantics; this primitive
+ * only proves the payload wasn't tampered with and was signed under `secret`.
+ */
+declare function signHmac(payload: string, secret: string): string;
+type HmacVerifyResult = {
+    valid: true;
+    payload: string;
+} | {
+    valid: false;
+    reason: "malformed" | "signature_mismatch";
+};
+/**
+ * Verify a token produced by `signHmac`. Constant-time signature comparison
+ * via `timingSafeEqual`, with a length pre-check against a fixed constant
+ * (not secret-dependent) so short/garbage signatures never reach the
+ * timing-safe path. Fails closed — never throws, even for a missing/empty
+ * `secret` or a malformed token.
+ */
+declare function verifyHmac(token: string, secret: string): HmacVerifyResult;
+
+/**
+ * Generate a cryptographically secure random code using a human-readable
+ * base32-ish alphabet. Excludes visually ambiguous characters (`0`/`O`,
+ * `1`/`I`/`L`) to minimize transcription errors — suitable for codes a
+ * person reads aloud or copies from a screen/print-out (invitation codes,
+ * short-lived verification codes, etc.).
+ *
+ * @param length - desired code length (default: 16 chars)
+ * @throws {Error} if `length < 8` (inadequate entropy)
+ * @returns a string of `length` characters drawn from `[A-Z2-9]` excluding `0`/`O`/`1`/`I`/`L`
+ */
+declare function randomCode(length?: number): string;
+/**
+ * Generate a cryptographically secure random token in base64url encoding.
+ * Suitable for session tokens, API keys, password-reset tokens, and
+ * invitation tokens.
+ *
+ * @param bytes - number of random bytes (default: 32, resulting in 43 base64url chars)
+ * @returns a base64url string (no `+`, `/`, or `=` padding)
+ */
+declare function randomToken(bytes?: number): string;
+/**
+ * Hash a raw token for at-rest storage using scrypt with a random 16-byte
+ * salt. The returned string embeds the salt so `verifyToken` doesn't need it
+ * supplied separately — store the returned string verbatim (e.g. in a
+ * `token_hash` column) and discard the raw token.
+ *
+ * Format: `<saltHex>:<hashHex>` (scrypt output is 64 bytes / 128 hex chars).
+ *
+ * @param raw - the plaintext token to hash (e.g. output of `randomToken`)
+ * @returns `"<saltHex>:<hashHex>"`
+ */
+declare function hashToken(raw: string): Promise<string>;
+/**
+ * Verify a raw token against a hash produced by `hashToken`. Recomputes the
+ * scrypt hash under the embedded salt and compares in constant time via
+ * `timingSafeEqual`. Fails closed — returns `false` (never throws) for a
+ * malformed `stored` value (wrong shape, non-hex segments, etc.).
+ *
+ * @param raw - the plaintext token supplied by the caller
+ * @param stored - the `"<saltHex>:<hashHex>"` string previously returned by `hashToken`
+ * @returns `true` if `raw` hashes to `stored` under its embedded salt, else `false`
+ */
+declare function verifyToken(raw: string, stored: string): Promise<boolean>;
+
 /**
  * Source of symmetric keys for `encryptField` / `decryptField`. The current
  * key is used for encryption; `byId` resolves any key (current or rotated-out)
@@ -177,4 +246,4 @@ declare class LookupKeyProvider implements KeyProvider {
  *  Convention: `<table>:<entityId>:<field>` — collision-free across tables. */
 declare function aadFor(table: string, entityId: string, field: string): string;
 
-export { CryptoError, type CryptoErrorCode, type EncryptedField, EnvKeyProvider, HttpKeyProvider, type HttpKeyProviderOptions, type KeyProvider, LookupKeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };
+export { CryptoError, type CryptoErrorCode, type EncryptedField, EnvKeyProvider, type HmacVerifyResult, HttpKeyProvider, type HttpKeyProviderOptions, type KeyProvider, LookupKeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField, hashToken, randomCode, randomToken, signHmac, verifyHmac, verifyToken };

package/dist/crypto/index.js

@@ -1,5 +1,5 @@
 // src/crypto/index.ts
-import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2 } from "crypto";
 import { HazoError } from "hazo_core";
 
 // src/crypto/provider-http.ts
@@ -79,6 +79,87 @@ var HttpKeyProvider = class {
   }
 };
 
+// src/crypto/hmac.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var HMAC_B64URL_LEN = 43;
+function b64url(input) {
+  const buf = typeof input === "string" ? Buffer.from(input, "utf8") : input;
+  return buf.toString("base64").replace(/=+$/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function b64urlDecode(input) {
+  const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - input.length % 4);
+  return Buffer.from(input.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+}
+function sign(payloadB64, secret) {
+  if (!secret) throw new Error("hazo_secure/crypto: HMAC secret is not set");
+  return b64url(createHmac("sha256", secret).update(payloadB64).digest());
+}
+function signHmac(payload, secret) {
+  const payloadB64 = b64url(payload);
+  const sig = sign(payloadB64, secret);
+  return `${payloadB64}.${sig}`;
+}
+function verifyHmac(token, secret) {
+  if (!secret) return { valid: false, reason: "malformed" };
+  if (!token || typeof token !== "string") return { valid: false, reason: "malformed" };
+  const parts = token.split(".");
+  if (parts.length !== 2) return { valid: false, reason: "malformed" };
+  const [payloadB64, sig] = parts;
+  if (sig.length !== HMAC_B64URL_LEN) {
+    return { valid: false, reason: "signature_mismatch" };
+  }
+  let expectedSig;
+  try {
+    expectedSig = sign(payloadB64, secret);
+  } catch {
+    return { valid: false, reason: "malformed" };
+  }
+  const a = Buffer.from(sig);
+  const b = Buffer.from(expectedSig);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    return { valid: false, reason: "signature_mismatch" };
+  }
+  let payload;
+  try {
+    payload = b64urlDecode(payloadB64).toString("utf8");
+  } catch {
+    return { valid: false, reason: "malformed" };
+  }
+  return { valid: true, payload };
+}
+
+// src/crypto/tokens.ts
+import { randomBytes, randomInt, scryptSync, timingSafeEqual as timingSafeEqual2 } from "crypto";
+var CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+var SCRYPT_KEY_LEN = 64;
+function randomCode(length = 16) {
+  if (length < 8) {
+    throw new Error(`randomCode length must be >= 8 for adequate entropy (got ${length})`);
+  }
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += CODE_ALPHABET[randomInt(0, CODE_ALPHABET.length)];
+  }
+  return out;
+}
+function randomToken(bytes = 32) {
+  return randomBytes(bytes).toString("base64url");
+}
+async function hashToken(raw) {
+  const salt = randomBytes(16);
+  const hash = scryptSync(raw, salt, SCRYPT_KEY_LEN);
+  return `${salt.toString("hex")}:${hash.toString("hex")}`;
+}
+async function verifyToken(raw, stored) {
+  const [saltHex, hashHex] = stored.split(":");
+  if (!saltHex || !hashHex) return false;
+  const salt = Buffer.from(saltHex, "hex");
+  const expected = Buffer.from(hashHex, "hex");
+  if (salt.length === 0 || expected.length === 0) return false;
+  const candidate = scryptSync(raw, salt, SCRYPT_KEY_LEN);
+  return candidate.length === expected.length && timingSafeEqual2(candidate, expected);
+}
+
 // src/crypto/index.ts
 var CryptoError = class extends HazoError {
   constructor(message, code) {
@@ -110,7 +191,7 @@ async function encryptField(plaintext, opts) {
       "invalid_key"
     );
   }
-  const iv = randomBytes(IV_LEN);
+  const iv = randomBytes2(IV_LEN);
   const cipher = createCipheriv(ALG, key, iv, { authTagLength: TAG_LEN });
   if (opts.aad) cipher.setAAD(Buffer.from(opts.aad, "utf8"));
   const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
@@ -267,5 +348,11 @@ export {
   StaticKeyProvider,
   aadFor,
   decryptField,
-  encryptField
+  encryptField,
+  hashToken,
+  randomCode,
+  randomToken,
+  signHmac,
+  verifyHmac,
+  verifyToken
 };

package/dist/mask/index.d.ts

@@ -34,6 +34,32 @@ 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].
@@ -45,4 +71,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, mask_email, mask_phone, nullify, redact_pii, tokenize };
+export { BUILTIN_TRANSFORMS, type MaskTransformFn, drop, fake_name, hash, jitter_date, maskABN, maskTFN, mask_email, mask_phone, nullify, redact_pii, tokenize };

package/dist/mask/index.js

@@ -58,6 +58,18 @@ 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;
@@ -107,6 +119,8 @@ export {
   fake_name,
   hash,
   jitter_date,
+  maskABN,
+  maskTFN,
   mask_email,
   mask_phone,
   nullify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_secure",
-  "version": "1.3.0",
+  "version": "1.5.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",
@@ -76,12 +76,12 @@
     "wink-eng-lite-web-model": "^1.7.0"
   },
   "peerDependencies": {
-    "hazo_core": "^1.1.0",
-    "hazo_logs": "^2.0.3",
-    "hazo_connect": "^3.5.1",
-    "hazo_jobs": "^0.12.0",
-    "hazo_files": "^3.1.0",
-    "hazo_ui": "^3.5.0"
+    "hazo_core": "^1.2.1",
+    "hazo_logs": "^2.1.1",
+    "hazo_connect": "^3.9.2",
+    "hazo_jobs": "^0.15.0",
+    "hazo_files": "^3.1.1",
+    "hazo_ui": "^6.1.0"
   },
   "peerDependenciesMeta": {
     "hazo_logs": {
@@ -103,19 +103,19 @@
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^22.10.0",
-    "hazo_core": "^1.1.0",
-    "hazo_logs": "^2.0.3",
-    "hazo_connect": "^3.5.1",
-    "hazo_jobs": "^0.12.0",
-    "hazo_files": "^3.1.0",
-    "hazo_ui": "^3.5.0",
+    "hazo_core": "^1.2.1",
+    "hazo_logs": "^2.1.1",
+    "hazo_connect": "^3.9.2",
+    "hazo_jobs": "^0.15.0",
+    "hazo_files": "^3.1.1",
+    "hazo_ui": "^6.1.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.5",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
     "wink-nlp": "^2.3.1",
     "wink-eng-lite-web-model": "^1.7.0",
-    "zod": "^3.23.8"
+    "zod": "^4.1.12"
   },
   "author": "Pubs Abayasiri",
   "license": "MIT"