@forgezero/access 0.1.0

package/dist/rate-limit.js

@@ -0,0 +1,89 @@
+// src/rate-limit.ts
+function memoryStore() {
+  const counters = new Map;
+  const sweep = (now) => {
+    if (counters.size < 1000)
+      return;
+    for (const [key, entry] of counters) {
+      if (entry.resetAt <= now)
+        counters.delete(key);
+    }
+  };
+  return {
+    async take(key, limit, windowSeconds) {
+      const now = Date.now();
+      sweep(now);
+      const entry = counters.get(key);
+      if (!entry || entry.resetAt <= now) {
+        counters.set(key, { count: 1, resetAt: now + windowSeconds * 1000 });
+        return true;
+      }
+      if (entry.count >= limit)
+        return false;
+      entry.count += 1;
+      return true;
+    },
+    reset: () => counters.clear(),
+    size: () => counters.size
+  };
+}
+function redisStore(redis, prefix = "rl:") {
+  return {
+    async take(key, limit, windowSeconds) {
+      const namespaced = prefix + key;
+      const count = await redis.incr(namespaced);
+      if (count === 1)
+        await redis.expire(namespaced, windowSeconds);
+      return count <= limit;
+    }
+  };
+}
+function durableObjectStore(storage, prefix = "rl:") {
+  return {
+    async take(key, limit, windowSeconds) {
+      const namespaced = prefix + key;
+      const now = Date.now();
+      const entry = await storage.get(namespaced);
+      if (!entry || entry.resetAt <= now) {
+        await storage.put(namespaced, { count: 1, resetAt: now + windowSeconds * 1000 });
+        return true;
+      }
+      if (entry.count >= limit)
+        return false;
+      await storage.put(namespaced, { count: entry.count + 1, resetAt: entry.resetAt });
+      return true;
+    }
+  };
+}
+function slidingWindowStore(base) {
+  const windows = new Map;
+  return {
+    async take(key, limit, windowSeconds) {
+      const now = Date.now();
+      const size = windowSeconds * 1000;
+      const entry = windows.get(key);
+      if (!entry || now - entry.startedAt >= size * 2) {
+        windows.set(key, { current: 1, previous: 0, startedAt: now });
+        return true;
+      }
+      const elapsed = now - entry.startedAt;
+      if (elapsed >= size) {
+        entry.previous = entry.current;
+        entry.current = 0;
+        entry.startedAt = now;
+      }
+      const overlap = 1 - (now - entry.startedAt) / size;
+      const estimated = entry.previous * overlap + entry.current;
+      if (estimated >= limit)
+        return false;
+      entry.current += 1;
+      return true;
+    }
+  };
+}
+export {
+  slidingWindowStore,
+  redisStore,
+  memoryStore,
+  durableObjectStore
+};

package/dist/security.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Security helpers — the primitives every project rewrites badly.
+ *
+ * Web Crypto only, so this runs unchanged on Bun, Node 18+, Workers and Deno.
+ * No dependency, and nothing here invents a construction: these are correct
+ * uses of standard primitives, written once so the next project does not get
+ * the timing comparison or the token entropy subtly wrong.
+ */
+export declare function toHex(bytes: Uint8Array): string;
+export declare function fromHex(hex: string): Uint8Array;
+/** URL-safe base64 without padding — safe in a path, a query or a cookie. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(value: string): Uint8Array;
+/**
+ * Compare in time independent of where the difference is.
+ *
+ * `a === b` returns on the first differing byte, so an attacker who can measure
+ * the response learns the prefix and recovers a token one character at a time.
+ * The length check leaks only the length, which is not secret.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * A token with real entropy.
+ *
+ * Defaults to 32 bytes — 256 bits — because a 16-byte token is fine until it
+ * is a session identifier, and nobody revisits the default afterwards.
+ * `Math.random()` is not a CSPRNG and must never appear near a credential.
+ */
+export declare function randomToken(bytes?: number): string;
+export declare function randomHex(bytes?: number): string;
+/** Numeric OTP with uniform digits — see `randomInt` for why modulo is wrong. */
+export declare function randomDigits(length?: number): string;
+/**
+ * Uniform integer in [0, max).
+ *
+ * Rejection sampling rather than `% max`: modulo of a uniform byte is biased
+ * whenever 256 is not a multiple of max, which for a 10-digit OTP makes the
+ * first six digits measurably likelier. Small, real, and free to avoid.
+ */
+export declare function randomInt(max: number): number;
+export declare function sha256(input: string | Uint8Array): Promise<string>;
+/**
+ * Hash a bearer token for storage.
+ *
+ * Unsalted SHA-256 is correct HERE and wrong for passwords. A token already has
+ * 256 bits of entropy, so there is nothing to brute-force and a salt would only
+ * prevent the lookup we want. A password has perhaps 30 bits, which is why it
+ * needs a slow KDF instead.
+ */
+export declare const hashToken: typeof sha256;
+export declare function hmacSha256(key: string | Uint8Array, message: string): Promise<string>;
+/** Verify an HMAC without leaking where it diverged. */
+export declare function verifyHmac(key: string | Uint8Array, message: string, signature: string): Promise<boolean>;
+/**
+ * Derive a key from a high-entropy secret.
+ *
+ * `info` is domain separation and is not optional in practice: deriving two
+ * keys from one secret without it produces the SAME key, so a signing key and
+ * an encryption key become interchangeable and the separation you thought you
+ * had does not exist.
+ */
+export declare function hkdf(secret: Uint8Array, info: string, length?: number, salt?: Uint8Array<ArrayBuffer>): Promise<Uint8Array>;
+export interface Sealed {
+    /** Nonce. Never reused with the same key — see `seal`. */
+    iv: string;
+    ciphertext: string;
+}
+/**
+ * AES-256-GCM with additional authenticated data.
+ *
+ * `aad` binds the ciphertext to its context — tenant, project, entry, version.
+ * A blob moved anywhere else then fails its tag rather than decrypting, which
+ * turns a scoping bug into a loud failure instead of silent cross-tenant
+ * disclosure.
+ *
+ * The IV is 12 random bytes per call. GCM catastrophically loses
+ * confidentiality on nonce reuse, so it is never derived from a counter or a
+ * timestamp here.
+ */
+export declare function seal(key: Uint8Array, plaintext: string, aad?: string): Promise<Sealed>;
+/** Throws on a tag mismatch — wrong key, tampering, or the wrong `aad`. */
+export declare function open(key: Uint8Array, sealed: Sealed, aad?: string): Promise<string>;
+export declare const nowSeconds: () => number;
+/**
+ * Whether something is still live.
+ *
+ * Checked in the application even where a TTL index exists, because a database
+ * reaper runs on its own schedule — often a minute or more behind under load —
+ * so an expired row stays readable for a while after it died. Trusting the
+ * index alone means the session outlives its own expiry.
+ */
+export declare const isLive: (expiresAtSec: number, at?: number) => boolean;
+declare const SECRET_NAME: RegExp;
+/**
+ * Strip anything credential-shaped before logging or exporting.
+ *
+ * Logs, span attributes and error payloads all reach places the value was never
+ * meant to go, and every one of them is an exfiltration path nobody
+ * deliberately built.
+ */
+export declare function redact<T extends Record<string, unknown>>(value: T): Record<string, unknown>;
+export { SECRET_NAME as secretFieldPattern };

package/dist/security.js

@@ -0,0 +1,141 @@
+// src/security.ts
+var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));
+function toHex(bytes) {
+  let out = "";
+  for (const byte of bytes)
+    out += HEX[byte];
+  return out;
+}
+function fromHex(hex) {
+  if (hex.length % 2 !== 0)
+    throw new Error("Hex string must have an even length.");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0;index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function toBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function randomToken(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toBase64Url(buffer);
+}
+function randomHex(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toHex(buffer);
+}
+function randomDigits(length = 6) {
+  let digits = "";
+  for (let index = 0;index < length; index += 1)
+    digits += randomInt(10).toString();
+  return digits;
+}
+function randomInt(max) {
+  if (max <= 0 || max > 256)
+    throw new Error("randomInt supports 1..256.");
+  const limit = Math.floor(256 / max) * max;
+  const buffer = new Uint8Array(1);
+  for (;; ) {
+    crypto.getRandomValues(buffer);
+    if (buffer[0] < limit)
+      return buffer[0] % max;
+  }
+}
+async function sha256(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+var hashToken = sha256;
+async function hmacSha256(key, message) {
+  const keyBytes = typeof key === "string" ? new TextEncoder().encode(key) : key;
+  const imported = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", imported, new TextEncoder().encode(message));
+  return toHex(new Uint8Array(signature));
+}
+async function verifyHmac(key, message, signature) {
+  return timingSafeEqual(await hmacSha256(key, message), signature);
+}
+async function hkdf(secret, info, length = 32, salt = new Uint8Array(32)) {
+  const key = await crypto.subtle.importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info: new TextEncoder().encode(info) }, key, length * 8);
+  return new Uint8Array(bits);
+}
+async function seal(key, plaintext, aad) {
+  const iv = new Uint8Array(12);
+  crypto.getRandomValues(iv);
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv,
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, new TextEncoder().encode(plaintext));
+  return { iv: toBase64Url(iv), ciphertext: toBase64Url(new Uint8Array(ciphertext)) };
+}
+async function open(key, sealed, aad) {
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+  const plaintext = await crypto.subtle.decrypt({
+    name: "AES-GCM",
+    iv: fromBase64Url(sealed.iv),
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, fromBase64Url(sealed.ciphertext));
+  return new TextDecoder().decode(plaintext);
+}
+var nowSeconds = () => Math.floor(Date.now() / 1000);
+var isLive = (expiresAtSec, at = nowSeconds()) => expiresAtSec > at;
+var SECRET_NAME = /token|secret|password|passphrase|credential|authorization|cookie|apikey|api_key|private/i;
+function redact(value) {
+  const out = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (SECRET_NAME.test(name))
+      out[name] = "[redacted]";
+    else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      out[name] = redact(entry);
+    } else
+      out[name] = entry;
+  }
+  return out;
+}
+export {
+  verifyHmac,
+  toHex,
+  toBase64Url,
+  timingSafeEqual,
+  sha256,
+  SECRET_NAME as secretFieldPattern,
+  seal,
+  redact,
+  randomToken,
+  randomInt,
+  randomHex,
+  randomDigits,
+  open,
+  nowSeconds,
+  isLive,
+  hmacSha256,
+  hkdf,
+  hashToken,
+  fromHex,
+  fromBase64Url
+};

package/dist/testing.d.ts

@@ -0,0 +1,63 @@
+import { type AccessControl, type Role, type RouteRegistry } from './index';
+/**
+ * Assert an access decision without standing up a server.
+ *
+ * A model nobody can test is a model nobody trusts. This is what lets a tenant
+ * write "this role cannot reach this route" as a unit test rather than clicking
+ * through an environment — and it answers WHICH policy decided, which is the
+ * part a 403 in a browser never tells you.
+ */
+export interface SimulateArgs {
+    route: string;
+    roles?: readonly Role[];
+    /** Shorthand: role keys with every session factor already proven. */
+    as?: string | {
+        roleKeys: readonly string[];
+        factors?: readonly string[];
+    };
+    stage?: string;
+    realm?: string;
+    enabledFactors?: readonly string[];
+}
+export interface Verdict {
+    allowed: boolean;
+    status: 200 | 404 | 401 | 403 | 428;
+    reason: string;
+    /** Which policy decided. The thing a browser 403 never tells you. */
+    sessionPolicy?: string;
+    actionPolicy?: string;
+    missingFactors?: readonly string[];
+    /** True when a fresh proof would still be demanded after passing layer 1. */
+    requiresStepUp: boolean;
+}
+/**
+ * Run layer 1 and report what layer 2 would then require.
+ *
+ * Deliberately does NOT simulate satisfying a step-up: a fresh proof is by
+ * definition something only a human can supply, and a test helper that pretended
+ * otherwise would be teaching the wrong model.
+ */
+export declare function simulate<R extends RouteRegistry>(access: AccessControl<R>, args: SimulateArgs, registries?: {
+    sessionPolicies?: Record<string, {
+        routes: readonly string[];
+    }>;
+    actionPolicies?: Record<string, {
+        routes: readonly string[];
+    }>;
+}): Verdict;
+/**
+ * Every route a set of roles can reach. Answers "what can this role actually
+ * do" without reading the grant list by hand — which is the question an audit
+ * asks and a grant list answers badly.
+ */
+export declare function reachableRoutes<R extends RouteRegistry>(access: AccessControl<R>, roles: readonly Role[], roleKeys: readonly string[], context?: {
+    stage?: string;
+    realm?: string;
+}): readonly string[];
+/**
+ * Routes reachable by NOBODY — no role grants them.
+ *
+ * Usually a rename that left a grant behind, or a route added and never granted.
+ * Both ship silently: the route works in development, where you are an admin.
+ */
+export declare function unreachableRoutes<R extends RouteRegistry>(access: AccessControl<R>, roles: readonly Role[]): readonly string[];