@udibo/oauth2 0.1.0

package/esm/adapters/hono/bff/session-store.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Session stores used by {@link HonoBff}.
+ *
+ * Two shapes are supported:
+ *
+ * - **Stateful**: the cookie holds a random session id; tokens live in a
+ *   server-side store keyed by that id ({@link MemorySessionStore}, or
+ *   your own DB-backed {@link SessionStore}). Pros: instant revocation,
+ *   tiny cookie, leaked session id is useless outside your server. Cons:
+ *   needs a store to scale horizontally.
+ *
+ * - **Stateless** ({@link EncryptedCookieSessionStore}): the cookie value
+ *   *is* the encrypted token bundle (AES-GCM with a server-held secret),
+ *   no server-side storage needed. Pros: no infrastructure beyond the
+ *   secret. Cons: revocation requires `/revoke` + cookie clear, cookie
+ *   grows with token size, key rotation needs care.
+ *
+ * A raw "token in cookie" store is deliberately **not** shipped: a leaked
+ * log line containing the cookie would yield a working bearer token. The
+ * AES-GCM encryption in the stateless store is what makes that pattern
+ * safe.
+ *
+ * @module
+ */
+import type { TokenBundle, UserInfoClaims } from "../../../client/mod.js";
+/** The data a BFF persists per session. */
+export interface SessionData {
+    /** The current token bundle (access token + expiry + scope + id_token). */
+    tokens: TokenBundle;
+    /** The refresh token, if one was issued. */
+    refreshToken?: string;
+    /**
+     * Cached user claims surfaced by `GET /auth/session` without exposing
+     * tokens to the browser. Populated from the id_token or the userinfo
+     * endpoint at callback time.
+     */
+    user?: UserInfoClaims | null;
+    /**
+     * The OP session id (`sid` claim from the id_token), when present. Used to
+     * target a single session during OIDC Back-Channel Logout; matching falls
+     * back to the subject (`user.sub`) when the logout_token carries no `sid`.
+     */
+    sid?: string;
+    /** When the session was created (epoch ms). */
+    createdAt: number;
+    /** When the session was last updated (epoch ms). */
+    updatedAt: number;
+}
+/**
+ * Optional {@link SessionStore} capability: destroy sessions by subject and/or
+ * OP session id, for an OIDC Back-Channel Logout receiver. A store opts in by
+ * implementing this method (it is duck-typed at runtime). Stateful stores
+ * (server-side records) can; stateless stores (e.g.
+ * {@link EncryptedCookieSessionStore}) cannot enumerate their sessions, so they
+ * omit it and the BFF's `/auth/backchannel` route stays unavailable.
+ */
+export interface BackchannelLogoutStore {
+    /**
+     * Destroy every session matching a validated logout_token. When `sid` is
+     * given, only the session(s) with that OP session id are destroyed; otherwise
+     * all sessions for `sub` are destroyed. Returns the number destroyed. Back a
+     * persistent implementation with an index on `sid`/`sub`.
+     */
+    destroyByLogout(criteria: {
+        sub?: string;
+        sid?: string;
+    }): Promise<number>;
+}
+/** Whether a store implements the {@link BackchannelLogoutStore} capability. */
+export declare function supportsBackchannelLogout(store: SessionStore): store is SessionStore & BackchannelLogoutStore;
+/**
+ * Default session lifetime — 14 days — shared by
+ * {@link EncryptedCookieSessionStore} and `HonoBff`'s
+ * `sessionMaxAgeMs`, so a BFF built with neither configured has a cookie
+ * and a server-side session that expire together.
+ *
+ * Long enough that an app used weekly never nags; short enough that a
+ * credential left on an unattended phone dies on its own. Set both knobs if
+ * your product wants a different window.
+ */
+export declare const DEFAULT_SESSION_MAX_AGE_MS: number;
+/**
+ * Optional {@link SessionStore} capability: the store enforces a maximum
+ * session age, in milliseconds, and says what it is.
+ *
+ * `HonoBff` reads it to refuse a configuration whose session cookie would die
+ * before the sessions this store keeps serving — the pairing that leaves a user
+ * signed out while their session is still listed as active. Expose it from a
+ * DB-backed store to get that check; omit it and the BFF falls back to its own
+ * `sessionMaxAgeMs` bound.
+ */
+export interface BoundedSessionStore {
+    /** Maximum age, in ms, past which this store stops honoring a session. */
+    readonly maxAgeMs: number;
+}
+/**
+ * The maximum session age a store enforces, or `undefined` when it does not
+ * advertise one (see {@link BoundedSessionStore}).
+ */
+export declare function sessionStoreMaxAgeMs(store: SessionStore): number | undefined;
+/**
+ * Session persistence contract for {@link HonoBff}.
+ *
+ * Implementations may be stateful (cookie holds a session id, data lives
+ * server-side) or stateless (cookie holds the encrypted payload itself).
+ * `create` / `update` return the cookie value to set; `read` takes a
+ * cookie value and returns the data (or `null` if the cookie doesn't
+ * correspond to a live session). `destroy` removes a session.
+ */
+export interface SessionStore {
+    /** Create a new session and return the cookie value to set. */
+    create(data: SessionData): Promise<string>;
+    /** Read an existing session's data, or `null` if not found / invalid. */
+    read(cookieValue: string): Promise<SessionData | null>;
+    /**
+     * Update an existing session's data. Returns the new cookie value to
+     * set (may be the same as `cookieValue` for stateful stores; changes
+     * with every update for stateless stores). Stateful implementations must
+     * atomically reject missing, expired or revoked sessions with
+     * `InvalidGrantError`; updating must never create or restore a session.
+     */
+    update(cookieValue: string, data: SessionData): Promise<string>;
+    /** Destroy the session identified by `cookieValue`. */
+    destroy(cookieValue: string): Promise<void>;
+}
+/**
+ * In-memory stateful session store. Data is lost when the process
+ * restarts. Suitable for single-process development or tests; use a
+ * persistent store in production.
+ */
+export declare class MemorySessionStore implements SessionStore, BackchannelLogoutStore {
+    #private;
+    /** Stores the session under a fresh random id and returns it as the cookie value. */
+    create(data: SessionData): Promise<string>;
+    /** Looks up the session by its id, or `null` if no live session matches. */
+    read(cookieValue: string): Promise<SessionData | null>;
+    /** Replaces the stored data in place; the cookie value (session id) is unchanged. */
+    update(cookieValue: string, data: SessionData): Promise<string>;
+    /** Removes the session record for the given id. */
+    destroy(cookieValue: string): Promise<void>;
+    /**
+     * Destroys the sessions a validated logout_token targets: the specific `sid`
+     * when given, otherwise every session for `sub`. Returns the number
+     * destroyed.
+     */
+    destroyByLogout(criteria: {
+        sub?: string;
+        sid?: string;
+    }): Promise<number>;
+}
+/** Options for {@link EncryptedCookieSessionStore}. */
+export interface EncryptedCookieSessionStoreOptions {
+    /**
+     * Server-held secret(s) used to derive the AES-256 key(s). Each must have at
+     * least 32 bytes of entropy; pass a base64 / hex string or raw bytes.
+     *
+     * Pass an **ordered list** to rotate the secret without signing everyone out:
+     * the **first** entry is current — every cookie is sealed under it — and
+     * `read` tries each entry in turn, so a cookie sealed under a still-listed
+     * older secret keeps unsealing. Rotate by deploying `[newSecret, oldSecret]`,
+     * then drop `oldSecret` once the grace window (at least {@linkcode maxAgeMs},
+     * or your longest session lifetime) has elapsed. This is the session-store
+     * analog of a multi-key JWKS grace window. A single secret behaves exactly as
+     * before — a fleet-wide forced sign-out on rotation.
+     */
+    secret: string | Uint8Array | Array<string | Uint8Array>;
+    /**
+     * Maximum age of a sealed cookie, in milliseconds: `read` returns `null` for
+     * any cookie sealed longer ago than this — even if it decrypts — bounding how
+     * long a captured cookie stays useful without any server-side state. This
+     * does **not** make `destroy` real; it only caps the window.
+     *
+     * Defaults to {@link DEFAULT_SESSION_MAX_AGE_MS} (14 days). There is no
+     * unbounded setting: an encrypted bearer cookie nobody can revoke must expire
+     * on its own. Pass a larger value for a longer window, and set the BFF's
+     * `sessionMaxAgeMs` to match — `HonoBff` throws when its session cookie
+     * would die before the sessions this store keeps accepting.
+     *
+     * `update` re-seals with a fresh stamp, so this is an **inactivity** window
+     * for a session the BFF keeps refreshing. Must be a positive number of
+     * milliseconds.
+     *
+     * The store stamps each cookie with a seal time at `create`/`update`; a
+     * pre-rotation cookie sealed before this field existed has no stamp and falls
+     * back to its own `updatedAt`, so old cookies are bounded too rather than
+     * grandfathered as unbounded.
+     */
+    maxAgeMs?: number;
+}
+/**
+ * Stateless session store. The cookie value is the AES-GCM-encrypted
+ * JSON-serialized {@link SessionData}. No server-side storage needed.
+ *
+ * Security notes:
+ * - Each secret must have at least 256 bits of entropy. A weak secret defeats
+ *   the confidentiality of the cookie.
+ * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
+ *   (returns `null`).
+ * - `destroy` is a no-op on the server — the cookie must be cleared in the
+ *   client response for the session to end, and the refresh token should be
+ *   revoked at the authorization server. Genuine server-side revocation is not
+ *   achievable statelessly; choose a DB-backed {@link SessionStore} for that.
+ *   {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs} — 14 days unless
+ *   you set it — bounds the window a captured cookie stays useful but does not
+ *   make `destroy` real.
+ * - Rotate the secret without a fleet-wide sign-out by passing an ordered list;
+ *   see {@linkcode EncryptedCookieSessionStoreOptions.secret}.
+ *
+ * @example Rotating the secret with a grace window
+ * ```ts
+ * // Deploy with the new secret first, the old one second: new cookies seal
+ * // under NEW, cookies still sealed under OLD keep unsealing until you drop it.
+ * const store = new EncryptedCookieSessionStore({
+ *   secret: [Deno.env.get("SESSION_SECRET")!, Deno.env.get("SESSION_SECRET_OLD")!],
+ *   maxAgeMs: 7 * 24 * 60 * 60 * 1000,
+ * });
+ * ```
+ */
+export declare class EncryptedCookieSessionStore implements SessionStore, BoundedSessionStore {
+    #private;
+    /**
+     * Derives each AES-256 key on first use and reuses it for every later
+     * operation. The first secret is current (used to seal); all are tried on
+     * read.
+     *
+     * @throws {Error} When the secret list is empty, or when
+     * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs} is not a positive
+     * finite number of milliseconds.
+     */
+    constructor(options: EncryptedCookieSessionStoreOptions);
+    /**
+     * The maximum age, in ms, past which a sealed cookie stops unsealing.
+     * Defaults to {@link DEFAULT_SESSION_MAX_AGE_MS}; `HonoBff` reads it to
+     * check that its session cookie outlives the sessions this store accepts.
+     */
+    get maxAgeMs(): number;
+    /** Encrypts the session into the cookie value under the current secret; there is no server-side record. */
+    create(data: SessionData): Promise<string>;
+    /**
+     * Decrypts the cookie value, trying each configured secret in turn. Returns
+     * `null` if it is tampered, malformed, sealed with an unknown secret, or
+     * sealed longer ago than
+     * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
+     */
+    read(cookieValue: string): Promise<SessionData | null>;
+    /** Re-encrypts the data into a fresh cookie value under the current secret. */
+    update(_cookieValue: string, data: SessionData): Promise<string>;
+    /** Stateless — the server has nothing to destroy. The caller must clear the cookie. */
+    destroy(_cookieValue: string): Promise<void>;
+}

package/esm/adapters/hono/bff/session-store.js

@@ -0,0 +1,216 @@
+/**
+ * Session stores used by {@link HonoBff}.
+ *
+ * Two shapes are supported:
+ *
+ * - **Stateful**: the cookie holds a random session id; tokens live in a
+ *   server-side store keyed by that id ({@link MemorySessionStore}, or
+ *   your own DB-backed {@link SessionStore}). Pros: instant revocation,
+ *   tiny cookie, leaked session id is useless outside your server. Cons:
+ *   needs a store to scale horizontally.
+ *
+ * - **Stateless** ({@link EncryptedCookieSessionStore}): the cookie value
+ *   *is* the encrypted token bundle (AES-GCM with a server-held secret),
+ *   no server-side storage needed. Pros: no infrastructure beyond the
+ *   secret. Cons: revocation requires `/revoke` + cookie clear, cookie
+ *   grows with token size, key rotation needs care.
+ *
+ * A raw "token in cookie" store is deliberately **not** shipped: a leaked
+ * log line containing the cookie would yield a working bearer token. The
+ * AES-GCM encryption in the stateless store is what makes that pattern
+ * safe.
+ *
+ * @module
+ */
+import { InvalidGrantError } from "../../../errors.js";
+import { deriveAesKey, sealJson, unsealJson } from "../../../utils/crypto.js";
+/** Whether a store implements the {@link BackchannelLogoutStore} capability. */
+export function supportsBackchannelLogout(store) {
+    return typeof store.destroyByLogout ===
+        "function";
+}
+/**
+ * Default session lifetime — 14 days — shared by
+ * {@link EncryptedCookieSessionStore} and `HonoBff`'s
+ * `sessionMaxAgeMs`, so a BFF built with neither configured has a cookie
+ * and a server-side session that expire together.
+ *
+ * Long enough that an app used weekly never nags; short enough that a
+ * credential left on an unattended phone dies on its own. Set both knobs if
+ * your product wants a different window.
+ */
+export const DEFAULT_SESSION_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * The maximum session age a store enforces, or `undefined` when it does not
+ * advertise one (see {@link BoundedSessionStore}).
+ */
+export function sessionStoreMaxAgeMs(store) {
+    const maxAgeMs = store.maxAgeMs;
+    return typeof maxAgeMs === "number" && Number.isFinite(maxAgeMs)
+        ? maxAgeMs
+        : undefined;
+}
+/**
+ * In-memory stateful session store. Data is lost when the process
+ * restarts. Suitable for single-process development or tests; use a
+ * persistent store in production.
+ */
+export class MemorySessionStore {
+    #sessions = new Map();
+    /** Stores the session under a fresh random id and returns it as the cookie value. */
+    create(data) {
+        const id = crypto.randomUUID();
+        this.#sessions.set(id, data);
+        return Promise.resolve(id);
+    }
+    /** Looks up the session by its id, or `null` if no live session matches. */
+    read(cookieValue) {
+        return Promise.resolve(this.#sessions.get(cookieValue) ?? null);
+    }
+    /** Replaces the stored data in place; the cookie value (session id) is unchanged. */
+    update(cookieValue, data) {
+        if (!this.#sessions.has(cookieValue)) {
+            return Promise.reject(new InvalidGrantError("session is no longer active"));
+        }
+        this.#sessions.set(cookieValue, data);
+        return Promise.resolve(cookieValue);
+    }
+    /** Removes the session record for the given id. */
+    destroy(cookieValue) {
+        this.#sessions.delete(cookieValue);
+        return Promise.resolve();
+    }
+    /**
+     * Destroys the sessions a validated logout_token targets: the specific `sid`
+     * when given, otherwise every session for `sub`. Returns the number
+     * destroyed.
+     */
+    destroyByLogout(criteria) {
+        const { sub, sid } = criteria;
+        let destroyed = 0;
+        for (const [id, data] of this.#sessions) {
+            const match = sid !== undefined
+                ? data.sid === sid
+                : sub !== undefined && data.user?.sub === sub;
+            if (match) {
+                this.#sessions.delete(id);
+                destroyed++;
+            }
+        }
+        return Promise.resolve(destroyed);
+    }
+}
+function isSealedSession(value) {
+    return typeof value === "object" && value !== null &&
+        typeof value.issuedAt === "number" &&
+        typeof value.data === "object" &&
+        value.data !== null;
+}
+/**
+ * Stateless session store. The cookie value is the AES-GCM-encrypted
+ * JSON-serialized {@link SessionData}. No server-side storage needed.
+ *
+ * Security notes:
+ * - Each secret must have at least 256 bits of entropy. A weak secret defeats
+ *   the confidentiality of the cookie.
+ * - AES-GCM provides authenticated encryption; tampered cookies fail `read`
+ *   (returns `null`).
+ * - `destroy` is a no-op on the server — the cookie must be cleared in the
+ *   client response for the session to end, and the refresh token should be
+ *   revoked at the authorization server. Genuine server-side revocation is not
+ *   achievable statelessly; choose a DB-backed {@link SessionStore} for that.
+ *   {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs} — 14 days unless
+ *   you set it — bounds the window a captured cookie stays useful but does not
+ *   make `destroy` real.
+ * - Rotate the secret without a fleet-wide sign-out by passing an ordered list;
+ *   see {@linkcode EncryptedCookieSessionStoreOptions.secret}.
+ *
+ * @example Rotating the secret with a grace window
+ * ```ts
+ * // Deploy with the new secret first, the old one second: new cookies seal
+ * // under NEW, cookies still sealed under OLD keep unsealing until you drop it.
+ * const store = new EncryptedCookieSessionStore({
+ *   secret: [Deno.env.get("SESSION_SECRET")!, Deno.env.get("SESSION_SECRET_OLD")!],
+ *   maxAgeMs: 7 * 24 * 60 * 60 * 1000,
+ * });
+ * ```
+ */
+export class EncryptedCookieSessionStore {
+    #secrets;
+    #keyPromises;
+    #maxAgeMs;
+    /**
+     * Derives each AES-256 key on first use and reuses it for every later
+     * operation. The first secret is current (used to seal); all are tried on
+     * read.
+     *
+     * @throws {Error} When the secret list is empty, or when
+     * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs} is not a positive
+     * finite number of milliseconds.
+     */
+    constructor(options) {
+        const secrets = Array.isArray(options.secret)
+            ? options.secret
+            : [options.secret];
+        if (secrets.length === 0) {
+            throw new Error("secret must not be an empty list.");
+        }
+        const maxAgeMs = options.maxAgeMs ?? DEFAULT_SESSION_MAX_AGE_MS;
+        if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0) {
+            throw new Error("maxAgeMs must be a positive number of milliseconds, got " +
+                `${options.maxAgeMs}. A cookie nobody can revoke has to expire on ` +
+                "its own; pass a larger value for a longer window.");
+        }
+        this.#secrets = secrets;
+        this.#keyPromises = secrets.map(() => undefined);
+        this.#maxAgeMs = maxAgeMs;
+    }
+    /**
+     * The maximum age, in ms, past which a sealed cookie stops unsealing.
+     * Defaults to {@link DEFAULT_SESSION_MAX_AGE_MS}; `HonoBff` reads it to
+     * check that its session cookie outlives the sessions this store accepts.
+     */
+    get maxAgeMs() {
+        return this.#maxAgeMs;
+    }
+    #key(index) {
+        return this.#keyPromises[index] ??= deriveAesKey(this.#secrets[index]);
+    }
+    /** Encrypts the session into the cookie value under the current secret; there is no server-side record. */
+    async create(data) {
+        const sealed = { issuedAt: Date.now(), data };
+        return await sealJson(await this.#key(0), sealed);
+    }
+    /**
+     * Decrypts the cookie value, trying each configured secret in turn. Returns
+     * `null` if it is tampered, malformed, sealed with an unknown secret, or
+     * sealed longer ago than
+     * {@linkcode EncryptedCookieSessionStoreOptions.maxAgeMs}.
+     */
+    async read(cookieValue) {
+        for (let index = 0; index < this.#secrets.length; index++) {
+            const unsealed = await unsealJson(await this.#key(index), cookieValue);
+            if (unsealed === null)
+                continue;
+            if (isSealedSession(unsealed)) {
+                return this.#isExpired(unsealed.issuedAt) ? null : unsealed.data;
+            }
+            const legacy = unsealed;
+            return this.#isExpired(legacy.updatedAt ?? legacy.createdAt)
+                ? null
+                : legacy;
+        }
+        return null;
+    }
+    #isExpired(issuedAt) {
+        return Date.now() - issuedAt > this.#maxAgeMs;
+    }
+    /** Re-encrypts the data into a fresh cookie value under the current secret. */
+    update(_cookieValue, data) {
+        return this.create(data);
+    }
+    /** Stateless — the server has nothing to destroy. The caller must clear the cookie. */
+    destroy(_cookieValue) {
+        return Promise.resolve();
+    }
+}

package/esm/adapters/hono/bff/testing.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Testing helpers for the Hono BFF adapter.
+ *
+ * Lets a consumer's tests drive protected endpoints without walking
+ * through the full login → authorize → callback flow, and ages the
+ * access token in the underlying {@link SessionStore} so a follow-up
+ * request through `attachToken()` exercises the refresh path
+ * deterministically (no `setTimeout` required).
+ *
+ * The runner-style helper {@link runSessionStoreContractTests} is
+ * available for verifying custom {@link SessionStore} implementations
+ * (Postgres, Redis, DynamoDB, …) satisfy the create / read / update /
+ * destroy contract.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+import type { ClientInterface } from "../../../models/client.js";
+import type { AbstractScope } from "../../../models/scope.js";
+import type { TokenServiceInterface } from "../../../server/services/token.js";
+import type { TokenBundle, UserInfoClaims } from "../../../client/mod.js";
+import type { HonoBff } from "./bff.js";
+import { type SessionData, type SessionStore } from "./session-store.js";
+/** Options for {@link createTestSession}. */
+export interface CreateTestSessionOptions {
+    /**
+     * Token bundle to install. Anything you don't supply gets a sensible
+     * default (random access token, expires in 1 hour, no refresh token).
+     */
+    tokens?: Partial<TokenBundle>;
+    /** Refresh token to store alongside the bundle. */
+    refreshToken?: string;
+    /** Cached user claims surfaced by `GET /auth/session`. */
+    user?: UserInfoClaims | null;
+    /** Override `createdAt` (epoch ms). Defaults to now. */
+    createdAt?: number;
+    /** Override `updatedAt` (epoch ms). Defaults to now. */
+    updatedAt?: number;
+}
+/**
+ * Seeds a session in `bff.sessionStore` and returns a `Cookie` header
+ * value (`<name>=<value>`) ready to attach to subsequent
+ * `app.request(...)` calls. Skips the authorize / callback round-trip
+ * entirely — useful for tests that only care about authenticated
+ * endpoint behavior.
+ *
+ * **Important — token recognition.** The seeded access token is random by
+ * default and is NOT registered with any resource server. That is enough for
+ * `GET /auth/session` (which reads the cached `user` claim), but a route
+ * guarded by {@link HonoBff.protect} validates the session's access token
+ * against the resource server's token service — so an unrecognized token
+ * yields 401. For protected API routes, either pre-register the token
+ * (`tokenService.save({ accessToken, ... })` then pass the same
+ * `tokens.accessToken` here), or use {@link createAuthenticatedTestSession},
+ * which does both in one call.
+ *
+ * @example
+ * ```ts
+ * // Probe-only (GET /auth/session) — no resource server involved:
+ * const cookie = await createTestSession(bff, {
+ *   user: { sub: "u1", name: "Alice" },
+ * });
+ * const res = await app.request("/auth/session", { headers: { cookie } });
+ * ```
+ */
+export declare function createTestSession(bff: HonoBff, options?: CreateTestSessionOptions): Promise<string>;
+/** Options for {@link createAuthenticatedTestSession}. */
+export interface CreateAuthenticatedTestSessionOptions<Client extends ClientInterface, User, Scope extends AbstractScope> {
+    /**
+     * The resource server's token service. The minted access token is saved
+     * here so {@link HonoBff.protect} recognizes it — pass the SAME token
+     * service the BFF's resource server validates against.
+     */
+    tokenService: TokenServiceInterface<Client, User, Scope>;
+    /** Client the token is issued to. */
+    client: Client;
+    /** User the token is issued for. */
+    user?: User;
+    /** Scope granted to the token (drives `protect("scope")` checks). */
+    scope?: Scope;
+    /** Access-token lifetime in seconds. Defaults to one hour. */
+    accessTokenLifetime?: number;
+    /** Cached user claims surfaced by `GET /auth/session`. Defaults to null. */
+    claims?: UserInfoClaims | null;
+}
+/**
+ * Mints a real access token, registers it with the resource server's token
+ * service, AND seeds a matching BFF session — the one-call setup for testing a
+ * route guarded by {@link HonoBff.protect}. Returns a `Cookie` header ready to
+ * attach to `app.request(...)`.
+ *
+ * This is the combined form of the two-step pattern (save a token, then
+ * {@link createTestSession} with the same access token) that protected-route
+ * tests otherwise hand-roll. Works with any {@link SessionStore} the BFF can
+ * `create()` into (e.g. `MemorySessionStore`,
+ * `EncryptedCookieSessionStore`); apps with a DB-backed store that mints
+ * its own cookie/secret should seed via that store directly.
+ *
+ * @example
+ * ```ts
+ * const cookie = await createAuthenticatedTestSession(bff, {
+ *   tokenService,
+ *   client: { id: "spa" },
+ *   user: { id: "u1", username: "alice" },
+ *   scope: new BasicScope("read write"),
+ *   claims: { sub: "u1", name: "Alice" },
+ * });
+ * const res = await app.request("/api/me", { headers: { cookie } });
+ * ```
+ */
+export declare function createAuthenticatedTestSession<Client extends ClientInterface, User, Scope extends AbstractScope>(bff: HonoBff, options: CreateAuthenticatedTestSessionOptions<Client, User, Scope>): Promise<string>;
+/**
+ * Ages the access token in the underlying session so the next request
+ * through {@link HonoBff.attachToken} sees it as expired and triggers
+ * the refresh path.
+ *
+ * Returns a fresh `Cookie` header. For stateful stores
+ * (`MemorySessionStore` and DB-backed variants) the cookie value
+ * is unchanged. For stateless stores
+ * (`EncryptedCookieSessionStore`) the value is re-encrypted and
+ * differs from the input — use the returned header for subsequent
+ * requests.
+ *
+ * @param expiredAt Optional time to set the access token's expiry to
+ * (epoch ms). Defaults to one second in the past.
+ */
+export declare function forceTokenExpiry(bff: HonoBff, cookieHeader: string, expiredAt?: number): Promise<string>;
+/**
+ * Returns the session data currently stored under the given cookie
+ * header, or `null` if there is none. Convenience wrapper around
+ * `bff.sessionStore.read` that handles cookie parsing.
+ */
+export declare function readTestSession(bff: HonoBff, cookieHeader: string): Promise<SessionData | null>;
+/** Options for {@link runSessionStoreContractTests}. */
+export interface SessionStoreContractOptions {
+    /** Returns a fresh, empty store for each test. */
+    makeStore(): Promise<SessionStore> | SessionStore;
+    /**
+     * Some stateless stores (`EncryptedCookieSessionStore`) cannot
+     * distinguish "session destroyed" from "session never existed" —
+     * destroy is a no-op on the server, with the cookie clear happening on
+     * the client side. Set this to `false` to skip the post-destroy
+     * `read` returns null assertion.
+     */
+    destroyClearsRead?: boolean;
+    /** Label for the generated `describe` block. Defaults to `"SessionStore contract"`. */
+    describeName?: string;
+    /**
+     * Returns a store bound to the given maximum session age, in milliseconds.
+     * Supply it whenever your store enforces an age bound — the suite builds a
+     * store with a one-second bound, waits it out, and requires `read` to stop
+     * returning the session. One second is whole-second-expressible, so a store
+     * whose TTL column or `EXPIRE` call has second resolution can honor it
+     * exactly.
+     *
+     * `HonoBff` trusts the `maxAgeMs` a store advertises when it refuses a
+     * configuration whose session cookie would expire before the store stops
+     * honoring the session. A store that advertises a bound it does not enforce
+     * defeats that check, so the suite fails a store that advertises one without
+     * supplying this factory.
+     */
+    makeBoundedStore?(maxAgeMs: number): Promise<SessionStore> | SessionStore;
+}
+/** Contract test suite for {@link SessionStore} implementations. */
+export declare function runSessionStoreContractTests(options: SessionStoreContractOptions): void;