hazo_secure 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pubs Abayasiri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# hazo_secure
+
+Security & compliance primitives for Node.js / Next.js apps. Four independent subpath modules — import only the ones you need.
+
+| Subpath | Purpose |
+|---|---|
+| `hazo_secure/fetch` | SSRF-safe `safeFetch()` — domain allowlist, private-CIDR blocker, redirect controls |
+| `hazo_secure/ratelimit` | Sliding-window + token-bucket limiter with pluggable store (in-memory default, Redis adapter) |
+| `hazo_secure/crypto` | AES-256-GCM field-level encryption with key versioning and AAD support |
+| `hazo_secure/gdpr` | Exporter / anonymiser registry + lifecycle orchestrator. Uses `hazo_jobs` for async export, `hazo_files` for ZIP delivery |
+
+## Install
+
+```bash
+npm install hazo_secure
+```
+
+`hazo_logs` is a required peer dep. `hazo_jobs` and `hazo_files` are optional peers — only needed if you use `hazo_secure/gdpr`.
+
+## Quick start
+
+### SSRF-safe outbound fetch
+
+```ts
+import { safeFetch } from "hazo_secure/fetch";
+
+const res = await safeFetch("https://nominatim.openstreetmap.org/search", {
+  policy: {
+    allowedHosts: ["nominatim.openstreetmap.org"],
+    blockPrivateIps: true,
+    maxRedirects: 3,
+    timeoutMs: 5000,
+  },
+});
+```
+
+### Rate limit a Next.js route
+
+```ts
+import { checkRateLimit } from "hazo_secure/ratelimit";
+
+export async function POST(req: Request) {
+  const decision = await checkRateLimit(req, { windowMs: 60_000, max: 30 });
+  if (!decision.allowed) return new Response("Too Many Requests", { status: 429 });
+  // ...
+}
+```
+
+### Encrypt a PII field
+
+```ts
+import { encryptField, decryptField } from "hazo_secure/crypto";
+
+const stored = await encryptField(plaintext, { keys, aad: `user:${userId}` });
+const recovered = await decryptField(stored, { keys });
+```
+
+### Register GDPR exporters
+
+```ts
+import { createGdprRegistry } from "hazo_secure/gdpr";
+
+const gdpr = createGdprRegistry();
+
+gdpr.registerExporter({
+  domain: "persons",
+  async *export({ userId }) {
+    for (const row of await db.personsByUser(userId)) {
+      yield { filename: `persons/${row.id}.json`, content: JSON.stringify(row, null, 2) };
+    }
+  },
+});
+```
+
+## Design
+
+Each subpath is independent — no cross-imports between `/fetch`, `/ratelimit`, `/crypto`, `/gdpr`. The `gdpr` module *consumes* the others when a project wires them together, but the package itself doesn't entangle them.
+
+See `CLAUDE.md` and `AGENTS.md` for architecture details.
+
+## License
+
+MIT

package/dist/crypto/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Source of symmetric keys for `encryptField` / `decryptField`. The current
+ * key is used for encryption; `byId` resolves any key (current or rotated-out)
+ * so we can still decrypt fields written under a previous key id.
+ *
+ * Production implementations should source keys from a KMS — see
+ * `EnvKeyProvider` below for the env-var fallback the local dev / single-VPS
+ * path uses today.
+ */
+interface KeyProvider {
+    current(): Promise<{
+        keyId: string;
+        key: Uint8Array;
+    }>;
+    byId(keyId: string): Promise<Uint8Array>;
+}
+/**
+ * Envelope for an encrypted string. Stored verbatim in a JSONB column.
+ *
+ * - `v` is the envelope version — bumped if we change the algorithm or layout.
+ *   Decryption checks this and refuses unknown versions.
+ * - `keyId` lets the consumer rotate keys without re-encrypting historical
+ *   rows in bulk; the provider resolves the right key per-field.
+ * - `iv` is a 12-byte AES-GCM nonce (base64). MUST be unique per encryption
+ *   under the same key — `encryptField` generates this from a CSPRNG.
+ * - `ct` is the ciphertext (base64).
+ * - `tag` is the 16-byte GCM auth tag (base64). MUST verify on decrypt.
+ * - `aad` is the binding string (e.g. `app_health_data:<personId>:<field>`).
+ *   Optional but strongly recommended — without it, two ciphertexts for the
+ *   same plaintext under the same key are confusable, and worse, ciphertexts
+ *   can be moved between rows without detection.
+ */
+interface EncryptedField {
+    v: 1;
+    keyId: string;
+    iv: string;
+    ct: string;
+    tag: string;
+    aad?: string;
+}
+declare class CryptoError extends Error {
+    readonly code: "unsupported_version" | "key_not_found" | "decrypt_failed" | "aad_mismatch" | "invalid_key" | "missing_env_key" | "no_keys_loaded";
+    constructor(message: string, code: "unsupported_version" | "key_not_found" | "decrypt_failed" | "aad_mismatch" | "invalid_key" | "missing_env_key" | "no_keys_loaded");
+}
+/**
+ * Encrypt a UTF-8 string under the current key.
+ * Throws `CryptoError("invalid_key")` if the key length is wrong.
+ */
+declare function encryptField(plaintext: string, opts: {
+    keys: KeyProvider;
+    aad?: string;
+}): Promise<EncryptedField>;
+/**
+ * Decrypt a previously-encrypted field. Verifies the AAD matches what's on
+ * the envelope (defense-in-depth — the GCM tag already binds it, but failing
+ * loud here surfaces logic bugs at the call site).
+ */
+declare function decryptField(field: EncryptedField, opts: {
+    keys: KeyProvider;
+    aad?: string;
+}): Promise<string>;
+/**
+ * Env-var-backed `KeyProvider` for the local dev + single-VPS deployment
+ * pattern. Reads keys from env vars matching `<PREFIX>_<KEY_ID>`, each a
+ * base64-encoded 32-byte AES-256 key. The current key id comes from
+ * `<PREFIX>_CURRENT`.
+ *
+ * Example:
+ *   KINSTRIPE_HEALTH_KEY_CURRENT=v1
+ *   KINSTRIPE_HEALTH_KEY_v1=<base64 of 32 bytes>
+ *   KINSTRIPE_HEALTH_KEY_v2=<base64 of 32 bytes>   # ready for rotation
+ *
+ * Rotation: write rows under the new id, leave old ids in env so historical
+ * rows stay decryptable. A bulk re-encrypt job (future) walks rows and
+ * re-encrypts under the new id at leisure.
+ *
+ * Lazy initial load + memoised so the env-var lookup runs once per process.
+ */
+declare class EnvKeyProvider implements KeyProvider {
+    private readonly prefix;
+    private readonly cache;
+    constructor(prefix: string);
+    current(): Promise<{
+        keyId: string;
+        key: Uint8Array;
+    }>;
+    byId(keyId: string): Promise<Uint8Array>;
+}
+/**
+ * In-memory `KeyProvider` for tests + ephemeral one-shot encryption.
+ * Don't use in production — keys live in process memory only.
+ */
+declare class StaticKeyProvider implements KeyProvider {
+    private readonly currentKeyId;
+    private readonly keys;
+    constructor(currentKeyId: string, keys: Record<string, Uint8Array>);
+    current(): Promise<{
+        keyId: string;
+        key: Uint8Array;
+    }>;
+    byId(keyId: string): Promise<Uint8Array>;
+}
+/** Helper: build a `aad` string with a stable, parser-friendly shape.
+ *  Convention: `<table>:<entityId>:<field>` — collision-free across tables. */
+declare function aadFor(table: string, entityId: string, field: string): string;
+
+export { CryptoError, type EncryptedField, EnvKeyProvider, type KeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };

package/dist/crypto/index.js

@@ -0,0 +1,147 @@
+// src/crypto/index.ts
+import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+var CryptoError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CryptoError";
+  }
+  code;
+};
+var ALG = "aes-256-gcm";
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var KEY_LEN = 32;
+function toB64(buf) {
+  return Buffer.from(buf).toString("base64");
+}
+function fromB64(s) {
+  return Buffer.from(s, "base64");
+}
+async function encryptField(plaintext, opts) {
+  const { keyId, key } = await opts.keys.current();
+  if (key.byteLength !== KEY_LEN) {
+    throw new CryptoError(
+      `Key for ${keyId} is ${key.byteLength} bytes; AES-256-GCM needs ${KEY_LEN}.`,
+      "invalid_key"
+    );
+  }
+  const iv = randomBytes(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()]);
+  const tag = cipher.getAuthTag();
+  return {
+    v: 1,
+    keyId,
+    iv: toB64(iv),
+    ct: toB64(ct),
+    tag: toB64(tag),
+    ...opts.aad ? { aad: opts.aad } : {}
+  };
+}
+async function decryptField(field, opts) {
+  if (field.v !== 1) {
+    throw new CryptoError(`Unknown envelope version ${field.v}`, "unsupported_version");
+  }
+  if (opts.aad !== void 0 && field.aad !== void 0 && opts.aad !== field.aad) {
+    throw new CryptoError("AAD mismatch \u2014 refusing to decrypt", "aad_mismatch");
+  }
+  let key;
+  try {
+    key = await opts.keys.byId(field.keyId);
+  } catch (err) {
+    throw new CryptoError(
+      `Key not found: ${field.keyId} (${err instanceof Error ? err.message : String(err)})`,
+      "key_not_found"
+    );
+  }
+  const iv = fromB64(field.iv);
+  const ct = fromB64(field.ct);
+  const tag = fromB64(field.tag);
+  const decipher = createDecipheriv(ALG, key, iv, { authTagLength: TAG_LEN });
+  const aad = field.aad ?? opts.aad;
+  if (aad !== void 0) decipher.setAAD(Buffer.from(aad, "utf8"));
+  decipher.setAuthTag(tag);
+  try {
+    const out = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return out.toString("utf8");
+  } catch (err) {
+    throw new CryptoError(
+      `GCM auth tag verification failed (${err instanceof Error ? err.message : String(err)})`,
+      "decrypt_failed"
+    );
+  }
+}
+var EnvKeyProvider = class {
+  constructor(prefix) {
+    this.prefix = prefix;
+  }
+  prefix;
+  cache = /* @__PURE__ */ new Map();
+  async current() {
+    const currentVar = `${this.prefix}_CURRENT`;
+    const keyId = process.env[currentVar];
+    if (!keyId) {
+      throw new CryptoError(
+        `Missing ${currentVar} env var (expected current key id like "v1")`,
+        "missing_env_key"
+      );
+    }
+    const key = await this.byId(keyId);
+    return { keyId, key };
+  }
+  async byId(keyId) {
+    if (this.cache.has(keyId)) return this.cache.get(keyId);
+    const varName = `${this.prefix}_${keyId}`;
+    const raw = process.env[varName];
+    if (!raw) {
+      throw new CryptoError(`Missing ${varName} env var`, "key_not_found");
+    }
+    const buf = Buffer.from(raw, "base64");
+    if (buf.byteLength !== KEY_LEN) {
+      throw new CryptoError(
+        `${varName} decodes to ${buf.byteLength} bytes; AES-256-GCM needs ${KEY_LEN}`,
+        "invalid_key"
+      );
+    }
+    this.cache.set(keyId, buf);
+    return buf;
+  }
+};
+var StaticKeyProvider = class {
+  constructor(currentKeyId, keys) {
+    this.currentKeyId = currentKeyId;
+    this.keys = keys;
+  }
+  currentKeyId;
+  keys;
+  async current() {
+    const key = this.keys[this.currentKeyId];
+    if (!key) {
+      throw new CryptoError(
+        `Static provider has no key for current id ${this.currentKeyId}`,
+        "no_keys_loaded"
+      );
+    }
+    return { keyId: this.currentKeyId, key };
+  }
+  async byId(keyId) {
+    const key = this.keys[keyId];
+    if (!key) {
+      throw new CryptoError(`Static provider has no key for id ${keyId}`, "key_not_found");
+    }
+    return key;
+  }
+};
+function aadFor(table, entityId, field) {
+  return `${table}:${entityId}:${field}`;
+}
+export {
+  CryptoError,
+  EnvKeyProvider,
+  StaticKeyProvider,
+  aadFor,
+  decryptField,
+  encryptField
+};

package/dist/csrf/index.d.ts

@@ -0,0 +1,46 @@
+interface CsrfPolicy {
+    cookieName?: string;
+    headerName?: string;
+    tokenLength?: number;
+    /** Methods that require a verified token. Defaults to mutating verbs. */
+    protectedMethods?: readonly string[];
+    /** Cookie attributes. `secure` defaults to true in production. */
+    cookie?: {
+        path?: string;
+        domain?: string;
+        sameSite?: "lax" | "strict" | "none";
+        secure?: boolean;
+        maxAgeSeconds?: number;
+    };
+}
+type CsrfErrorCode = "csrf_cookie_missing" | "csrf_header_missing" | "csrf_mismatch" | "csrf_malformed";
+declare class CsrfError extends Error {
+    readonly code: CsrfErrorCode;
+    constructor(code: CsrfErrorCode, message: string);
+}
+/** Generate a fresh URL-safe random token of the configured length (in bytes;
+ *  output is base64url-encoded so the string is longer than the byte count). */
+declare function issueCsrfToken(policy?: CsrfPolicy): string;
+/** Build the Set-Cookie header value for the CSRF cookie. Caller appends to
+ *  the response. The cookie is intentionally NOT httpOnly — the client must
+ *  read it to echo into the request header (double-submit pattern). */
+declare function csrfCookieHeader(token: string, policy?: CsrfPolicy): string;
+interface VerifyCsrfResult {
+    ok: boolean;
+    code?: CsrfErrorCode;
+    cookieToken?: string;
+}
+/** Verify a request's CSRF token using the double-submit cookie pattern.
+ *  Reads cookie + header, requires both present and equal. Safe methods
+ *  (GET/HEAD/OPTIONS) pass automatically. */
+declare function verifyCsrf(req: Request, policy?: CsrfPolicy): VerifyCsrfResult;
+interface WithCsrfOptions extends CsrfPolicy {
+    onReject?: (req: Request, result: VerifyCsrfResult) => Response | Promise<Response>;
+    /** When true (default), GET responses that lack a CSRF cookie get a fresh
+     *  Set-Cookie appended so clients always have a token to echo. */
+    issueOnSafeMethods?: boolean;
+}
+type AnyRouteHandler = (...args: any[]) => Promise<Response>;
+declare function withCsrf<H extends AnyRouteHandler>(handler: H, opts?: WithCsrfOptions): H;
+
+export { CsrfError, type CsrfErrorCode, type CsrfPolicy, type VerifyCsrfResult, type WithCsrfOptions, csrfCookieHeader, issueCsrfToken, verifyCsrf, withCsrf };

package/dist/csrf/index.js

@@ -0,0 +1,116 @@
+// src/csrf/index.ts
+var DEFAULT_COOKIE_NAME = "hs_csrf";
+var DEFAULT_HEADER_NAME = "x-csrf-token";
+var DEFAULT_TOKEN_LENGTH = 32;
+var DEFAULT_PROTECTED = ["POST", "PUT", "PATCH", "DELETE"];
+var CsrfError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CsrfError";
+  }
+  code;
+};
+function resolved(policy) {
+  return {
+    cookieName: policy.cookieName ?? DEFAULT_COOKIE_NAME,
+    headerName: (policy.headerName ?? DEFAULT_HEADER_NAME).toLowerCase(),
+    tokenLength: policy.tokenLength ?? DEFAULT_TOKEN_LENGTH,
+    protectedMethods: policy.protectedMethods ?? DEFAULT_PROTECTED
+  };
+}
+function toBase64Url(bytes) {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  const b64 = typeof btoa === "function" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function issueCsrfToken(policy = {}) {
+  const { tokenLength } = resolved(policy);
+  const bytes = new Uint8Array(tokenLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return toBase64Url(bytes);
+}
+function csrfCookieHeader(token, policy = {}) {
+  const { cookieName } = resolved(policy);
+  const c = policy.cookie ?? {};
+  const parts = [`${cookieName}=${token}`];
+  parts.push(`Path=${c.path ?? "/"}`);
+  if (c.domain) parts.push(`Domain=${c.domain}`);
+  parts.push(`SameSite=${capitaliseFirst(c.sameSite ?? "lax")}`);
+  const secureDefault = process.env.NODE_ENV === "production";
+  if (c.secure ?? secureDefault) parts.push("Secure");
+  if (c.maxAgeSeconds != null) parts.push(`Max-Age=${c.maxAgeSeconds}`);
+  return parts.join("; ");
+}
+function capitaliseFirst(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+function parseCookieValue(cookieHeader, name) {
+  if (!cookieHeader) return null;
+  const parts = cookieHeader.split(";");
+  for (const part of parts) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq).trim();
+    if (k === name) return part.slice(eq + 1).trim();
+  }
+  return null;
+}
+function constantTimeEquals(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function verifyCsrf(req, policy = {}) {
+  const { cookieName, headerName, protectedMethods } = resolved(policy);
+  if (!protectedMethods.includes(req.method.toUpperCase())) {
+    return { ok: true };
+  }
+  const cookieToken = parseCookieValue(req.headers.get("cookie"), cookieName);
+  if (!cookieToken) return { ok: false, code: "csrf_cookie_missing" };
+  if (!/^[A-Za-z0-9_-]+$/.test(cookieToken)) return { ok: false, code: "csrf_malformed" };
+  const headerToken = req.headers.get(headerName);
+  if (!headerToken) return { ok: false, code: "csrf_header_missing", cookieToken };
+  if (!constantTimeEquals(cookieToken, headerToken)) {
+    return { ok: false, code: "csrf_mismatch", cookieToken };
+  }
+  return { ok: true, cookieToken };
+}
+function withCsrf(handler, opts = {}) {
+  const { cookieName, protectedMethods } = resolved(opts);
+  const issueOnSafe = opts.issueOnSafeMethods ?? true;
+  const fn = async (...args) => {
+    const req = args[0];
+    const method = req.method.toUpperCase();
+    if (protectedMethods.includes(method)) {
+      const result = verifyCsrf(req, opts);
+      if (!result.ok) {
+        if (opts.onReject) return await opts.onReject(req, result);
+        return new Response("Forbidden", {
+          status: 403,
+          headers: { "X-CSRF-Reject-Reason": result.code ?? "csrf_unknown" }
+        });
+      }
+    }
+    const res = await handler(...args);
+    if (issueOnSafe && !protectedMethods.includes(method)) {
+      const hasCookie = parseCookieValue(req.headers.get("cookie"), cookieName);
+      if (!hasCookie) {
+        res.headers.append("Set-Cookie", csrfCookieHeader(issueCsrfToken(opts), opts));
+      }
+    }
+    return res;
+  };
+  return fn;
+}
+export {
+  CsrfError,
+  csrfCookieHeader,
+  issueCsrfToken,
+  verifyCsrf,
+  withCsrf
+};

package/dist/fetch/index.d.ts

@@ -0,0 +1,24 @@
+interface SafeFetchPolicy {
+    allowedHosts?: readonly string[];
+    allowedHostPatterns?: readonly RegExp[];
+    blockPrivateIps?: boolean;
+    maxRedirects?: number;
+    timeoutMs?: number;
+    allowedProtocols?: readonly ("http:" | "https:")[];
+}
+interface SafeFetchDeps {
+    dnsLookup?: (host: string) => Promise<readonly string[]>;
+    fetchImpl?: typeof fetch;
+}
+interface SafeFetchOptions extends Omit<RequestInit, "redirect"> {
+    policy: SafeFetchPolicy;
+    deps?: SafeFetchDeps;
+}
+type SafeFetchErrorCode = "invalid_url" | "protocol_not_allowed" | "host_not_allowed" | "dns_failed" | "private_ip_blocked" | "redirect_limit" | "redirect_loop" | "timeout";
+declare class SafeFetchError extends Error {
+    readonly code: SafeFetchErrorCode;
+    constructor(code: SafeFetchErrorCode, message: string);
+}
+declare function safeFetch(input: string | URL, options: SafeFetchOptions): Promise<Response>;
+
+export { type SafeFetchDeps, SafeFetchError, type SafeFetchErrorCode, type SafeFetchOptions, type SafeFetchPolicy, safeFetch };

package/dist/fetch/index.js

@@ -0,0 +1,189 @@
+// src/fetch/index.ts
+import { lookup } from "dns/promises";
+
+// src/fetch/cidr.ts
+import { isIP } from "net";
+var IPV4_PRIVATE_RANGES = [
+  [0, 8],
+  // 0.0.0.0/8 — "this network"
+  [167772160, 8],
+  // 10.0.0.0/8 — RFC1918
+  [2130706432, 8],
+  // 127.0.0.0/8 — loopback
+  [2851995648, 16],
+  // 169.254.0.0/16 — link-local incl. 169.254.169.254 metadata
+  [2886729728, 12],
+  // 172.16.0.0/12 — RFC1918
+  [3232235520, 16],
+  // 192.168.0.0/16 — RFC1918
+  [1681915904, 10],
+  // 100.64.0.0/10 — CGNAT
+  [3758096384, 4],
+  // 224.0.0.0/4 — multicast
+  [4026531840, 4]
+  // 240.0.0.0/4 — reserved (incl 255.255.255.255 broadcast)
+];
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let n = 0;
+  for (const part of parts) {
+    const octet = Number(part);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+    n = n * 256 + octet >>> 0;
+  }
+  return n;
+}
+function ipv4InRange(ipInt, baseInt, prefix) {
+  const mask = prefix === 0 ? 0 : 4294967295 << 32 - prefix >>> 0;
+  return (ipInt & mask) === (baseInt & mask);
+}
+function isPrivateIpv4(ip) {
+  const n = ipv4ToInt(ip);
+  if (n === null) return false;
+  return IPV4_PRIVATE_RANGES.some(([base, prefix]) => ipv4InRange(n, base, prefix));
+}
+function isPrivateIpv6(ip) {
+  const normalised = ip.toLowerCase();
+  if (normalised === "::1") return true;
+  if (normalised === "::") return true;
+  if (normalised.startsWith("fe80:") || normalised.startsWith("fe80::")) return true;
+  if (normalised.startsWith("fc") || normalised.startsWith("fd")) {
+    const firstByte = parseInt(normalised.slice(0, 2), 16);
+    if ((firstByte & 254) === 252) return true;
+  }
+  const mapped = normalised.match(/^::ffff:([\d.]+)$/);
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  const mapped2 = normalised.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mapped2) {
+    const high = parseInt(mapped2[1], 16);
+    const low = parseInt(mapped2[2], 16);
+    const ipv4 = `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+    return isPrivateIpv4(ipv4);
+  }
+  return false;
+}
+function isPrivateIp(ip) {
+  const family = isIP(ip);
+  if (family === 4) return isPrivateIpv4(ip);
+  if (family === 6) return isPrivateIpv6(ip);
+  return false;
+}
+
+// src/fetch/index.ts
+var SafeFetchError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SafeFetchError";
+  }
+  code;
+};
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_REDIRECTS = 3;
+var DEFAULT_PROTOCOLS = ["https:", "http:"];
+async function defaultDnsLookup(host) {
+  const records = await lookup(host, { all: true, verbatim: true });
+  return records.map((r) => r.address);
+}
+function hostAllowed(host, policy) {
+  const hosts = policy.allowedHosts;
+  const patterns = policy.allowedHostPatterns;
+  if ((hosts === void 0 || hosts.length === 0) && (patterns === void 0 || patterns.length === 0)) {
+    return true;
+  }
+  if (hosts?.some((h) => h.toLowerCase() === host.toLowerCase())) return true;
+  if (patterns?.some((p) => p.test(host))) return true;
+  return false;
+}
+async function validateUrl(url, policy, deps) {
+  const protocols = policy.allowedProtocols ?? DEFAULT_PROTOCOLS;
+  if (!protocols.includes(url.protocol)) {
+    throw new SafeFetchError("protocol_not_allowed", `Protocol ${url.protocol} not allowed`);
+  }
+  if (!hostAllowed(url.hostname, policy)) {
+    throw new SafeFetchError("host_not_allowed", `Host ${url.hostname} not allowed`);
+  }
+  if (policy.blockPrivateIps !== false) {
+    let addresses;
+    try {
+      addresses = await (deps.dnsLookup ?? defaultDnsLookup)(url.hostname);
+    } catch (err) {
+      throw new SafeFetchError(
+        "dns_failed",
+        `DNS lookup for ${url.hostname} failed: ${err.message}`
+      );
+    }
+    if (addresses.length === 0) {
+      throw new SafeFetchError("dns_failed", `DNS lookup for ${url.hostname} returned no records`);
+    }
+    for (const addr of addresses) {
+      if (isPrivateIp(addr)) {
+        throw new SafeFetchError(
+          "private_ip_blocked",
+          `Host ${url.hostname} resolves to private IP ${addr}`
+        );
+      }
+    }
+  }
+}
+async function safeFetch(input, options) {
+  const { policy, deps = {}, ...init } = options;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const maxRedirects = policy.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const timeoutMs = policy.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let currentUrl;
+  try {
+    currentUrl = input instanceof URL ? input : new URL(input);
+  } catch {
+    throw new SafeFetchError("invalid_url", `Could not parse URL: ${String(input)}`);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  let hopsRemaining = maxRedirects;
+  while (true) {
+    await validateUrl(currentUrl, policy, deps);
+    const urlKey = currentUrl.toString();
+    if (visited.has(urlKey)) {
+      throw new SafeFetchError("redirect_loop", `Redirect loop detected at ${urlKey}`);
+    }
+    visited.add(urlKey);
+    const controller = new AbortController();
+    const externalSignal = init.signal;
+    if (externalSignal) {
+      if (externalSignal.aborted) controller.abort(externalSignal.reason);
+      else externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason));
+    }
+    const timer = setTimeout(() => controller.abort(new SafeFetchError("timeout", `Request to ${urlKey} timed out after ${timeoutMs}ms`)), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl(currentUrl, {
+        ...init,
+        signal: controller.signal,
+        redirect: "manual"
+      });
+    } catch (err) {
+      if (err.name === "AbortError" || err.code === "ABORT_ERR") {
+        const reason = controller.signal.reason;
+        if (reason instanceof SafeFetchError) throw reason;
+        throw new SafeFetchError("timeout", `Request to ${urlKey} aborted`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (res.status >= 300 && res.status < 400 && res.headers.get("location")) {
+      if (hopsRemaining <= 0) {
+        throw new SafeFetchError("redirect_limit", `Exceeded ${maxRedirects} redirects`);
+      }
+      hopsRemaining--;
+      const next = new URL(res.headers.get("location"), currentUrl);
+      currentUrl = next;
+      continue;
+    }
+    return res;
+  }
+}
+export {
+  SafeFetchError,
+  safeFetch
+};

package/dist/gdpr/index.d.ts

@@ -0,0 +1,24 @@
+interface ExporterContext {
+    userId: string;
+    locale?: string;
+}
+interface DomainExporter {
+    domain: string;
+    export(ctx: ExporterContext): AsyncIterable<{
+        filename: string;
+        content: Uint8Array | string;
+    }>;
+}
+interface DomainAnonymiser {
+    domain: string;
+    anonymise(ctx: ExporterContext): Promise<void>;
+}
+interface GdprRegistry {
+    registerExporter(exporter: DomainExporter): void;
+    registerAnonymiser(anonymiser: DomainAnonymiser): void;
+    listExporters(): readonly DomainExporter[];
+    listAnonymisers(): readonly DomainAnonymiser[];
+}
+declare function createGdprRegistry(): GdprRegistry;
+
+export { type DomainAnonymiser, type DomainExporter, type ExporterContext, type GdprRegistry, createGdprRegistry };

package/dist/gdpr/index.js

@@ -0,0 +1,22 @@
+// src/gdpr/index.ts
+function createGdprRegistry() {
+  const exporters = [];
+  const anonymisers = [];
+  return {
+    registerExporter(e) {
+      exporters.push(e);
+    },
+    registerAnonymiser(a) {
+      anonymisers.push(a);
+    },
+    listExporters() {
+      return exporters;
+    },
+    listAnonymisers() {
+      return anonymisers;
+    }
+  };
+}
+export {
+  createGdprRegistry
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+declare const NoopLogger: Logger;
+declare const PACKAGE_VERSION = "0.1.0";
+
+export { type Logger, NoopLogger, PACKAGE_VERSION };

package/dist/index.js

@@ -0,0 +1,16 @@
+// src/index.ts
+var NoopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+var PACKAGE_VERSION = "0.1.0";
+export {
+  NoopLogger,
+  PACKAGE_VERSION
+};

package/dist/ratelimit/index.d.ts

@@ -0,0 +1,54 @@
+interface MemoryStoreOptions {
+    now?: () => number;
+    sweepIntervalMs?: number;
+}
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly map;
+    private readonly now;
+    private sweepTimer;
+    constructor(opts?: MemoryStoreOptions);
+    get(key: string): Promise<RateLimitState | null>;
+    increment(key: string, windowMs: number): Promise<RateLimitState>;
+    reset(key: string): Promise<void>;
+    size(): number;
+    sweep(): void;
+    stop(): void;
+}
+declare function getDefaultMemoryStore(): MemoryRateLimitStore;
+
+interface RateLimitState {
+    count: number;
+    resetAt: number;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfterSeconds: number;
+}
+interface RateLimitStore {
+    get(key: string): Promise<RateLimitState | null>;
+    increment(key: string, windowMs: number): Promise<RateLimitState>;
+    reset(key: string): Promise<void>;
+}
+interface RateLimiterOptions {
+    store?: RateLimitStore;
+    windowMs: number;
+    max: number;
+    keyResolver?: (req: Request) => string;
+    now?: () => number;
+}
+interface RateLimiter {
+    check(req: Request): Promise<RateLimitDecision>;
+    checkKey(key: string): Promise<RateLimitDecision>;
+}
+declare function defaultKeyResolver(req: Request): string;
+declare function createRateLimiter(opts: RateLimiterOptions): RateLimiter;
+declare function checkRateLimit(req: Request, opts: RateLimiterOptions): Promise<RateLimitDecision>;
+interface WithRateLimitOptions extends RateLimiterOptions {
+    onLimit?: (req: Request, decision: RateLimitDecision) => Response | Promise<Response>;
+}
+type AnyRouteHandler = (...args: any[]) => Promise<Response>;
+declare function withRateLimit<H extends AnyRouteHandler>(handler: H, opts: WithRateLimitOptions): H;
+
+export { MemoryRateLimitStore, type RateLimitDecision, type RateLimitState, type RateLimitStore, type RateLimiter, type RateLimiterOptions, type WithRateLimitOptions, checkRateLimit, createRateLimiter, defaultKeyResolver, getDefaultMemoryStore, withRateLimit };

package/dist/ratelimit/index.js

@@ -0,0 +1,122 @@
+// src/ratelimit/store-memory.ts
+var MemoryRateLimitStore = class {
+  map = /* @__PURE__ */ new Map();
+  now;
+  sweepTimer = null;
+  constructor(opts = {}) {
+    this.now = opts.now ?? Date.now;
+    const sweepMs = opts.sweepIntervalMs ?? 6e4;
+    if (sweepMs > 0 && typeof setInterval === "function") {
+      this.sweepTimer = setInterval(() => this.sweep(), sweepMs);
+      const t = this.sweepTimer;
+      t.unref?.();
+    }
+  }
+  async get(key) {
+    const e = this.map.get(key);
+    if (!e) return null;
+    if (e.expiresAt <= this.now()) {
+      this.map.delete(key);
+      return null;
+    }
+    return { ...e.state };
+  }
+  async increment(key, windowMs) {
+    const t = this.now();
+    const existing = this.map.get(key);
+    if (!existing || existing.expiresAt <= t) {
+      const state = { count: 1, resetAt: t + windowMs };
+      this.map.set(key, { state, expiresAt: state.resetAt });
+      return { ...state };
+    }
+    existing.state.count += 1;
+    return { ...existing.state };
+  }
+  async reset(key) {
+    this.map.delete(key);
+  }
+  size() {
+    return this.map.size;
+  }
+  sweep() {
+    const t = this.now();
+    for (const [k, v] of this.map) {
+      if (v.expiresAt <= t) this.map.delete(k);
+    }
+  }
+  stop() {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+};
+var defaultStore = null;
+function getDefaultMemoryStore() {
+  if (!defaultStore) defaultStore = new MemoryRateLimitStore();
+  return defaultStore;
+}
+
+// src/ratelimit/index.ts
+function defaultKeyResolver(req) {
+  const headers = req.headers;
+  const xff = headers.get("x-forwarded-for");
+  if (xff) return xff.split(",")[0].trim();
+  const xri = headers.get("x-real-ip");
+  if (xri) return xri.trim();
+  const cf = headers.get("cf-connecting-ip");
+  if (cf) return cf.trim();
+  return "unknown";
+}
+function createRateLimiter(opts) {
+  const store = opts.store ?? getDefaultMemoryStore();
+  const keyResolver = opts.keyResolver ?? defaultKeyResolver;
+  const now = opts.now ?? Date.now;
+  async function checkKey(key) {
+    const state = await store.increment(key, opts.windowMs);
+    const allowed = state.count <= opts.max;
+    const remaining = Math.max(0, opts.max - state.count);
+    const retryAfterSeconds = Math.max(0, Math.ceil((state.resetAt - now()) / 1e3));
+    return { allowed, remaining, resetAt: state.resetAt, retryAfterSeconds };
+  }
+  return {
+    check: (req) => checkKey(keyResolver(req)),
+    checkKey
+  };
+}
+async function checkRateLimit(req, opts) {
+  return createRateLimiter(opts).check(req);
+}
+function withRateLimit(handler, opts) {
+  const limiter = createRateLimiter(opts);
+  const fn = async (...args) => {
+    const req = args[0];
+    const decision = await limiter.check(req);
+    if (!decision.allowed) {
+      if (opts.onLimit) return await opts.onLimit(req, decision);
+      return new Response("Too Many Requests", {
+        status: 429,
+        headers: {
+          "Retry-After": String(decision.retryAfterSeconds),
+          "X-RateLimit-Limit": String(opts.max),
+          "X-RateLimit-Remaining": "0",
+          "X-RateLimit-Reset": String(decision.resetAt)
+        }
+      });
+    }
+    const res = await handler(...args);
+    res.headers.set("X-RateLimit-Limit", String(opts.max));
+    res.headers.set("X-RateLimit-Remaining", String(decision.remaining));
+    res.headers.set("X-RateLimit-Reset", String(decision.resetAt));
+    return res;
+  };
+  return fn;
+}
+export {
+  MemoryRateLimitStore,
+  checkRateLimit,
+  createRateLimiter,
+  defaultKeyResolver,
+  getDefaultMemoryStore,
+  withRateLimit
+};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "hazo_secure",
+  "version": "0.5.0",
+  "description": "Security & compliance primitives — SSRF-safe fetch, rate limiting, field-level encryption, GDPR orchestration. Four subpath modules, pick the ones you need.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch/index.d.ts",
+      "import": "./dist/fetch/index.js",
+      "default": "./dist/fetch/index.js"
+    },
+    "./ratelimit": {
+      "types": "./dist/ratelimit/index.d.ts",
+      "import": "./dist/ratelimit/index.js",
+      "default": "./dist/ratelimit/index.js"
+    },
+    "./crypto": {
+      "types": "./dist/crypto/index.d.ts",
+      "import": "./dist/crypto/index.js",
+      "default": "./dist/crypto/index.js"
+    },
+    "./gdpr": {
+      "types": "./dist/gdpr/index.d.ts",
+      "import": "./dist/gdpr/index.js",
+      "default": "./dist/gdpr/index.js"
+    },
+    "./csrf": {
+      "types": "./dist/csrf/index.d.ts",
+      "import": "./dist/csrf/index.js",
+      "default": "./dist/csrf/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "dev:test-app": "npm run build && cd test-app && npm run dev",
+    "build:test-app": "npm run build && cd test-app && npm run build",
+    "install:test-app": "cd test-app && npm install",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "hazo_logs": "^1.1.0",
+    "hazo_jobs": "^0.7.0",
+    "hazo_files": "^1.4.7"
+  },
+  "peerDependenciesMeta": {
+    "hazo_jobs": { "optional": true },
+    "hazo_files": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Pubs Abayasiri",
+  "license": "MIT"
+}