@shaferllc/keel 0.59.0 → 0.66.0

package/dist/core/application.js

@@ -168,9 +168,21 @@ export class Application extends Container {
         for (const provider of this.providers) {
             await provider.boot();
         }
+        // A provider's shutdown() joins the app's shutdown hooks, so it runs (LIFO)
+        // on terminate() alongside any onShutdown() a provider registered by hand.
+        // ready()/shutdown() are optional — plain duck-typed providers may omit them.
+        for (const provider of this.providers) {
+            if (typeof provider.shutdown === "function") {
+                this.onShutdown(() => provider.shutdown());
+            }
+        }
         this.booted = true;
         for (const hook of this.readyHooks)
             await hook(this);
+        for (const provider of this.providers) {
+            if (typeof provider.ready === "function")
+                await provider.ready();
+        }
         return this;
     }
     /**

package/dist/core/auth.d.ts

@@ -12,6 +12,7 @@
  *   await auth().user();      // the full user (via your provider)
  */
 import type { MiddlewareHandler } from "hono";
+import { type AccessToken } from "./tokens.js";
 /** Loads a user by the id stored in the session. Register with setUserProvider. */
 export type UserProvider = (id: string) => unknown | Promise<unknown>;
 /** Tell Keel how to load the authenticated user from its id. */
@@ -58,3 +59,49 @@ export declare function authGuard(options?: {
 export declare function bearerAuth(options?: {
     optional?: boolean;
 }): MiddlewareHandler;
+/**
+ * Verifies a Basic-auth credential pair. Return the authenticated user's id to
+ * log them in for the request (so `auth().user()` resolves through your
+ * provider), `true` to allow without an identity, or a falsy value to reject.
+ * Verify the password with `hash.verify` — and reach for `hash.dummy` on a miss
+ * so timing doesn't reveal which usernames exist.
+ */
+export type BasicVerifier = (username: string, password: string) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
+/**
+ * HTTP Basic authentication. Reads `Authorization: Basic <base64>`, decodes the
+ * `username:password` pair, and hands it to your `verify` callback. On failure
+ * it answers `401` with a `WWW-Authenticate` challenge (so a browser prompts).
+ * Handy for internal tools and quick API gates — always behind HTTPS, since the
+ * credentials ride on every request.
+ *
+ *   router.get("/admin", handler).use(
+ *     basicAuth(async (user, pass) => {
+ *       const row = await findAdmin(user);
+ *       return (await hash.verify(row?.password ?? hash.dummy, pass)) && row ? row.id : false;
+ *     }),
+ *   );
+ */
+export declare function basicAuth(verify: BasicVerifier, options?: {
+    realm?: string;
+}): MiddlewareHandler;
+/**
+ * Opaque access-token auth — the revocable, ability-scoped counterpart to
+ * `bearerAuth()` (which verifies a stateless JWT). Reads `Authorization: Bearer
+ * keel_…`, verifies it against the [token store](./tokens.ts), and makes the
+ * token's owner the authenticated id — plus stashes the token itself so handlers
+ * can check abilities via `token()` / `tokenCan()`.
+ *
+ *   router.get("/api/posts", handler).use(tokenAuth({ abilities: ["posts:read"] }));
+ *
+ * Rejects a missing, invalid, expired, or under-scoped token with `401`. Pass
+ * `{ optional: true }` to let unauthenticated requests through.
+ */
+export declare function tokenAuth(options?: {
+    optional?: boolean;
+    abilities?: string[];
+    connection?: string;
+}): MiddlewareHandler;
+/** The opaque access token verified by `tokenAuth()` on this request, or null. */
+export declare function token(): AccessToken | null;
+/** Whether this request's access token grants an ability (`false` if there's none). */
+export declare function tokenCan(ability: string): boolean;

package/dist/core/auth.js

@@ -14,6 +14,7 @@
 import { session } from "./session.js";
 import { ctx } from "./request.js";
 import { jwt } from "./crypto.js";
+import { verifyToken, tokenAllows } from "./tokens.js";
 const KEY = "auth_id";
 let provider;
 /** Tell Keel how to load the authenticated user from its id. */
@@ -103,3 +104,79 @@ export function bearerAuth(options = {}) {
         await next();
     };
 }
+/**
+ * HTTP Basic authentication. Reads `Authorization: Basic <base64>`, decodes the
+ * `username:password` pair, and hands it to your `verify` callback. On failure
+ * it answers `401` with a `WWW-Authenticate` challenge (so a browser prompts).
+ * Handy for internal tools and quick API gates — always behind HTTPS, since the
+ * credentials ride on every request.
+ *
+ *   router.get("/admin", handler).use(
+ *     basicAuth(async (user, pass) => {
+ *       const row = await findAdmin(user);
+ *       return (await hash.verify(row?.password ?? hash.dummy, pass)) && row ? row.id : false;
+ *     }),
+ *   );
+ */
+export function basicAuth(verify, options = {}) {
+    const realm = options.realm ?? "Restricted";
+    return async (c, next) => {
+        const challenge = () => c.json({ error: "Unauthenticated", status: 401 }, 401, {
+            "WWW-Authenticate": `Basic realm="${realm}", charset="UTF-8"`,
+        });
+        const raw = c.req.header("authorization")?.match(/^Basic\s+(.+)$/i)?.[1];
+        if (!raw)
+            return challenge();
+        let decoded;
+        try {
+            decoded = new TextDecoder().decode(Uint8Array.from(atob(raw), (ch) => ch.charCodeAt(0)));
+        }
+        catch {
+            return challenge(); // not valid base64
+        }
+        const sep = decoded.indexOf(":");
+        if (sep === -1)
+            return challenge();
+        const result = await verify(decoded.slice(0, sep), decoded.slice(sep + 1));
+        if (!result)
+            return challenge();
+        if (result !== true)
+            c.set("auth_id", String(result));
+        await next();
+    };
+}
+/**
+ * Opaque access-token auth — the revocable, ability-scoped counterpart to
+ * `bearerAuth()` (which verifies a stateless JWT). Reads `Authorization: Bearer
+ * keel_…`, verifies it against the [token store](./tokens.ts), and makes the
+ * token's owner the authenticated id — plus stashes the token itself so handlers
+ * can check abilities via `token()` / `tokenCan()`.
+ *
+ *   router.get("/api/posts", handler).use(tokenAuth({ abilities: ["posts:read"] }));
+ *
+ * Rejects a missing, invalid, expired, or under-scoped token with `401`. Pass
+ * `{ optional: true }` to let unauthenticated requests through.
+ */
+export function tokenAuth(options = {}) {
+    return async (c, next) => {
+        const raw = c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        const token = raw ? await verifyToken(raw, options.connection) : null;
+        const scoped = token && (options.abilities ?? []).every((a) => tokenAllows(token, a));
+        if (!token || !scoped) {
+            if (options.optional)
+                return next();
+            return c.json({ error: "Unauthenticated", status: 401 }, 401);
+        }
+        c.set("auth_id", token.tokenableId);
+        c.set("access_token", token);
+        await next();
+    };
+}
+/** The opaque access token verified by `tokenAuth()` on this request, or null. */
+export function token() {
+    return ctx().get("access_token") ?? null;
+}
+/** Whether this request's access token grants an ability (`false` if there's none). */
+export function tokenCan(ability) {
+    return tokenAllows(token(), ability);
+}

package/dist/core/authorization.d.ts

@@ -25,6 +25,8 @@ type Constructor = new (...args: never[]) => object;
 export type GateCallback = (user: User, ...args: Args) => boolean | Promise<boolean>;
 /** Runs before every check; return a boolean to short-circuit (e.g. admin bypass). */
 export type BeforeCallback = (user: User, ability: string, args: Args) => boolean | undefined | Promise<boolean | undefined>;
+/** Runs after every check; return a boolean to override the result (e.g. audit + veto). */
+export type AfterCallback = (user: User, ability: string, args: Args, result: boolean) => boolean | undefined | Promise<boolean | undefined>;
 /** Define a gate — an ad-hoc ability keyed by name. */
 export declare function define(ability: string, callback: GateCallback): void;
 /**
@@ -35,9 +37,15 @@ export declare function define(ability: string, callback: GateCallback): void;
 export declare function policy(model: Constructor, impl: object | (new () => object)): void;
 /** Register a callback that runs before every check (return a boolean to decide). */
 export declare function gateBefore(callback: BeforeCallback): void;
+/**
+ * Register a callback that runs *after* every check and can override its result
+ * — return a boolean to replace it, or `undefined` to keep it. Pairs with
+ * `gateBefore` to bracket every decision (logging, audit, a late veto).
+ */
+export declare function gateAfter(callback: AfterCallback): void;
 /** Override how the "current user" is resolved (default: `auth().user()`). */
 export declare function setUserResolver(resolver: () => User | Promise<User>): void;
-/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+/** Reset gates, policies, hooks, and the resolver (test helper). */
 export declare function clearAuthorization(): void;
 /** Whether the current user is allowed the ability (with the given arguments). */
 export declare function can(ability: string, ...args: Args): Promise<boolean>;

package/dist/core/authorization.js

@@ -23,6 +23,7 @@ import { auth } from "./auth.js";
 const gates = new Map();
 const policies = new Map();
 let beforeCallback;
+let afterCallback;
 let userResolver = () => auth().user();
 /** Define a gate — an ad-hoc ability keyed by name. */
 export function define(ability, callback) {
@@ -41,18 +42,28 @@ export function policy(model, impl) {
 export function gateBefore(callback) {
     beforeCallback = callback;
 }
+/**
+ * Register a callback that runs *after* every check and can override its result
+ * — return a boolean to replace it, or `undefined` to keep it. Pairs with
+ * `gateBefore` to bracket every decision (logging, audit, a late veto).
+ */
+export function gateAfter(callback) {
+    afterCallback = callback;
+}
 /** Override how the "current user" is resolved (default: `auth().user()`). */
 export function setUserResolver(resolver) {
     userResolver = resolver;
 }
-/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+/** Reset gates, policies, hooks, and the resolver (test helper). */
 export function clearAuthorization() {
     gates.clear();
     policies.clear();
     beforeCallback = undefined;
+    afterCallback = undefined;
     userResolver = () => auth().user();
 }
-async function evaluate(user, ability, args) {
+/** Resolve a check to a raw boolean, before the after-hook runs. */
+async function decide(user, ability, args) {
     if (beforeCallback) {
         const decided = await beforeCallback(user, ability, args);
         if (typeof decided === "boolean")
@@ -71,6 +82,15 @@ async function evaluate(user, ability, args) {
         return Boolean(await gate(user, ...args));
     return false; // unknown ability — deny by default
 }
+async function evaluate(user, ability, args) {
+    const result = await decide(user, ability, args);
+    if (afterCallback) {
+        const overridden = await afterCallback(user, ability, args, result);
+        if (typeof overridden === "boolean")
+            return overridden;
+    }
+    return result;
+}
 /** Whether the current user is allowed the ability (with the given arguments). */
 export async function can(ability, ...args) {
     return evaluate(await userResolver(), ability, args);

package/dist/core/container.d.ts

@@ -13,12 +13,32 @@ export type Factory<T> = (app: Container) => T;
 export declare class Container {
     private bindings;
     private instances;
+    private swaps;
     /** Register a transient binding — a fresh value every resolve. */
     bind<T>(token: Token<T>, factory: Factory<T>): this;
     /** Register a shared binding — resolved once, then cached. */
     singleton<T>(token: Token<T>, factory: Factory<T>): this;
     /** Register an already-constructed value as a shared instance. */
     instance<T>(token: Token<T>, value: T): T;
+    /**
+     * Register an alias that resolves to another token — `alias("router", Router)`
+     * lets `make("router")` return whatever `make(Router)` does, honoring the
+     * target's own sharing (the target owns the singleton; the alias just points).
+     */
+    alias<T>(alias: Token<T>, target: Token<T>): this;
+    /**
+     * Temporarily replace a binding with a fake — for tests. The replacement is
+     * shared (resolved once), and the original binding/instance is remembered so
+     * `restore()` can put it back. Idempotent per token: the first swap saves the
+     * original; later swaps just change the fake.
+     *
+     *   app.swap(Mailer, () => fakeMailer);
+     *   // … exercise code that resolves Mailer …
+     *   app.restore(Mailer);
+     */
+    swap<T>(token: Token<T>, factory: Factory<T>): this;
+    /** Undo a `swap()` — restore the original binding. No token restores every swap. */
+    restore(token?: Token): this;
     /** True if the token is bound or has a cached instance. */
     bound(token: Token): boolean;
     /** Resolve a token out of the container. */

package/dist/core/container.js

@@ -10,6 +10,7 @@
 export class Container {
     bindings = new Map();
     instances = new Map();
+    swaps = new Map();
     /** Register a transient binding — a fresh value every resolve. */
     bind(token, factory) {
         this.bindings.set(token, { factory, shared: false });
@@ -25,6 +26,57 @@ export class Container {
         this.instances.set(token, value);
         return value;
     }
+    /**
+     * Register an alias that resolves to another token — `alias("router", Router)`
+     * lets `make("router")` return whatever `make(Router)` does, honoring the
+     * target's own sharing (the target owns the singleton; the alias just points).
+     */
+    alias(alias, target) {
+        this.bindings.set(alias, { factory: (app) => app.make(target), shared: false });
+        return this;
+    }
+    /**
+     * Temporarily replace a binding with a fake — for tests. The replacement is
+     * shared (resolved once), and the original binding/instance is remembered so
+     * `restore()` can put it back. Idempotent per token: the first swap saves the
+     * original; later swaps just change the fake.
+     *
+     *   app.swap(Mailer, () => fakeMailer);
+     *   // … exercise code that resolves Mailer …
+     *   app.restore(Mailer);
+     */
+    swap(token, factory) {
+        if (!this.swaps.has(token)) {
+            this.swaps.set(token, {
+                binding: this.bindings.get(token),
+                instance: this.instances.get(token),
+                hadInstance: this.instances.has(token),
+            });
+        }
+        this.bindings.set(token, { factory, shared: true });
+        this.instances.delete(token); // force the next make() through the fake
+        return this;
+    }
+    /** Undo a `swap()` — restore the original binding. No token restores every swap. */
+    restore(token) {
+        if (token === undefined) {
+            for (const t of [...this.swaps.keys()])
+                this.restore(t);
+            return this;
+        }
+        const saved = this.swaps.get(token);
+        if (!saved)
+            return this;
+        this.swaps.delete(token);
+        this.instances.delete(token);
+        if (saved.binding)
+            this.bindings.set(token, saved.binding);
+        else
+            this.bindings.delete(token);
+        if (saved.hadInstance)
+            this.instances.set(token, saved.instance);
+        return this;
+    }
     /** True if the token is bound or has a cached instance. */
     bound(token) {
         return this.bindings.has(token) || this.instances.has(token);

package/dist/core/cors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CORS — Cross-Origin Resource Sharing. Register it in your HTTP kernel (or on a
+ * route group) to let browsers on other origins call your API. It answers
+ * preflight `OPTIONS` requests automatically and sets the `Access-Control-*`
+ * headers on every response.
+ *
+ *   this.use(cors());                                  // reflect any origin (dev)
+ *   this.use(cors({ origin: ["https://app.example.com"], credentials: true }));
+ *
+ * `origin` accepts a boolean (`true` reflects the caller, `false` blocks), `"*"`,
+ * an allowlist array, or a predicate. When `credentials` is on, `"*"` isn't legal
+ * per the spec, so the caller's origin is reflected and `Vary: Origin` is set.
+ */
+import type { Context, MiddlewareHandler } from "hono";
+export interface CorsOptions {
+    /** Who may call: `true` reflects the request origin, `false` blocks, `"*"` any, an allowlist, or a predicate. Default `true`. */
+    origin?: boolean | string | string[] | ((origin: string, c: Context) => boolean | string);
+    /** Allowed methods for cross-origin requests. */
+    methods?: string[];
+    /** Allowed request headers: `true` reflects what the browser asks for, or an allowlist. Default `true`. */
+    headers?: boolean | string[];
+    /** Response headers JS may read (`Access-Control-Expose-Headers`). */
+    exposeHeaders?: string[];
+    /** Send `Access-Control-Allow-Credentials: true` (cookies/authorization). Default `false`. */
+    credentials?: boolean;
+    /** Preflight cache seconds (`Access-Control-Max-Age`). `null` omits it. Default 86400. */
+    maxAge?: number | null;
+}
+export declare function cors(options?: CorsOptions): MiddlewareHandler;

package/dist/core/cors.js

@@ -0,0 +1,72 @@
+/**
+ * CORS — Cross-Origin Resource Sharing. Register it in your HTTP kernel (or on a
+ * route group) to let browsers on other origins call your API. It answers
+ * preflight `OPTIONS` requests automatically and sets the `Access-Control-*`
+ * headers on every response.
+ *
+ *   this.use(cors());                                  // reflect any origin (dev)
+ *   this.use(cors({ origin: ["https://app.example.com"], credentials: true }));
+ *
+ * `origin` accepts a boolean (`true` reflects the caller, `false` blocks), `"*"`,
+ * an allowlist array, or a predicate. When `credentials` is on, `"*"` isn't legal
+ * per the spec, so the caller's origin is reflected and `Vary: Origin` is set.
+ */
+const DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"];
+/** Resolve the allowed origin for this request, or `null` to disallow. */
+function resolveOrigin(option, requestOrigin, c) {
+    if (option === undefined || option === true)
+        return requestOrigin || "*";
+    if (option === false)
+        return null;
+    if (option === "*")
+        return "*";
+    if (typeof option === "string")
+        return option;
+    if (Array.isArray(option))
+        return option.includes(requestOrigin) ? requestOrigin : null;
+    const result = option(requestOrigin, c);
+    if (result === true)
+        return requestOrigin || "*";
+    if (result === false)
+        return null;
+    return result;
+}
+export function cors(options = {}) {
+    const methods = options.methods ?? DEFAULT_METHODS;
+    const maxAge = options.maxAge === undefined ? 86400 : options.maxAge;
+    const credentials = options.credentials ?? false;
+    return async (c, next) => {
+        const requestOrigin = c.req.header("origin") ?? "";
+        let allowOrigin = resolveOrigin(options.origin, requestOrigin, c);
+        // With credentials, "*" is illegal — reflect the concrete origin instead.
+        if (allowOrigin === "*" && credentials)
+            allowOrigin = requestOrigin || null;
+        const shared = {};
+        if (allowOrigin)
+            shared["Access-Control-Allow-Origin"] = allowOrigin;
+        // Reflecting a specific origin makes the response vary by it (caches).
+        if (allowOrigin && allowOrigin !== "*")
+            shared["Vary"] = "Origin";
+        if (credentials)
+            shared["Access-Control-Allow-Credentials"] = "true";
+        // Preflight — answer directly with all headers, never reaching the route.
+        if (c.req.method === "OPTIONS" && c.req.header("access-control-request-method")) {
+            const headers = { ...shared, "Access-Control-Allow-Methods": methods.join(", ") };
+            const allowHeaders = options.headers === undefined || options.headers === true
+                ? c.req.header("access-control-request-headers") ?? ""
+                : options.headers.join(", ");
+            if (allowHeaders)
+                headers["Access-Control-Allow-Headers"] = allowHeaders;
+            if (maxAge != null)
+                headers["Access-Control-Max-Age"] = String(maxAge);
+            return c.body(null, 204, headers);
+        }
+        await next();
+        // Set on the final response (survives a handler that returns a fresh Response).
+        for (const [name, value] of Object.entries(shared))
+            c.header(name, value);
+        if (options.exposeHeaders?.length) {
+            c.header("Access-Control-Expose-Headers", options.exposeHeaders.join(", "));
+        }
+    };
+}

package/dist/core/crypto.d.ts

@@ -18,12 +18,48 @@ export declare const hash: {
     verify(hashed: string, password: string): Promise<boolean>;
     /** Whether a hash was made with fewer iterations than the current default. */
     needsRehash(hashed: string, iterations?: number): boolean;
+    /**
+     * Swap real hashing for a trivial, **insecure** scheme so tests that create
+     * many users don't pay for PBKDF2. `make` returns `fake$<password>` and
+     * `verify` just compares — near-instant. Call in a test setup hook; undo with
+     * `restore()`. Never use outside tests.
+     */
+    fake(): void;
+    /** Restore real PBKDF2 hashing after `fake()`. */
+    restore(): void;
+    /**
+     * A valid dummy hash (of a random secret) at the default cost. Compare against
+     * it when a user *isn't* found so login spends the same time as a wrong
+     * password — otherwise a fast "no such user" response leaks which emails are
+     * registered (a timing/enumeration attack).
+     *
+     *   const user = await findUserByEmail(email);
+     *   const ok = await hash.verify(user?.password ?? hash.dummy, password);
+     *   if (ok && user) auth().login(user.id);   // `user &&` so the dummy never authenticates
+     */
+    dummy: string;
 };
+export interface EncryptOptions {
+    /** Time-to-live — seconds (number) or a duration string (`"30m"`, `"1h"`, `"7d"`). */
+    expiresIn?: number | string;
+    /** Bind the token to a context; `decrypt` must pass the same `purpose` or gets `null`. */
+    purpose?: string;
+}
 export declare const encryption: {
-    /** Encrypt any JSON-serializable value (AES-GCM), keyed by config('app.key'). */
-    encrypt(value: unknown): Promise<string>;
-    /** Decrypt a value; returns null if the payload is tampered or invalid. */
-    decrypt<T = unknown>(payload: string): Promise<T | null>;
+    /**
+     * Encrypt any JSON-serializable value (AES-GCM), keyed by `config('app.key')`.
+     * `expiresIn` makes the token self-expire; `purpose` binds it to a context
+     * (e.g. `"password-reset"`) so a token minted for one use can't be replayed for
+     * another.
+     */
+    encrypt(value: unknown, options?: EncryptOptions): Promise<string>;
+    /**
+     * Decrypt a value; returns `null` if the payload is tampered, invalid, expired,
+     * or minted for a different `purpose`. Never throws.
+     */
+    decrypt<T = unknown>(payload: string, options?: {
+        purpose?: string;
+    }): Promise<T | null>;
 };
 /** Standard registered claims, plus whatever custom fields you sign. */
 export interface JwtPayload {

package/dist/core/crypto.js

@@ -42,6 +42,9 @@ function appKey() {
 }
 /* ------------------------------- hashing ------------------------------- */
 const DEFAULT_ITERATIONS = 100_000;
+/** When true, `hash` skips PBKDF2 for a trivial (insecure) scheme — tests only. */
+let faking = false;
+const FAKE_PREFIX = "fake$";
 async function pbkdf2(password, salt, iterations) {
     const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(password), "PBKDF2", false, ["deriveBits"]);
     const bits = await crypto.subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations, hash: "SHA-256" }, key, 256);
@@ -50,12 +53,16 @@ async function pbkdf2(password, salt, iterations) {
 export const hash = {
     /** Hash a password (PBKDF2-SHA256 with a random salt). */
     async make(password, iterations = DEFAULT_ITERATIONS) {
+        if (faking)
+            return `${FAKE_PREFIX}${password}`;
         const salt = crypto.getRandomValues(new Uint8Array(16));
         const derived = await pbkdf2(password, salt, iterations);
         return `pbkdf2_sha256$${iterations}$${b64(salt)}$${b64(derived)}`;
     },
     /** Verify a password against a stored hash. Returns false for any malformed hash. */
     async verify(hashed, password) {
+        if (faking)
+            return hashed === `${FAKE_PREFIX}${password}`;
         const [algo, iter, salt64, hash64] = hashed.split("$");
         if (algo !== "pbkdf2_sha256" || !iter || !salt64 || !hash64)
             return false;
@@ -73,9 +80,35 @@ export const hash = {
     },
     /** Whether a hash was made with fewer iterations than the current default. */
     needsRehash(hashed, iterations = DEFAULT_ITERATIONS) {
+        if (faking)
+            return false;
         const iter = Number(hashed.split("$")[1]);
         return !iter || iter < iterations;
     },
+    /**
+     * Swap real hashing for a trivial, **insecure** scheme so tests that create
+     * many users don't pay for PBKDF2. `make` returns `fake$<password>` and
+     * `verify` just compares — near-instant. Call in a test setup hook; undo with
+     * `restore()`. Never use outside tests.
+     */
+    fake() {
+        faking = true;
+    },
+    /** Restore real PBKDF2 hashing after `fake()`. */
+    restore() {
+        faking = false;
+    },
+    /**
+     * A valid dummy hash (of a random secret) at the default cost. Compare against
+     * it when a user *isn't* found so login spends the same time as a wrong
+     * password — otherwise a fast "no such user" response leaks which emails are
+     * registered (a timing/enumeration attack).
+     *
+     *   const user = await findUserByEmail(email);
+     *   const ok = await hash.verify(user?.password ?? hash.dummy, password);
+     *   if (ok && user) auth().login(user.id);   // `user &&` so the dummy never authenticates
+     */
+    dummy: "pbkdf2_sha256$100000$7uVVFNW3RCry5kPKJQUgTw==$fOfxeFDnxv5A3rhl6bcWGKJQhmcK8x6XNfe9Z88WO/A=",
 };
 /* ----------------------------- encryption ------------------------------ */
 async function aesKey() {
@@ -83,24 +116,51 @@ async function aesKey() {
     return crypto.subtle.importKey("raw", digest, "AES-GCM", false, ["encrypt", "decrypt"]);
 }
 export const encryption = {
-    /** Encrypt any JSON-serializable value (AES-GCM), keyed by config('app.key'). */
-    async encrypt(value) {
+    /**
+     * Encrypt any JSON-serializable value (AES-GCM), keyed by `config('app.key')`.
+     * `expiresIn` makes the token self-expire; `purpose` binds it to a context
+     * (e.g. `"password-reset"`) so a token minted for one use can't be replayed for
+     * another.
+     */
+    async encrypt(value, options = {}) {
+        // Wrap in a small envelope so expiry/purpose travel inside the ciphertext.
+        const envelope = { __k: 1, v: value };
+        if (options.expiresIn != null)
+            envelope.exp = Date.now() + seconds(options.expiresIn) * 1000;
+        if (options.purpose != null)
+            envelope.p = options.purpose;
         const iv = crypto.getRandomValues(new Uint8Array(12));
-        const data = new TextEncoder().encode(JSON.stringify(value));
+        const data = new TextEncoder().encode(JSON.stringify(envelope));
         const cipher = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, await aesKey(), data));
         const packed = new Uint8Array(iv.length + cipher.length);
         packed.set(iv);
         packed.set(cipher, iv.length);
         return b64(packed);
     },
-    /** Decrypt a value; returns null if the payload is tampered or invalid. */
-    async decrypt(payload) {
+    /**
+     * Decrypt a value; returns `null` if the payload is tampered, invalid, expired,
+     * or minted for a different `purpose`. Never throws.
+     */
+    async decrypt(payload, options = {}) {
         try {
             const bytes = fromB64(payload);
             const iv = bytes.slice(0, 12);
             const cipher = bytes.slice(12);
             const plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: iv }, await aesKey(), cipher);
-            return JSON.parse(new TextDecoder().decode(plain));
+            const parsed = JSON.parse(new TextDecoder().decode(plain));
+            // Envelope (new format): enforce expiry + purpose.
+            if (parsed && typeof parsed === "object" && parsed.__k === 1) {
+                const env = parsed;
+                if (typeof env.exp === "number" && Date.now() >= env.exp)
+                    return null;
+                if ((options.purpose ?? null) !== (env.p ?? null))
+                    return null;
+                return env.v;
+            }
+            // Legacy plain value (encrypted before envelopes). A required purpose can't match.
+            if (options.purpose != null)
+                return null;
+            return parsed;
         }
         catch {
             return null;

package/dist/core/csrf.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CSRF protection for server-rendered apps. A synchronizer token lives in the
+ * session; state-changing requests (`POST`/`PUT`/`PATCH`/`DELETE`) must echo it
+ * back, or they're rejected with `419 Page Expired`. Needs `sessionMiddleware()`.
+ *
+ *   this.use(sessionMiddleware());
+ *   this.use(csrf());
+ *
+ * Put the token in forms with `csrfField()`; SPAs get it for free — `csrf()` also
+ * writes an `XSRF-TOKEN` cookie that axios/fetch libraries send back as the
+ * `X-XSRF-TOKEN` header automatically. The token is also read from a `_token` or
+ * `_csrf` field, or the `X-CSRF-Token` header.
+ */
+import type { MiddlewareHandler } from "hono";
+/** The current request's CSRF token, minting and storing one if absent. */
+export declare function csrfToken(): string;
+/** A hidden form input carrying the CSRF token — drop it into any `<form method="POST">`. */
+export declare function csrfField(): string;
+export interface CsrfOptions {
+    /** Paths exempt from verification (webhooks, callbacks). Trailing `*` matches a prefix. */
+    except?: (string | RegExp)[];
+    /** Write the readable `XSRF-TOKEN` cookie for SPA libraries. Default true. */
+    cookie?: boolean;
+}
+export declare function csrf(options?: CsrfOptions): MiddlewareHandler;