hazo_secure 1.0.1 → 1.3.0

package/dist/fetch/index.d.ts

@@ -1,8 +1,13 @@
+import { HazoError } from 'hazo_core';
 import { Agent } from 'undici';
 
 /**
- * Validates a resolved IP at connect time. Throws if private/reserved.
- * Exported so it can be unit-tested directly.
+ * Validates a resolved IP at connect time. Throws `SafeFetchError("private_ip_blocked")`
+ * if private/reserved. Exported so it can be unit-tested directly.
+ *
+ * Carries the legacy `SSRF_PRIVATE_IP` ErrnoException-style code on the error
+ * for older consumers that grepped for it. New code should branch on the
+ * SafeFetchError discriminator instead.
  */
 declare function validateConnectIp(ip: string): void;
 /**
@@ -31,7 +36,13 @@ interface SafeFetchOptions extends Omit<RequestInit, "redirect"> {
     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 {
+/**
+ * Typed error raised by `safeFetch`. Extends `HazoError` so it participates
+ * in the workspace's correlation-ID auto-attach + envelope JSON shape, while
+ * preserving the legacy `(code, message)` constructor + `err.code` short
+ * discriminator that 1.0.x consumers already check.
+ */
+declare class SafeFetchError extends HazoError {
     readonly code: SafeFetchErrorCode;
     constructor(code: SafeFetchErrorCode, message: string);
 }

package/dist/fetch/index.js

@@ -1,6 +1,7 @@
 // src/fetch/index.ts
 import { lookup as lookup2 } from "dns/promises";
 import { fetch as undiciFetch } from "undici";
+import { HazoError, REQUEST_ID_HEADER, getCorrelationId } from "hazo_core";
 
 // src/fetch/cidr.ts
 import { isIP } from "net";
@@ -76,10 +77,12 @@ import { Agent } from "undici";
 import * as dns from "dns";
 function validateConnectIp(ip) {
   if (isPrivateIp(ip)) {
-    const err = new Error(
+    const err = new SafeFetchError(
+      "private_ip_blocked",
       `SSRF: resolved IP ${ip} is a private/reserved address \u2014 blocked at connect time`
     );
-    err.code = "SSRF_PRIVATE_IP";
+    err.code = "private_ip_blocked";
+    err.ssrfCode = "SSRF_PRIVATE_IP";
     throw err;
   }
 }
@@ -103,13 +106,28 @@ function createSecureDispatcher() {
 
 // src/fetch/index.ts
 var secureDispatcher = createSecureDispatcher();
-var SafeFetchError = class extends Error {
+var SAFE_FETCH_STATUS_MAP = {
+  invalid_url: { httpStatus: 400, retryable: false },
+  protocol_not_allowed: { httpStatus: 400, retryable: false },
+  host_not_allowed: { httpStatus: 403, retryable: false },
+  dns_failed: { httpStatus: 502, retryable: true },
+  private_ip_blocked: { httpStatus: 403, retryable: false },
+  redirect_limit: { httpStatus: 502, retryable: false },
+  redirect_loop: { httpStatus: 502, retryable: false },
+  timeout: { httpStatus: 504, retryable: true }
+};
+var SafeFetchError = class extends HazoError {
   constructor(code, message) {
-    super(message);
-    this.code = code;
+    const { httpStatus, retryable } = SAFE_FETCH_STATUS_MAP[code];
+    super({
+      code,
+      pkg: "hazo_secure",
+      message,
+      httpStatus,
+      retryable
+    });
     this.name = "SafeFetchError";
   }
-  code;
 };
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_REDIRECTS = 3;
@@ -171,6 +189,14 @@ async function safeFetch(input, options) {
   } catch {
     throw new SafeFetchError("invalid_url", `Could not parse URL: ${String(input)}`);
   }
+  const correlationId = getCorrelationId();
+  if (correlationId) {
+    const existingHeaders = new Headers(init.headers);
+    if (!existingHeaders.has(REQUEST_ID_HEADER)) {
+      existingHeaders.set(REQUEST_ID_HEADER, correlationId);
+      init.headers = existingHeaders;
+    }
+  }
   const visited = /* @__PURE__ */ new Set();
   let hopsRemaining = maxRedirects;
   while (true) {

package/dist/gdpr/index.d.ts

@@ -1,3 +1,5 @@
+import { HazoError } from 'hazo_core';
+
 interface ExporterContext {
     userId: string;
     locale?: string;
@@ -43,9 +45,16 @@ interface GdprRegistryOptions {
      */
     auditIntent?: AuditIntentFn;
 }
-declare class GdprRegistryError extends Error {
-    readonly code: 'incomplete_registry';
-    constructor(message: string, code: 'incomplete_registry');
+type GdprRegistryErrorCode = 'incomplete_registry';
+/**
+ * Typed error raised by `/gdpr`. Extends `HazoError` so registry-incomplete
+ * gaps surface through the workspace's correlation-ID + envelope shape, while
+ * preserving the legacy `(message, code)` constructor + `err.code` short
+ * discriminator that 1.0.x consumers already check.
+ */
+declare class GdprRegistryError extends HazoError {
+    readonly code: GdprRegistryErrorCode;
+    constructor(message: string, code: GdprRegistryErrorCode);
 }
 interface GdprRegistry {
     registerExporter(exporter: DomainExporter): void;
@@ -59,4 +68,4 @@ interface GdprRegistry {
 }
 declare function createGdprRegistry(opts?: GdprRegistryOptions): GdprRegistry;
 
-export { type AuditIntentFn, type DomainAnonymiser, type DomainExporter, type DryRunExportResult, type ExporterContext, type GdprRegistry, GdprRegistryError, type GdprRegistryOptions, type UserExportResult, type ValidateRegistryOptions, createGdprRegistry };
+export { type AuditIntentFn, type DomainAnonymiser, type DomainExporter, type DryRunExportResult, type ExporterContext, type GdprRegistry, GdprRegistryError, type GdprRegistryErrorCode, type GdprRegistryOptions, type UserExportResult, type ValidateRegistryOptions, createGdprRegistry };

package/dist/gdpr/index.js

@@ -1,11 +1,16 @@
 // src/gdpr/index.ts
-var GdprRegistryError = class extends Error {
+import { HazoError } from "hazo_core";
+var GdprRegistryError = class extends HazoError {
   constructor(message, code) {
-    super(message);
-    this.code = code;
+    super({
+      code,
+      pkg: "hazo_secure",
+      message,
+      httpStatus: 500,
+      retryable: false
+    });
     this.name = "GdprRegistryError";
   }
-  code;
 };
 function createGdprRegistry(opts = {}) {
   const exporters = [];

package/dist/index.d.ts

@@ -1,10 +1,43 @@
+/**
+ * Logger utility for hazo_secure.
+ *
+ * Default: delegates to hazo_core's createLogger('hazo_secure'), which
+ * auto-injects correlationId, env, and writes structured JSON via hazo_logs.
+ * Consumers can still override with set_logger() — useful for tests, or for
+ * apps that want to route hazo_secure logs through their own sink.
+ */
 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;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
 }
-declare const NoopLogger: Logger;
-declare const PACKAGE_VERSION = "0.1.0";
+/**
+ * Set the logger instance used throughout hazo_secure.
+ * Pass `undefined` to reset to the hazo_core default.
+ */
+declare function set_logger(logger: Logger | undefined): void;
+/**
+ * Get the current logger instance — defaults to hazo_core's createLogger
+ * on first access if no consumer override has been set.
+ */
+declare function get_logger(): Logger;
+/**
+ * Re-exported for backwards compatibility with hazo_secure < 1.1.0, which
+ * shipped a `NoopLogger` constant for consumers that wanted to silence
+ * package logs. Prefer `set_logger(noop_logger)` going forward.
+ */
+declare const noop_logger: Logger;
 
-export { type Logger, NoopLogger, PACKAGE_VERSION };
+/**
+ * Root entry — shared types only. Functional surface lives in the subpath
+ * modules (`hazo_secure/fetch`, `/ratelimit`, `/crypto`, `/gdpr`, `/csrf`).
+ *
+ * Logger helpers re-exported here so consumers can override the in-package
+ * logger without reaching into a subpath: `import { set_logger } from
+ * 'hazo_secure'`.
+ */
+
+declare const PACKAGE_VERSION = "1.1.0";
+
+export { type Logger, noop_logger as NoopLogger, PACKAGE_VERSION, get_logger, noop_logger, set_logger };

package/dist/index.js

@@ -1,16 +1,45 @@
-// src/index.ts
-var NoopLogger = {
-  debug() {
+// src/utils/logger.ts
+import { createLogger } from "hazo_core";
+var console_logger = {
+  info: (m, d) => d ? console.log(`[hazo_secure] ${m}`, d) : console.log(`[hazo_secure] ${m}`),
+  debug: (m, d) => d ? console.debug(`[hazo_secure] ${m}`, d) : console.debug(`[hazo_secure] ${m}`),
+  warn: (m, d) => d ? console.warn(`[hazo_secure] ${m}`, d) : console.warn(`[hazo_secure] ${m}`),
+  error: (m, d) => d ? console.error(`[hazo_secure] ${m}`, d) : console.error(`[hazo_secure] ${m}`)
+};
+function build_default_logger() {
+  try {
+    return createLogger("hazo_secure");
+  } catch {
+    return console_logger;
+  }
+}
+var current_logger = null;
+function set_logger(logger) {
+  current_logger = logger ?? null;
+}
+function get_logger() {
+  if (!current_logger) {
+    current_logger = build_default_logger();
+  }
+  return current_logger;
+}
+var noop_logger = {
+  debug: () => {
   },
-  info() {
+  info: () => {
   },
-  warn() {
+  warn: () => {
   },
-  error() {
+  error: () => {
   }
 };
-var PACKAGE_VERSION = "0.1.0";
+
+// src/index.ts
+var PACKAGE_VERSION = "1.1.0";
 export {
-  NoopLogger,
-  PACKAGE_VERSION
+  noop_logger as NoopLogger,
+  PACKAGE_VERSION,
+  get_logger,
+  noop_logger,
+  set_logger
 };

package/dist/mask/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * mask_email — replace with deterministic masked email.
+ * alice@example.com → a3f9b12c1d2e@masked.example
+ * Same source → same masked value (FK survival).
+ */
+declare function mask_email(value: unknown, _col: string, maskKey: string): unknown;
+/**
+ * mask_phone — replace with deterministic masked phone.
+ * Preserves leading + and length pattern. +1-555-0001 → +1-XXX-a3f9b1
+ */
+declare function mask_phone(value: unknown, _col: string, maskKey: string): unknown;
+declare function fake_name(value: unknown, _col: string, maskKey: string): unknown;
+/**
+ * jitter_date — add a deterministic date offset (±0–180 days) to a date string.
+ * Preserves approximate era; different source values → different offsets.
+ */
+declare function jitter_date(value: unknown, _col: string, maskKey: string): unknown;
+/**
+ * hash — replace with HMAC-SHA256 hex hash of value.
+ * Fully opaque; same source → same hash.
+ */
+declare function hash(value: unknown, col: string, maskKey: string): unknown;
+/**
+ * tokenize — replace with a stable short token (FK-safe).
+ * tok_<12 hex chars> — same source → same token.
+ */
+declare function tokenize(value: unknown, col: string, maskKey: string): unknown;
+/**
+ * drop — always returns null (secret dropped, not masked).
+ * Used for passwords, tokens, etc.
+ */
+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;
+/**
+ * redact_pii — NER-based PII redaction (wink-nlp lite model).
+ * Detects named entities (dates, cardinals, etc.) and replaces them with [REDACTED_TYPE].
+ * Deterministic: same input + same model → same output.
+ * maskKey is accepted but not used (redaction is model-driven, not key-driven).
+ */
+declare function redact_pii(value: unknown, _col: string, _maskKey: string): unknown;
+/** Registry of all built-in transforms */
+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 };

package/dist/mask/index.js

@@ -0,0 +1,115 @@
+// src/mask/index.ts
+import { createHmac } from "crypto";
+import { createRequire } from "module";
+function hmacHex(value, maskKey, context) {
+  return createHmac("sha256", maskKey).update(`${context}:${value}`).digest("hex");
+}
+function hmacToken(value, maskKey, context) {
+  return hmacHex(value, maskKey, context).slice(0, 12);
+}
+function mask_email(value, _col, maskKey) {
+  if (value === null || value === void 0) return value;
+  const str = String(value);
+  const atIdx = str.indexOf("@");
+  const domain = atIdx >= 0 ? str.slice(atIdx + 1) : "example.com";
+  const token = hmacToken(str, maskKey, "email");
+  return `${token}@masked.${domain}`;
+}
+function mask_phone(value, _col, maskKey) {
+  if (value === null || value === void 0) return value;
+  const str = String(value);
+  const token = hmacToken(str, maskKey, "phone").slice(0, 6);
+  const hasPlus = str.startsWith("+");
+  const digits = str.replace(/[^\d]/g, "");
+  const prefix = digits.length > 4 ? digits.slice(0, 2) : "00";
+  return `${hasPlus ? "+" : ""}${prefix}-XXX-${token}`;
+}
+var FIRST_NAMES = ["Alex", "Blake", "Casey", "Dana", "Ellis", "Finley", "Gray", "Harper", "Indigo", "Jordan"];
+var LAST_NAMES = ["Smith", "Jones", "Williams", "Brown", "Davis", "Miller", "Wilson", "Moore", "Taylor", "Anderson"];
+function fake_name(value, _col, maskKey) {
+  if (value === null || value === void 0) return value;
+  const str = String(value);
+  const h = hmacHex(str, maskKey, "name");
+  const firstIdx = parseInt(h.slice(0, 2), 16) % FIRST_NAMES.length;
+  const lastIdx = parseInt(h.slice(2, 4), 16) % LAST_NAMES.length;
+  return `${FIRST_NAMES[firstIdx]} ${LAST_NAMES[lastIdx]}`;
+}
+function jitter_date(value, _col, maskKey) {
+  if (value === null || value === void 0) return value;
+  const str = String(value);
+  const h = hmacHex(str, maskKey, "date");
+  const jitterDays = parseInt(h.slice(0, 4), 16) % 361 - 180;
+  const date = new Date(str);
+  if (isNaN(date.getTime())) return value;
+  date.setDate(date.getDate() + jitterDays);
+  return date.toISOString().slice(0, 10);
+}
+function hash(value, col, maskKey) {
+  if (value === null || value === void 0) return value;
+  return hmacHex(String(value), maskKey, col);
+}
+function tokenize(value, col, maskKey) {
+  if (value === null || value === void 0) return value;
+  return `tok_${hmacToken(String(value), maskKey, col)}`;
+}
+function drop(_value, _col, _maskKey) {
+  return null;
+}
+function nullify(_value, _col, _maskKey) {
+  return null;
+}
+var _esmReq = createRequire(import.meta.url);
+var _nlpInstance = null;
+var _nlpIts = null;
+function getNlp() {
+  if (_nlpInstance) return { nlp: _nlpInstance, its: _nlpIts };
+  try {
+    const winkNLP = _esmReq("wink-nlp");
+    const model = _esmReq("wink-eng-lite-web-model");
+    const nlp = winkNLP(model, ["ner"]);
+    _nlpInstance = nlp;
+    _nlpIts = nlp.its;
+    return { nlp, its: nlp.its };
+  } catch {
+    return null;
+  }
+}
+function redact_pii(value, _col, _maskKey) {
+  if (value === null || value === void 0) return value;
+  const text = String(value);
+  const ctx = getNlp();
+  if (!ctx) return value;
+  const doc = ctx.nlp.readDoc(text);
+  const replacements = [];
+  doc.entities().each((e) => {
+    replacements.push({ text: e.out(), type: e.out(ctx.its.type) });
+  });
+  let result = text;
+  for (const { text: entityText, type } of replacements) {
+    result = result.replaceAll(entityText, `[REDACTED_${type}]`);
+  }
+  return result;
+}
+var BUILTIN_TRANSFORMS = {
+  mask_email,
+  mask_phone,
+  fake_name,
+  jitter_date,
+  hash,
+  tokenize,
+  drop,
+  nullify,
+  redact_pii
+};
+export {
+  BUILTIN_TRANSFORMS,
+  drop,
+  fake_name,
+  hash,
+  jitter_date,
+  mask_email,
+  mask_phone,
+  nullify,
+  redact_pii,
+  tokenize
+};

package/dist/ratelimit/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @deprecated MemoryRateLimitStore has moved to `hazo_api/rate_limit` per D-014.
+ * This implementation remains in hazo_secure for one major version for backwards
+ * compatibility and will be removed in hazo_secure@2.0.0.
+ * Update your imports: `import { MemoryRateLimitStore } from 'hazo_api/rate_limit'`
+ */
+
 interface MemoryStoreOptions {
     now?: () => number;
     sweepIntervalMs?: number;

package/dist/ratelimit/index.js

@@ -58,6 +58,7 @@ function getDefaultMemoryStore() {
 }
 
 // src/ratelimit/store-connect.ts
+import { HazoConfigError, HazoValidationError, optional_import } from "hazo_core";
 var ConnectRateLimitStore = class {
   #getSvc;
   #now;
@@ -67,14 +68,27 @@ var ConnectRateLimitStore = class {
     } else if (opts.getAdapter) {
       const getAdapter = opts.getAdapter;
       this.#getSvc = async () => {
-        const { createCrudService } = await import("hazo_connect/server");
+        const mod = await optional_import(
+          "hazo_connect/server"
+        );
+        if (!mod) {
+          throw new HazoConfigError({
+            code: "HAZO_SECURE_RATELIMIT_CONNECT_MISSING",
+            pkg: "hazo_secure",
+            message: "ConnectRateLimitStore requires hazo_connect to be installed. Install it or pass `_svc` directly."
+          });
+        }
         const adapter = await getAdapter();
-        return createCrudService(adapter, "hazo_rl_buckets", {
+        return mod.createCrudService(adapter, "hazo_rl_buckets", {
           autoId: { enabled: false, column: "id" }
         });
       };
     } else {
-      throw new Error("ConnectRateLimitStore: provide getAdapter or _svc");
+      throw new HazoConfigError({
+        code: "HAZO_SECURE_RATELIMIT_INVALID_STORE_OPTIONS",
+        pkg: "hazo_secure",
+        message: "ConnectRateLimitStore: provide getAdapter or _svc"
+      });
     }
     this.#now = opts.now ?? Date.now;
   }
@@ -94,9 +108,11 @@ var ConnectRateLimitStore = class {
   }
   async increment(key, windowMs, max) {
     if (max === void 0) {
-      throw new Error(
-        "ConnectRateLimitStore requires max in increment(). Ensure createRateLimiter / checkRateLimit receives { max }."
-      );
+      throw new HazoValidationError({
+        code: "HAZO_SECURE_RATELIMIT_MISSING_MAX",
+        pkg: "hazo_secure",
+        message: "ConnectRateLimitStore requires max in increment(). Ensure createRateLimiter / checkRateLimit receives { max }."
+      });
     }
     const svc = await this.svc();
     const now = this.#now();

package/dist/secrets/index.d.ts

@@ -0,0 +1,41 @@
+import { HazoError } from 'hazo_core';
+
+type SecretsErrorCode = 'HAZO_SECURE_SECRET_NOT_FOUND';
+declare class SecretsError extends HazoError {
+    readonly code: SecretsErrorCode;
+    constructor(code: SecretsErrorCode, message: string);
+}
+interface SecretsProvider {
+    /** Resolve multiple secret names at once. Returns all resolved values.
+     *  Throws SecretsError (HAZO_SECURE_SECRET_NOT_FOUND) for any missing name. */
+    resolve(names: string[]): Promise<Record<string, string>>;
+    /** Resolve a single secret. Throws if absent. */
+    get(name: string): Promise<string>;
+}
+/**
+ * Reads secrets from environment variables.
+ * Variable name = `${prefix}_${NAME.toUpperCase()}` (underscores preserved).
+ * Default prefix: `HAZO_SECRET`
+ */
+declare class EnvSecretsProvider implements SecretsProvider {
+    private readonly prefix;
+    constructor(prefix?: string);
+    get(name: string): Promise<string>;
+    resolve(names: string[]): Promise<Record<string, string>>;
+}
+/** In-memory map. Primary use: tests. */
+declare class StaticSecretsProvider implements SecretsProvider {
+    private readonly map;
+    constructor(secrets: Record<string, string>);
+    get(name: string): Promise<string>;
+    resolve(names: string[]): Promise<Record<string, string>>;
+}
+/** Caller-supplied lookup function. Useful for custom secret backends. */
+declare class LookupSecretsProvider implements SecretsProvider {
+    private readonly lookup;
+    constructor(lookup: (name: string) => string | undefined | Promise<string | undefined>);
+    get(name: string): Promise<string>;
+    resolve(names: string[]): Promise<Record<string, string>>;
+}
+
+export { EnvSecretsProvider, LookupSecretsProvider, SecretsError, type SecretsProvider, StaticSecretsProvider };

package/dist/secrets/index.js

@@ -0,0 +1,84 @@
+// src/secrets/index.ts
+import { HazoError } from "hazo_core";
+var SecretsError = class extends HazoError {
+  constructor(code, message) {
+    super({ code, pkg: "hazo_secure", message, httpStatus: 400, retryable: false });
+    this.name = "SecretsError";
+  }
+};
+var EnvSecretsProvider = class {
+  prefix;
+  constructor(prefix = "HAZO_SECRET") {
+    this.prefix = prefix;
+  }
+  async get(name) {
+    const envKey = `${this.prefix}_${name.toUpperCase()}`;
+    const val = process.env[envKey];
+    if (val === void 0) {
+      throw new SecretsError(
+        "HAZO_SECURE_SECRET_NOT_FOUND",
+        `Secret "${name}" not found (checked env var ${envKey})`
+      );
+    }
+    return val;
+  }
+  async resolve(names) {
+    const out = {};
+    for (const name of names) {
+      out[name] = await this.get(name);
+    }
+    return out;
+  }
+};
+var StaticSecretsProvider = class {
+  map;
+  constructor(secrets) {
+    this.map = new Map(Object.entries(secrets));
+  }
+  async get(name) {
+    const val = this.map.get(name);
+    if (val === void 0) {
+      throw new SecretsError(
+        "HAZO_SECURE_SECRET_NOT_FOUND",
+        `Secret "${name}" not found in static map`
+      );
+    }
+    return val;
+  }
+  async resolve(names) {
+    const out = {};
+    for (const name of names) {
+      out[name] = await this.get(name);
+    }
+    return out;
+  }
+};
+var LookupSecretsProvider = class {
+  lookup;
+  constructor(lookup) {
+    this.lookup = lookup;
+  }
+  async get(name) {
+    const val = await this.lookup(name);
+    if (val === void 0) {
+      throw new SecretsError(
+        "HAZO_SECURE_SECRET_NOT_FOUND",
+        `Secret "${name}" not found via lookup`
+      );
+    }
+    return val;
+  }
+  async resolve(names) {
+    const out = {};
+    for (const name of names) {
+      out[name] = await this.get(name);
+    }
+    return out;
+  }
+};
+export {
+  EnvSecretsProvider,
+  LookupSecretsProvider,
+  SecretsError,
+  StaticSecretsProvider
+};

package/migrations/001_hazo_rl_buckets.sql

@@ -0,0 +1,26 @@
+-- hazo_secure rate-limit token bucket table
+-- Supports both PostgreSQL and SQLite
+--
+-- Column: id           — rate-limit key (e.g. "1.2.3.4:/api/auth/login")
+-- Column: tokens       — current token count (REAL so partial tokens are tracked)
+-- Column: last_refill_at — when tokens was last updated
+-- Column: max_tokens   — cap configured for this key (stored for introspection)
+-- Column: refill_rate_per_ms — tokens added per millisecond
+--
+-- SQLite version (use this for local dev):
+-- CREATE TABLE IF NOT EXISTS hazo_rl_buckets (
+--   id                  TEXT NOT NULL PRIMARY KEY,
+--   tokens              REAL NOT NULL,
+--   last_refill_at      TEXT NOT NULL,
+--   max_tokens          REAL NOT NULL,
+--   refill_rate_per_ms  REAL NOT NULL
+-- );
+--
+-- PostgreSQL version (active):
+CREATE TABLE IF NOT EXISTS hazo_rl_buckets (
+  id                  TEXT NOT NULL PRIMARY KEY,
+  tokens              DOUBLE PRECISION NOT NULL,
+  last_refill_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  max_tokens          DOUBLE PRECISION NOT NULL,
+  refill_rate_per_ms  DOUBLE PRECISION NOT NULL
+);