@binary1702/auth 0.2.4 → 0.3.0

package/dist/core/options.d.ts

@@ -0,0 +1,76 @@
+import { type YamlTree } from "./yaml.ts";
+export declare const CONFIG_FILE = "b17_auth.yaml";
+export type SignupMode = "open" | "closed" | "invite";
+export type EmailOptions = {
+    from?: string;
+    replyTo?: string;
+    gmail?: {
+        /** the mailbox to send as */
+        user: string;
+        /** service account (Workspace, domain-wide delegation): its email and private key */
+        clientEmail?: string;
+        privateKey?: string;
+        /** or an OAuth client with a refresh token (a plain Gmail account) */
+        clientId?: string;
+        clientSecret?: string;
+        refreshToken?: string;
+    };
+    resend?: {
+        apiKey: string;
+    };
+};
+export type Options = {
+    /** App name: page titles and email subjects. Falls back to the request's host. */
+    name?: string;
+    signup: SignupMode;
+    inviteCode?: string;
+    emailDomain?: string;
+    requireVerified: boolean;
+    sessionDays: number;
+    /** Paths that need a session, exact or `prefix/*`; everything else is open. Use this OR `public`. */
+    protected: string[];
+    /** The reverse: everything needs a session except these (and static files). */
+    public: string[];
+    /** Emails that may open /auth/admin. Lowercased. */
+    admins: string[];
+    database?: string;
+    secret?: string;
+    email: EmailOptions;
+    /** role → permissions. "all" (or "*") is everything, "blue.*" a prefix */
+    permissions: Record<string, string[]>;
+    /** organization name → role → permissions, overriding `permissions` there */
+    organizations: Record<string, Record<string, string[]>>;
+    production: boolean;
+};
+export declare const DEFAULTS: Options;
+/** Keys whose value must be a ${…} reference in the file, never a literal */
+export declare const SECRET_KEYS: string[];
+export type Env = Record<string, string | undefined>;
+/** The env vars as they were before the file existed. Pure. */
+export declare function fromEnv(env: Env): Partial<Options>;
+/** "all" is the file's word for "*"; duplicates dropped. */
+export declare function normalizePermissions(list: string[]): string[];
+export declare class OptionsError extends Error {
+    constructor(message: string);
+}
+/** Replace every ${NAME} in a value from env. A missing variable is an error naming both. */
+export declare function interpolate(value: string, env: Env, key: string): string;
+/**
+ * Literal secrets in a committed file are how keys leak. Returns the keys
+ * that hold a literal where a ${…} reference belongs. Pure.
+ */
+export declare function literalSecrets(tree: YamlTree): string[];
+/** The file's contents as options, ${…} resolved. Pure. */
+export declare function fromYaml(tree: YamlTree, env: Env): Partial<Options>;
+/** defaults ← file ← env. Maps (email, permissions, organizations) merge key by key. Pure. */
+export declare function resolveOptions(file: YamlTree | null, env: Env): Options;
+/**
+ * Read b17_auth.yaml from the project root (the directory the server was
+ * started in), or from AUTH_CONFIG when that is set, and merge with env.
+ * Memoized; re-read in development when the file changes.
+ */
+export declare function loadOptions(cwd?: string, env?: Env): Options;
+/** The current options. What every handler reads. */
+export declare function options(): Options;
+/** Drop the memo (tests, CLI after writing the file). */
+export declare function resetOptions(): void;

package/dist/core/options.js

@@ -0,0 +1,310 @@
+// ─────────────────────────────────────────────────────────────
+// One typed object for everything configurable, built from three
+// layers, each overriding the one before:
+//
+//   DEFAULTS         what the package does with no configuration
+//   b17_auth.yaml    the app's choices, with ${NAME} pulled from env
+//   env vars         the deploy-time override, and the only home of secrets
+//
+// No file → the env vars work exactly as they always did. The pure
+// part is resolveOptions(); loadOptions() adds the file read and a
+// per-process memo (re-read in development when the file changes).
+// ─────────────────────────────────────────────────────────────
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseYaml, words } from "./yaml.js";
+export const CONFIG_FILE = "b17_auth.yaml";
+export const DEFAULTS = {
+    signup: "closed",
+    requireVerified: false,
+    sessionDays: 7,
+    protected: [],
+    public: [],
+    admins: [],
+    email: {},
+    // An owner can do everything unless a file says otherwise. A sole
+    // developer never has to write a permissions section at all.
+    permissions: { owner: ["*"] },
+    organizations: {},
+    production: false,
+};
+/** Keys whose value must be a ${…} reference in the file, never a literal */
+export const SECRET_KEYS = ["database", "secret", "inviteCode", "email.gmail.privateKey", "email.gmail.clientSecret", "email.gmail.refreshToken", "email.resend.apiKey"];
+// ── env layer ─────────────────────────────────────────────────
+const truthy = (v) => /^(true|1|yes)$/i.test(v ?? "");
+/** The env vars as they were before the file existed. Pure. */
+export function fromEnv(env) {
+    const o = {};
+    if (env.AUTH_SIGNUP === "open")
+        o.signup = env.AUTH_INVITE_CODE ? "invite" : "open";
+    if (env.AUTH_INVITE_CODE)
+        o.inviteCode = env.AUTH_INVITE_CODE;
+    if (env.AUTH_EMAIL_DOMAIN)
+        o.emailDomain = env.AUTH_EMAIL_DOMAIN;
+    if (env.AUTH_REQUIRE_VERIFIED !== undefined)
+        o.requireVerified = truthy(env.AUTH_REQUIRE_VERIFIED);
+    if (env.AUTH_PROTECTED)
+        o.protected = words(env.AUTH_PROTECTED);
+    if (env.AUTH_PUBLIC)
+        o.public = words(env.AUTH_PUBLIC);
+    if (env.AUTH_ADMINS)
+        o.admins = words(env.AUTH_ADMINS).map((e) => e.toLowerCase());
+    if (env.DATABASE_URL)
+        o.database = env.DATABASE_URL;
+    if (env.AUTH_SECRET)
+        o.secret = env.AUTH_SECRET;
+    const email = {};
+    if (env.AUTH_EMAIL_FROM)
+        email.from = env.AUTH_EMAIL_FROM;
+    if (env.AUTH_EMAIL_REPLY_TO)
+        email.replyTo = env.AUTH_EMAIL_REPLY_TO;
+    if (env.AUTH_GMAIL_USER) {
+        email.gmail = {
+            user: env.AUTH_GMAIL_USER,
+            clientEmail: env.AUTH_GMAIL_CLIENT_EMAIL,
+            privateKey: env.AUTH_GMAIL_PRIVATE_KEY,
+            clientId: env.AUTH_GMAIL_CLIENT_ID,
+            clientSecret: env.AUTH_GMAIL_CLIENT_SECRET,
+            refreshToken: env.AUTH_GMAIL_REFRESH_TOKEN,
+        };
+    }
+    if (env.AUTH_RESEND_API_KEY)
+        email.resend = { apiKey: env.AUTH_RESEND_API_KEY };
+    if (Object.keys(email).length)
+        o.email = email;
+    if (env.AUTH_PERMISSIONS)
+        o.permissions = permissionsFromJson(env.AUTH_PERMISSIONS);
+    o.production = env.NODE_ENV === "production";
+    return o;
+}
+function permissionsFromJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('AUTH_PERMISSIONS is not valid JSON. Expected: {"admin":["invoices.view"],"member":[]}');
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("AUTH_PERMISSIONS must be a JSON object mapping role → list of permissions");
+    }
+    const map = {};
+    for (const [role, perms] of Object.entries(parsed)) {
+        if (!Array.isArray(perms) || !perms.every((p) => typeof p === "string")) {
+            throw new Error(`AUTH_PERMISSIONS: role "${role}" must map to a list of strings`);
+        }
+        map[role] = normalizePermissions(perms);
+    }
+    return map;
+}
+/** "all" is the file's word for "*"; duplicates dropped. */
+export function normalizePermissions(list) {
+    return [...new Set(list.map((p) => (p === "all" ? "*" : p)))];
+}
+// ── file layer ────────────────────────────────────────────────
+export class OptionsError extends Error {
+    constructor(message) {
+        super(`${CONFIG_FILE}: ${message}`);
+        this.name = "OptionsError";
+    }
+}
+/** Replace every ${NAME} in a value from env. A missing variable is an error naming both. */
+export function interpolate(value, env, key) {
+    return value.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+        const v = env[name];
+        if (v === undefined || v === "")
+            throw new OptionsError(`${key} refers to \${${name}}, which is not set in the environment`);
+        return v;
+    });
+}
+const isRef = (v) => typeof v === "string" && /^\$\{[A-Z0-9_]+\}$/i.test(v.trim());
+/**
+ * Literal secrets in a committed file are how keys leak. Returns the keys
+ * that hold a literal where a ${…} reference belongs. Pure.
+ */
+export function literalSecrets(tree) {
+    const get = (path) => path.split(".").reduce((n, k) => (n && typeof n === "object" ? n[k] : undefined), tree);
+    return SECRET_KEYS.filter((k) => {
+        const v = get(k);
+        return typeof v === "string" && v.trim() !== "" && !isRef(v);
+    });
+}
+/** `key:` with nothing after it and nothing under it: the same as leaving the key out */
+const isEmpty = (v) => typeof v === "object" && v !== null && Object.keys(v).length === 0;
+function str(tree, key, env) {
+    const v = tree[key];
+    if (v === undefined || isEmpty(v))
+        return undefined;
+    if (typeof v !== "string")
+        throw new OptionsError(`${key} must be a value, not a section`);
+    return interpolate(v, env, key);
+}
+function section(tree, key) {
+    const v = tree[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "object")
+        throw new OptionsError(`${key} must be a section with indented keys under it`);
+    return v;
+}
+/** The file's contents as options, ${…} resolved. Pure. */
+export function fromYaml(tree, env) {
+    const o = {};
+    const known = new Set(["name", "signup", "inviteCode", "emailDomain", "requireVerified", "sessionDays", "protected", "public", "admins", "database", "secret", "email", "permissions", "organizations"]);
+    for (const k of Object.keys(tree))
+        if (!known.has(k))
+            throw new OptionsError(`unknown key "${k}"`);
+    const name = str(tree, "name", env);
+    if (name)
+        o.name = name;
+    const signup = str(tree, "signup", env);
+    if (signup !== undefined) {
+        if (!["open", "closed", "invite"].includes(signup))
+            throw new OptionsError(`signup must be open, closed or invite, not "${signup}"`);
+        o.signup = signup;
+    }
+    const invite = str(tree, "inviteCode", env);
+    if (invite)
+        o.inviteCode = invite;
+    const domain = str(tree, "emailDomain", env);
+    if (domain)
+        o.emailDomain = domain;
+    const rv = str(tree, "requireVerified", env);
+    if (rv !== undefined) {
+        if (!/^(true|false)$/i.test(rv))
+            throw new OptionsError(`requireVerified must be true or false`);
+        o.requireVerified = truthy(rv);
+    }
+    const days = str(tree, "sessionDays", env);
+    if (days !== undefined) {
+        if (!/^\d+$/.test(days) || Number(days) < 1)
+            throw new OptionsError(`sessionDays must be a whole number of days`);
+        o.sessionDays = Number(days);
+    }
+    for (const key of ["protected", "public"]) {
+        const v = str(tree, key, env);
+        if (v === undefined)
+            continue;
+        o[key] = words(v);
+        for (const p of o[key])
+            if (!p.startsWith("/"))
+                throw new OptionsError(`${key} paths start with /, not "${p}"`);
+    }
+    if (o.protected?.length && o.public?.length) {
+        throw new OptionsError("use either protected: (only these need sign-in) or public: (everything but these), not both");
+    }
+    const admins = str(tree, "admins", env);
+    if (admins !== undefined) {
+        o.admins = words(admins).map((e) => e.toLowerCase());
+        for (const a of o.admins)
+            if (!a.includes("@"))
+                throw new OptionsError(`admins are email addresses, not "${a}"`);
+    }
+    const database = str(tree, "database", env);
+    if (database)
+        o.database = database;
+    const secret = str(tree, "secret", env);
+    if (secret)
+        o.secret = secret;
+    const email = section(tree, "email");
+    if (email) {
+        const e = {};
+        const from = str(email, "from", env);
+        if (from)
+            e.from = from;
+        const replyTo = str(email, "replyTo", env);
+        if (replyTo)
+            e.replyTo = replyTo;
+        const gmail = section(email, "gmail");
+        if (gmail) {
+            const user = str(gmail, "user", env);
+            if (!user)
+                throw new OptionsError("email.gmail needs `user: <mailbox to send as>`");
+            e.gmail = {
+                user,
+                clientEmail: str(gmail, "clientEmail", env),
+                privateKey: str(gmail, "privateKey", env),
+                clientId: str(gmail, "clientId", env),
+                clientSecret: str(gmail, "clientSecret", env),
+                refreshToken: str(gmail, "refreshToken", env),
+            };
+        }
+        const resend = section(email, "resend");
+        if (resend) {
+            const apiKey = str(resend, "apiKey", env);
+            if (!apiKey)
+                throw new OptionsError("email.resend needs `apiKey: ${AUTH_RESEND_API_KEY}`");
+            e.resend = { apiKey };
+        }
+        o.email = e;
+    }
+    const perms = section(tree, "permissions");
+    if (perms)
+        o.permissions = roleMap(perms, env, "permissions");
+    const orgs = section(tree, "organizations");
+    if (orgs) {
+        o.organizations = {};
+        for (const [org, roles] of Object.entries(orgs)) {
+            if (typeof roles !== "object")
+                throw new OptionsError(`organizations.${org} must be a section of role: permissions`);
+            o.organizations[org] = roleMap(roles, env, `organizations.${org}`);
+        }
+    }
+    return o;
+}
+function roleMap(tree, env, where) {
+    const map = {};
+    for (const [role, v] of Object.entries(tree)) {
+        if (isEmpty(v)) {
+            map[role] = []; // `member:` with nothing: a role that exists and may do nothing yet
+            continue;
+        }
+        if (typeof v !== "string")
+            throw new OptionsError(`${where}.${role} must be a list of permissions separated by spaces`);
+        map[role] = normalizePermissions(words(interpolate(v, env, `${where}.${role}`)));
+    }
+    return map;
+}
+// ── merge ─────────────────────────────────────────────────────
+/** defaults ← file ← env. Maps (email, permissions, organizations) merge key by key. Pure. */
+export function resolveOptions(file, env) {
+    const layers = [DEFAULTS, file ? fromYaml(file, env) : {}, fromEnv(env)];
+    const out = { ...DEFAULTS, email: {}, permissions: {}, organizations: {} };
+    for (const layer of layers) {
+        for (const [k, v] of Object.entries(layer)) {
+            if (v === undefined)
+                continue;
+            if (k === "email" || k === "permissions" || k === "organizations")
+                Object.assign(out[k], v);
+            else
+                out[k] = v;
+        }
+    }
+    return out;
+}
+// ── loading ───────────────────────────────────────────────────
+let cache = null;
+/**
+ * Read b17_auth.yaml from the project root (the directory the server was
+ * started in), or from AUTH_CONFIG when that is set, and merge with env.
+ * Memoized; re-read in development when the file changes.
+ */
+export function loadOptions(cwd = process.cwd(), env = process.env) {
+    const path = env.AUTH_CONFIG ? (env.AUTH_CONFIG.startsWith("/") ? env.AUTH_CONFIG : join(cwd, env.AUTH_CONFIG)) : join(cwd, CONFIG_FILE);
+    const exists = existsSync(path);
+    const mtime = exists ? statSync(path).mtimeMs : 0;
+    if (cache && cache.path === path && (cache.options.production || cache.mtime === mtime))
+        return cache.options;
+    const file = exists ? parseYaml(readFileSync(path, "utf8")) : null;
+    const options = resolveOptions(file, env);
+    cache = { options, path, mtime };
+    return options;
+}
+/** The current options. What every handler reads. */
+export function options() {
+    return loadOptions();
+}
+/** Drop the memo (tests, CLI after writing the file). */
+export function resetOptions() {
+    cache = null;
+}

package/dist/core/org.d.ts

@@ -0,0 +1,34 @@
+import type { User } from "./session.ts";
+import type { SessionRow } from "./db.ts";
+import type { Options } from "./options.ts";
+export type Organization = {
+    id: string;
+    name: string;
+};
+export type Authorization = {
+    role: string | null;
+    permissions: string[];
+};
+export type Session = {
+    user: User;
+    organization: Organization | null;
+    authorization: Authorization;
+};
+export type PermissionSource = Pick<Options, "permissions" | "organizations">;
+/** The effective permissions of a role, in an organization. The organization's own map wins. Pure. */
+export declare function permissionsFor(role: string | null, org: string | null, opts: PermissionSource): string[];
+/** Build the contract from the store's row. Pure. */
+export declare function buildSession(row: SessionRow, opts: PermissionSource): Session;
+/**
+ * The check. Pure. A granted entry matches when it is
+ *   "*"            everything
+ *   "invoices.*"   any permission under that prefix ("invoices.view", "invoices.a.b")
+ *   exact          the permission itself
+ */
+export declare function hasPermission(session: Pick<Session, "authorization">, permission: string): boolean;
+/** What a signed-out client sees from the React side. The HTTP endpoint answers 401 instead. */
+export declare const NO_SESSION: {
+    user: null;
+    organization: null;
+    authorization: Authorization;
+};

package/dist/core/org.js

@@ -0,0 +1,55 @@
+// ─────────────────────────────────────────────────────────────
+// The session contract: one JSON shape for "who is this, where are
+// they, what may they do". Served by GET /auth/session and returned
+// by getSession() on the server. Three keys, nothing else.
+//
+//   user            { id, email }
+//   organization    { id, name } or null when the user is in none
+//   authorization   { role, permissions }
+//
+// Role comes from the membership row (members.role, free text;
+// the CLI defaults to "member"). Permissions are the app's business,
+// so they come from b17_auth.yaml (or AUTH_PERMISSIONS):
+//
+//   permissions:            role → what it may do
+//     owner: all            "all" (or "*") is everything
+//     member: blue.* green.read
+//   organizations:          overrides, by organization name
+//     Acme:
+//       member: blue.read
+//
+// Unknown role, no role, or no map: no permissions. All pure; the
+// store feeds it one row.
+// ─────────────────────────────────────────────────────────────
+/** The effective permissions of a role, in an organization. The organization's own map wins. Pure. */
+export function permissionsFor(role, org, opts) {
+    if (!role)
+        return [];
+    const own = org ? opts.organizations[org]?.[role] : undefined;
+    return own ?? opts.permissions[role] ?? [];
+}
+/** Build the contract from the store's row. Pure. */
+export function buildSession(row, opts) {
+    const organization = row.org_id && row.org_name !== null ? { id: row.org_id, name: row.org_name } : null;
+    const role = organization ? row.role : null;
+    return {
+        user: { id: row.id, email: row.email },
+        organization,
+        authorization: { role, permissions: permissionsFor(role, organization?.name ?? null, opts) },
+    };
+}
+/**
+ * The check. Pure. A granted entry matches when it is
+ *   "*"            everything
+ *   "invoices.*"   any permission under that prefix ("invoices.view", "invoices.a.b")
+ *   exact          the permission itself
+ */
+export function hasPermission(session, permission) {
+    return session.authorization.permissions.some((granted) => granted === "*" || granted === permission || (granted.endsWith(".*") && permission.startsWith(granted.slice(0, -1))));
+}
+/** What a signed-out client sees from the React side. The HTTP endpoint answers 401 instead. */
+export const NO_SESSION = {
+    user: null,
+    organization: null,
+    authorization: { role: null, permissions: [] },
+};

package/dist/core/password.d.ts

@@ -1,2 +1,18 @@
+export declare const SCRYPT_N: number;
+export declare const SCRYPT_R = 8;
+export declare const SCRYPT_P = 1;
 export declare function hashPassword(password: string): Promise<string>;
+type Parsed = {
+    n: number;
+    r: number;
+    p: number;
+    salt: Buffer;
+    hash: Buffer;
+};
+/** The parts of a stored hash, or null when it is not one of ours. Pure. */
+export declare function parseHash(stored: string): Parsed | null;
+/** False for a wrong password and for anything that is not a well-formed hash. Never throws. */
 export declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+/** True when the stored hash was made with weaker parameters than today's, or is not ours. Pure. */
+export declare function needsRehash(stored: string): boolean;
+export {};

package/dist/core/password.js

@@ -3,30 +3,59 @@
 //
 // Stored format:  scrypt$N$r$p$<salt b64url>$<hash b64url>
 // Parameters live in the string, so they can be raised later
-// without invalidating existing rows.
+// without invalidating existing rows: needsRehash() spots a row
+// hashed under weaker parameters, and sign-in re-hashes it.
+//
+// N = 2^17 since 0.3.0 (about 0.3 s and 128 MB per hash): slow on
+// purpose, it is what makes a stolen table expensive to crack.
 // ─────────────────────────────────────────────────────────────
 import { randomBytes, scrypt as scryptCb, timingSafeEqual } from "node:crypto";
 import { promisify } from "node:util";
 const scrypt = promisify(scryptCb);
-const N = 16384;
-const R = 8;
-const P = 1;
+export const SCRYPT_N = 2 ** 17;
+export const SCRYPT_R = 8;
+export const SCRYPT_P = 1;
 const KEYLEN = 64;
 function run(password, salt, n, r, p) {
     return scrypt(password, salt, KEYLEN, { N: n, r, p, maxmem: 256 * n * r });
 }
 export async function hashPassword(password) {
     const salt = randomBytes(16);
-    const hash = await run(password, salt, N, R, P);
-    return ["scrypt", N, R, P, salt.toString("base64url"), hash.toString("base64url")].join("$");
+    const hash = await run(password, salt, SCRYPT_N, SCRYPT_R, SCRYPT_P);
+    return ["scrypt", SCRYPT_N, SCRYPT_R, SCRYPT_P, salt.toString("base64url"), hash.toString("base64url")].join("$");
 }
-export async function verifyPassword(password, stored) {
+/** The parts of a stored hash, or null when it is not one of ours. Pure. */
+export function parseHash(stored) {
     const parts = stored.split("$");
     if (parts.length !== 6 || parts[0] !== "scrypt")
-        return false;
+        return null;
     const [, n, r, p, saltB64, hashB64] = parts;
-    const salt = Buffer.from(saltB64, "base64url");
-    const expected = Buffer.from(hashB64, "base64url");
-    const actual = await run(password, salt, Number(n), Number(r), Number(p));
-    return actual.length === expected.length && timingSafeEqual(actual, expected);
+    const num = (s) => (/^\d+$/.test(s) ? Number(s) : NaN);
+    const parsed = { n: num(n), r: num(r), p: num(p), salt: Buffer.from(saltB64, "base64url"), hash: Buffer.from(hashB64, "base64url") };
+    // N must be a power of two above 1; r and p positive; salt and hash present
+    if (!(parsed.n > 1 && Number.isInteger(parsed.n) && (parsed.n & (parsed.n - 1)) === 0))
+        return null;
+    if (!(parsed.r >= 1 && parsed.p >= 1))
+        return null;
+    if (parsed.salt.length === 0 || parsed.hash.length === 0)
+        return null;
+    return parsed;
+}
+/** False for a wrong password and for anything that is not a well-formed hash. Never throws. */
+export async function verifyPassword(password, stored) {
+    const h = parseHash(stored);
+    if (!h)
+        return false;
+    try {
+        const actual = await run(password, h.salt, h.n, h.r, h.p);
+        return actual.length === h.hash.length && timingSafeEqual(actual, h.hash);
+    }
+    catch {
+        return false;
+    }
+}
+/** True when the stored hash was made with weaker parameters than today's, or is not ours. Pure. */
+export function needsRehash(stored) {
+    const h = parseHash(stored);
+    return !h || h.n < SCRYPT_N || h.r < SCRYPT_R || h.p < SCRYPT_P;
 }

package/dist/core/rate.d.ts

@@ -0,0 +1,26 @@
+import { type Db } from "./db.ts";
+export type Bucket = "signin:ip" | "signin:email" | "signup:ip" | "forgot:email" | "verify:email";
+/** [limit, window in seconds] */
+export declare const LIMITS: Record<Bucket, readonly [number, number]>;
+export type Hit = {
+    count: number;
+    reset_at: string | Date;
+};
+export type Decision = {
+    allowed: boolean;
+    retryAfter: number;
+    count: number;
+    limit: number;
+};
+/** The rule. `hit` is the bucket's row after this request was counted. Pure. */
+export declare function decide(hit: Hit, limit: number, now?: Date): Decision;
+/** The client's address, as the first proxy saw it; "unknown" when no header says. Pure. */
+export declare function clientIp(headers: {
+    get(name: string): string | null;
+}): string;
+/** The row's key. Emails lowercased, so "Ben@" and "ben@" share a bucket. Pure. */
+export declare function bucketKey(bucket: Bucket, value: string): string;
+/** The message a refused request sees. Pure. */
+export declare function retryMessage(retryAfter: number): string;
+/** Count this request against the bucket and decide. One statement, plus housekeeping when a window starts. */
+export declare function rateLimit(bucket: Bucket, value: string, store?: Db, now?: Date): Promise<Decision>;

package/dist/core/rate.js

@@ -0,0 +1,70 @@
+// ─────────────────────────────────────────────────────────────
+// Rate limiting: a fixed window per bucket, stored in one row.
+//
+//   rateLimit("signin:email", "ben@x.y")   one INSERT … ON CONFLICT that
+//                                          starts or bumps the window and
+//                                          returns the count; decide() then
+//                                          says allowed or not, and for how
+//                                          long to wait.
+//
+// Buckets and limits (per window):
+//   signin:ip      20 / 15 min    stops guessing many accounts from one place
+//   signin:email   10 / 15 min    stops guessing one account from many places
+//   signup:ip      10 / 1 h       stops account spam
+//   forgot:email    3 / 1 h       stops reset-email spam
+//   verify:email    3 / 1 h       stops verification-email spam
+//
+// Refused requests get 429 with Retry-After. The decision is pure; the
+// storage is one function.
+// ─────────────────────────────────────────────────────────────
+import { db, ensureSchema } from "./db.js";
+/** [limit, window in seconds] */
+export const LIMITS = {
+    "signin:ip": [20, 15 * 60],
+    "signin:email": [10, 15 * 60],
+    "signup:ip": [10, 60 * 60],
+    "forgot:email": [3, 60 * 60],
+    "verify:email": [3, 60 * 60],
+};
+/** The rule. `hit` is the bucket's row after this request was counted. Pure. */
+export function decide(hit, limit, now = new Date()) {
+    const count = Number(hit.count);
+    const resetAt = new Date(hit.reset_at).getTime();
+    const retryAfter = Math.max(1, Math.ceil((resetAt - now.getTime()) / 1000));
+    return count <= limit ? { allowed: true, retryAfter: 0, count, limit } : { allowed: false, retryAfter, count, limit };
+}
+/** The client's address, as the first proxy saw it; "unknown" when no header says. Pure. */
+export function clientIp(headers) {
+    const fwd = headers.get("x-forwarded-for");
+    if (fwd) {
+        const first = fwd.split(",")[0].trim();
+        if (first)
+            return first;
+    }
+    return headers.get("x-real-ip")?.trim() || "unknown";
+}
+/** The row's key. Emails lowercased, so "Ben@" and "ben@" share a bucket. Pure. */
+export function bucketKey(bucket, value) {
+    return `${bucket}:${value.trim().toLowerCase()}`;
+}
+/** The message a refused request sees. Pure. */
+export function retryMessage(retryAfter) {
+    const m = Math.ceil(retryAfter / 60);
+    return retryAfter < 90 ? `Too many attempts. Try again in ${retryAfter} seconds.` : `Too many attempts. Try again in ${m} minutes.`;
+}
+/** Count this request against the bucket and decide. One statement, plus housekeeping when a window starts. */
+export async function rateLimit(bucket, value, store = db(), now = new Date()) {
+    const [limit, windowSeconds] = LIMITS[bucket];
+    await ensureSchema(store);
+    const [hit] = await store.query(`INSERT INTO rate_limits (bucket, count, reset_at)
+     VALUES ($1, 1, now() + ($2::int * interval '1 second'))
+     ON CONFLICT (bucket) DO UPDATE SET
+       count    = CASE WHEN rate_limits.reset_at <= now() THEN 1 ELSE rate_limits.count + 1 END,
+       reset_at = CASE WHEN rate_limits.reset_at <= now() THEN now() + ($2::int * interval '1 second') ELSE rate_limits.reset_at END
+     RETURNING count, reset_at`, [bucketKey(bucket, value), windowSeconds]);
+    if (Number(hit.count) === 1) {
+        // A window just started: a cheap moment to drop windows nobody will look at again
+        await store.query(`DELETE FROM rate_limits WHERE reset_at < now() - interval '1 day'`);
+    }
+    return decide(hit, limit, now);
+}