@shaferllc/keel 0.59.0 → 0.68.0

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;

package/dist/core/csrf.js

@@ -0,0 +1,78 @@
+/**
+ * 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 { setCookie } from "hono/cookie";
+import { HttpException } from "./exceptions.js";
+import { session } from "./session.js";
+import { request } from "./request.js";
+const KEY = "_csrf";
+const UNSAFE = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function randomToken() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++)
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return result === 0;
+}
+/** The current request's CSRF token, minting and storing one if absent. */
+export function csrfToken() {
+    const sess = session();
+    let token = sess.get(KEY, undefined);
+    if (!token) {
+        token = randomToken();
+        sess.put(KEY, token);
+    }
+    return token;
+}
+/** A hidden form input carrying the CSRF token — drop it into any `<form method="POST">`. */
+export function csrfField() {
+    return `<input type="hidden" name="_token" value="${csrfToken()}">`;
+}
+async function submitted(c) {
+    const header = c.req.header("x-csrf-token") ?? c.req.header("x-xsrf-token");
+    if (header)
+        return header;
+    const all = await request.all(); // shares keel's body cache — safe to read
+    return (all._token ?? all._csrf);
+}
+function isExcepted(path, except) {
+    return except.some((rule) => typeof rule === "string"
+        ? rule.endsWith("*")
+            ? path.startsWith(rule.slice(0, -1))
+            : path === rule
+        : rule.test(path));
+}
+export function csrf(options = {}) {
+    const except = options.except ?? [];
+    return async (c, next) => {
+        const token = csrfToken(); // ensures a token exists in the session
+        if (options.cookie !== false) {
+            setCookie(c, "XSRF-TOKEN", token, { path: "/", sameSite: "Lax" }); // readable by JS on purpose
+        }
+        if (UNSAFE.has(c.req.method.toUpperCase()) && !isExcepted(c.req.path, except)) {
+            const provided = await submitted(c);
+            if (!provided || !safeEqual(provided, token)) {
+                throw new HttpException(419, "CSRF token mismatch");
+            }
+        }
+        await next();
+    };
+}

package/dist/core/database.d.ts

@@ -31,16 +31,40 @@ export interface Connection {
 }
 export type Dialect = "sqlite" | "mysql" | "postgres";
 export type Operator = "=" | "!=" | "<" | "<=" | ">" | ">=" | "like";
-/** Register the database connection (and dialect) used by `db()`. */
+/** A registered connection — the driver bridge plus its SQL dialect. */
+interface Source {
+    conn: Connection;
+    dialect: Dialect;
+}
+/** Register the default connection (and dialect) used by `db()`. */
 export declare function setConnection(conn: Connection, driverDialect?: Dialect): void;
+/**
+ * Register a *named* connection alongside any others — the way to use more than
+ * one database. Point a query or model at it by name; nothing else changes.
+ *
+ *   addConnection("reporting", pgConn, "postgres");
+ *   await db("events", "reporting").where("kind", "signup").count();
+ */
+export declare function addConnection(name: string, conn: Connection, driverDialect?: Dialect): void;
+/** Choose which registered connection `db()` and models use when none is named. */
+export declare function setDefaultConnection(name: string): void;
+/** The names of every registered connection. */
+export declare function connectionNames(): string[];
+/** Unregister every connection — a test helper for a clean slate. */
+export declare function clearConnections(): void;
 export declare class QueryBuilder<T extends Row = Row> {
     private table;
+    private getSource;
     private wheres;
     private orders;
     private columns;
     private _limit?;
     private _offset?;
-    constructor(table: string);
+    constructor(table: string, getSource: () => Source);
+    /** Run a row-returning query on this builder's connection, dialect-adjusted. */
+    private runSelect;
+    /** Run a write on this builder's connection, dialect-adjusted. */
+    private runWrite;
     select(...columns: string[]): this;
     where(column: string, value: unknown): this;
     where(column: string, operator: Operator, value: unknown): this;
@@ -79,5 +103,26 @@ export declare class QueryBuilder<T extends Row = Row> {
     update(data: Row): Promise<WriteResult>;
     delete(): Promise<WriteResult>;
 }
-/** Start a query against a table. */
-export declare function db<T extends Row = Row>(table: string): QueryBuilder<T>;
+/** Start a query against a table, on the default connection or a named one. */
+export declare function db<T extends Row = Row>(table: string, connectionName?: string): QueryBuilder<T>;
+/** A handle to one registered connection — query it, or run raw SQL on it. */
+export interface ConnectionHandle {
+    /** Start a query against a table on this connection. */
+    table<T extends Row = Row>(table: string): QueryBuilder<T>;
+    /** Run a raw row-returning query (`?` placeholders, dialect-adjusted). */
+    select(sql: string, bindings?: unknown[]): Promise<Row[]>;
+    /** Run a raw write (`?` placeholders, dialect-adjusted). */
+    write(sql: string, bindings?: unknown[]): Promise<WriteResult>;
+    /** This connection's SQL dialect. */
+    readonly dialect: Dialect;
+}
+/**
+ * Get a handle to a named connection (or the default). Use it to run several
+ * queries against one database without repeating the name, or to reach the raw
+ * `select`/`write` bridge.
+ *
+ *   const reporting = connection("reporting");
+ *   await reporting.table("events").where("kind", "signup").count();
+ */
+export declare function connection(name?: string): ConnectionHandle;
+export {};

package/dist/core/database.js

@@ -9,20 +9,56 @@
  *   const user = await db("users").where("id", 1).first();
  *   await db("users").insert({ email });
  */
-let connection;
-let dialect = "sqlite";
-/** Register the database connection (and dialect) used by `db()`. */
+/**
+ * The connection registry. An app can talk to several databases at once —
+ * register each by name, then route a query with `db(table, name)`, a whole
+ * model with `static connection`, or a handle from `connection(name)`. The
+ * unnamed default lives under `"default"` so `db(table)` and `setConnection()`
+ * keep working unchanged.
+ */
+const registry = new Map();
+let defaultConnection = "default";
+/** Register the default connection (and dialect) used by `db()`. */
 export function setConnection(conn, driverDialect = "sqlite") {
-    connection = conn;
-    dialect = driverDialect;
+    registry.set("default", { conn, dialect: driverDialect });
+    defaultConnection = "default";
+}
+/**
+ * Register a *named* connection alongside any others — the way to use more than
+ * one database. Point a query or model at it by name; nothing else changes.
+ *
+ *   addConnection("reporting", pgConn, "postgres");
+ *   await db("events", "reporting").where("kind", "signup").count();
+ */
+export function addConnection(name, conn, driverDialect = "sqlite") {
+    registry.set(name, { conn, dialect: driverDialect });
+}
+/** Choose which registered connection `db()` and models use when none is named. */
+export function setDefaultConnection(name) {
+    if (!registry.has(name))
+        throw new Error(`No database connection "${name}" to make default.`);
+    defaultConnection = name;
+}
+/** The names of every registered connection. */
+export function connectionNames() {
+    return [...registry.keys()];
 }
-function conn() {
-    if (!connection)
-        throw new Error("No database connection. Call setConnection(conn, dialect).");
-    return connection;
+/** Unregister every connection — a test helper for a clean slate. */
+export function clearConnections() {
+    registry.clear();
+    defaultConnection = "default";
 }
-/** Render `?` placeholders for the active dialect (Postgres uses $1, $2, …). */
-function placeholders(sql) {
+/** Resolve a connection by name (or the default); throws if it isn't registered. */
+function resolve(name) {
+    const source = registry.get(name ?? defaultConnection);
+    if (!source) {
+        throw new Error(`No database connection${name ? ` "${name}"` : ""}. ` +
+            `Call setConnection(conn, dialect) or addConnection(name, conn, dialect).`);
+    }
+    return source;
+}
+/** Render `?` placeholders for a dialect (Postgres uses $1, $2, …). */
+function placeholders(sql, dialect) {
     if (dialect !== "postgres")
         return sql;
     let i = 0;
@@ -30,13 +66,28 @@ function placeholders(sql) {
 }
 export class QueryBuilder {
     table;
+    getSource;
     wheres = [];
     orders = [];
     columns = "*";
     _limit;
     _offset;
-    constructor(table) {
+    // The connection is resolved lazily, when a query actually runs — so building
+    // a query never throws, and an unregistered connection surfaces as a rejected
+    // read/write rather than a synchronous error at construction.
+    constructor(table, getSource) {
         this.table = table;
+        this.getSource = getSource;
+    }
+    /** Run a row-returning query on this builder's connection, dialect-adjusted. */
+    runSelect(sql, bindings) {
+        const source = this.getSource();
+        return source.conn.select(placeholders(sql, source.dialect), bindings);
+    }
+    /** Run a write on this builder's connection, dialect-adjusted. */
+    runWrite(sql, bindings) {
+        const source = this.getSource();
+        return source.conn.write(placeholders(sql, source.dialect), bindings);
     }
     select(...columns) {
         this.columns = columns.length ? columns.join(", ") : "*";
@@ -114,7 +165,7 @@ export class QueryBuilder {
             sql += ` LIMIT ${this._limit}`;
         if (this._offset != null)
             sql += ` OFFSET ${this._offset}`;
-        return (await conn().select(placeholders(sql), where.bindings));
+        return (await this.runSelect(sql, where.bindings));
     }
     async first() {
         this._limit = 1;
@@ -123,7 +174,7 @@ export class QueryBuilder {
     }
     async count() {
         const where = this.whereClause();
-        const rows = (await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings));
+        const rows = (await this.runSelect(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`, where.bindings));
         return Number(rows[0]?.count ?? 0);
     }
     async exists() {
@@ -131,7 +182,7 @@ export class QueryBuilder {
     }
     async aggregate(fn, column) {
         const where = this.whereClause();
-        const rows = (await conn().select(placeholders(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${where.sql}`), where.bindings));
+        const rows = (await this.runSelect(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${where.sql}`, where.bindings));
         return Number(rows[0]?.agg ?? 0);
     }
     sum(column) {
@@ -178,7 +229,7 @@ export class QueryBuilder {
         const sql = `INSERT INTO ${this.table} (${keys.join(", ")}) VALUES (${keys
             .map(() => "?")
             .join(", ")})`;
-        return conn().write(placeholders(sql), Object.values(data));
+        return this.runWrite(sql, Object.values(data));
     }
     async insertGetId(data) {
         return (await this.insert(data)).insertId;
@@ -187,17 +238,34 @@ export class QueryBuilder {
         const keys = Object.keys(data);
         const set = keys.map((k) => `${k} = ?`).join(", ");
         const where = this.whereClause();
-        return conn().write(placeholders(`UPDATE ${this.table} SET ${set}${where.sql}`), [
+        return this.runWrite(`UPDATE ${this.table} SET ${set}${where.sql}`, [
             ...Object.values(data),
             ...where.bindings,
         ]);
     }
     async delete() {
         const where = this.whereClause();
-        return conn().write(placeholders(`DELETE FROM ${this.table}${where.sql}`), where.bindings);
+        return this.runWrite(`DELETE FROM ${this.table}${where.sql}`, where.bindings);
     }
 }
-/** Start a query against a table. */
-export function db(table) {
-    return new QueryBuilder(table);
+/** Start a query against a table, on the default connection or a named one. */
+export function db(table, connectionName) {
+    return new QueryBuilder(table, () => resolve(connectionName));
+}
+/**
+ * Get a handle to a named connection (or the default). Use it to run several
+ * queries against one database without repeating the name, or to reach the raw
+ * `select`/`write` bridge.
+ *
+ *   const reporting = connection("reporting");
+ *   await reporting.table("events").where("kind", "signup").count();
+ */
+export function connection(name) {
+    const source = resolve(name);
+    return {
+        table: (t) => new QueryBuilder(t, () => source),
+        select: (sql, bindings = []) => source.conn.select(placeholders(sql, source.dialect), bindings),
+        write: (sql, bindings = []) => source.conn.write(placeholders(sql, source.dialect), bindings),
+        dialect: source.dialect,
+    };
 }

package/dist/core/events.d.ts

@@ -5,17 +5,141 @@
  *
  *   listen("user.registered", (user) => sendWelcome(user));
  *   await emit("user.registered", user);
+ *
+ * Declare an event in `EventsList` and the emitter checks both sides of it —
+ * the payload you fire and the payload your listener receives:
+ *
+ *   declare module "@shaferllc/keel/core" {
+ *     interface EventsList {
+ *       "order.paid": { id: number; total: number };
+ *     }
+ *   }
+ *
+ * One listener's failure never stops another's: `emit` runs them all, then
+ * reports what broke — to `onError()` if you registered one, otherwise by
+ * rejecting.
+ */
+/**
+ * The registry of known events, keyed by name. Empty by default — augment it
+ * from your app to type an event's payload:
+ *
+ *   declare module "@shaferllc/keel/core" {
+ *     interface EventsList {
+ *       "user.registered": User;
+ *     }
+ *   }
+ */
+export interface EventsList {
+}
+/** A declared event name, or any other string. */
+export type EventName = keyof EventsList | (string & {});
+/**
+ * The declared payload for an event, or `unknown` for an undeclared one.
+ *
+ * The `[E]` tuple wrapper stops the conditional from distributing: `EventName`
+ * is itself a union, and a naked `E` would resolve to a *union* of every
+ * declared payload rather than the one event's.
+ */
+export type PayloadOf<E> = [E] extends [keyof EventsList] ? EventsList[E & keyof EventsList] : unknown;
+/**
+ * `emit`'s payload argument. Declared events must be fired with their payload;
+ * undeclared (and void) ones may be fired without.
  */
+export type EmitArgs<P> = [P] extends [void | undefined] ? [payload?: P] : unknown extends P ? [payload?: P] : [payload: P];
+/**
+ * The payload type for an event.
+ *
+ * A **declared** event takes its payload from `EventsList`, and `NoInfer` is
+ * load-bearing there: without it TypeScript would infer the payload type from
+ * the value you pass, so `emit("order.paid", anythingAtAll)` would type-check by
+ * inferring it to whatever you handed over — and the registry would enforce
+ * nothing.
+ *
+ * An **undeclared** event behaves as it always has: the payload type is inferred
+ * from the listener, or given explicitly as `listen<Order>("order.paid", …)`,
+ * and falls back to `unknown`.
+ */
+export type Resolve<T, E> = [E] extends [keyof EventsList] ? NoInfer<EventsList[E & keyof EventsList]> : T;
 export type Listener<T = unknown> = (payload: T) => void | Promise<void>;
+/** A listener for *every* event, as registered by `onAny`. */
+export type AnyListener = (event: string, payload: unknown) => void | Promise<void>;
+/** Called when a listener throws, instead of `emit` rejecting. */
+export type ErrorHandler = (event: string, error: unknown, payload: unknown) => void | Promise<void>;
+/** One recorded emission, as captured by a fake. */
+export interface RecordedEvent {
+    event: string;
+    payload: unknown;
+}
 export declare class Events {
     private listeners;
+    private anyListeners;
+    private errorHandler?;
+    /** Non-null while faking: the events to intercept (`true` = all of them). */
+    private faked?;
+    private buffer?;
     /** Subscribe to an event. Returns an unsubscribe function. */
-    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    on<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Subscribe for a single emission. */
-    once<T = unknown>(event: string, listener: Listener<T>): () => void;
-    off<T = unknown>(event: string, listener: Listener<T>): void;
-    /** Emit an event, awaiting every listener in order. */
-    emit<T = unknown>(event: string, payload?: T): Promise<void>;
+    once<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
+    off<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): void;
+    /**
+     * Subscribe to *every* event — for logging and other cross-cutting concerns.
+     * These run before the event's own listeners. Returns an unsubscribe function.
+     */
+    onAny(listener: AnyListener): () => void;
+    /**
+     * Handle listener failures instead of letting `emit` reject. Without one, an
+     * `emit` whose listeners threw rejects (with an `AggregateError` if more than
+     * one did) — errors are never silently swallowed.
+     */
+    onError(handler: ErrorHandler): void;
+    /**
+     * Emit an event, awaiting every listener in registration order.
+     *
+     * A listener that throws does not stop the others — they all run, and the
+     * failures are reported afterwards. That's the point of an emitter: one
+     * subscriber's bug shouldn't silently cancel an unrelated subscriber's work.
+     */
+    emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
     listenerCount(event: string): number;
     clear(event?: string): void;
+    /** Drop every `onAny` listener and the error handler too. */
+    clearAll(): void;
+    /**
+     * Record emissions instead of running listeners, so a test can assert an event
+     * fired without triggering its side effects. Undo with `restore()`.
+     *
+     *   const events = events().fake();
+     *   await register(user);
+     *   events.assertEmitted("user.registered");
+     *
+     * Pass one or more event names to fake only those — everything else dispatches
+     * for real.
+     */
+    fake(only?: EventName | EventName[]): EventBuffer;
+    /** Stop faking; listeners run for real again. */
+    restore(): void;
+}
+/** What a fake records, plus assertions over it. */
+export declare class EventBuffer {
+    private events;
+    /** @internal — called by `Events.emit` while faking. */
+    record(event: string, payload: unknown): void;
+    /** Every emission recorded so far, in order. */
+    all(): RecordedEvent[];
+    /** The payloads recorded for one event. */
+    payloadsFor<E extends EventName>(event: E): PayloadOf<E>[];
+    /**
+     * Assert the event fired — optionally only counting emissions whose payload
+     * satisfies `predicate`.
+     *
+     *   buffer.assertEmitted("order.paid", (o) => o.total === 4200);
+     */
+    assertEmitted<E extends EventName>(event: E, predicate?: (payload: PayloadOf<E>) => boolean): void;
+    assertNotEmitted<E extends EventName>(event: E): void;
+    assertEmittedCount<E extends EventName>(event: E, expected: number): void;
+    /** Assert nothing at all was emitted. */
+    assertNoneEmitted(): void;
+    private listenerCountFor;
+    private summary;
 }