@stonyx/oauth 0.1.1-alpha.3 → 0.1.1-alpha.30

package/dist/main.d.ts

@@ -0,0 +1,121 @@
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
+import type { RedeemedTicket } from './ticket-store.js';
+import type { SessionResult } from './session-manager.js';
+import type OAuthFlow from './oauth-flow.js';
+/** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
+export declare const STATE_TTL_MS: number;
+/** Entropy of the client-held binding value, in bytes. */
+export declare const BINDING_VALUE_BYTES = 32;
+interface ProviderEntry {
+    flow: OAuthFlow;
+    tokenManager: TokenManager;
+}
+/**
+ * A flow that is in progress.
+ *
+ * Holds a *digest* of the binding value rather than the value itself: a
+ * callback is only accepted when the caller presents the plaintext that hashes
+ * to `bindingHash`, so the record on its own unlocks nothing.
+ */
+export interface PendingState {
+    bindingHash: string;
+    createdAt: number;
+}
+export interface IssuedState {
+    /** Sent to the provider as the OAuth2 `state` parameter. */
+    url: string;
+    /** Retained so a login that cannot be bound can withdraw its own state. */
+    stateToken: string;
+    /** Held by the client that started the flow, never by the provider. */
+    bindingValue: string;
+}
+export default class OAuth {
+    static instance: OAuth | null;
+    providers: Map<string, ProviderEntry>;
+    pendingStates: Map<string, PendingState>;
+    stateTtl: number;
+    sessionManager: SessionManager;
+    ticketStore: TicketStore;
+    frontendCallbackUrl?: string;
+    constructor();
+    init(): Promise<void>;
+    getProvider(name: string): ProviderEntry;
+    /**
+     * SHA-256 of a binding value, hex encoded.
+     *
+     * The pending record stores the digest so that read access to the map does
+     * not hand over the value a callback must present.
+     */
+    static hash(value: string): string;
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a: string, b: string): boolean;
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Stopping at the first value carrying the cookie's name instead makes a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. And
+     * the candidate list is deliberately uncapped — a cap does not bound an
+     * attack, it *is* one, reinstating that denial above its own threshold
+     * because the planted cookies are the ones that sort first. The work is
+     * already bounded by Node's 16 KB header limit.
+     *
+     * The reduce does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    static anyCandidateMatches(candidates: readonly string[], bindingHash: string): boolean;
+    /**
+     * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+     * the client that asked for it.
+     *
+     * `state` on its own is replay-window limiting, not the CSRF binding it
+     * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+     * state issued to any visitor validated for any callback, so an attacker
+     * could harvest their own state and code, deliver them to a victim over a
+     * plain link, and log the victim into the attacker's account. The binding
+     * value is the thing the victim's browser carries and the attacker's does
+     * not (#36).
+     */
+    getAuthorizationUrl(providerName: string): IssuedState;
+    /**
+     * Withdraws a state that was issued but could not be handed to a client.
+     *
+     * Used by the login route when the binding cookie cannot be set: a state the
+     * client cannot be bound to is exactly the defect this mechanism exists to
+     * prevent, so it must not outlive the request that failed to bind it.
+     */
+    discardState(stateToken: string): void;
+    /**
+     * Validates and consumes a pending state, then completes the flow.
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name — see `anyCandidateMatches`.
+     */
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<SessionResult>;
+    /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+    redirectUriFor(providerName: string): string | undefined;
+    /**
+     * Mints the value the callback redirect is allowed to put in a URL (#45).
+     *
+     * The session id never travels in the redirect. What travels is a ticket
+     * that is single-use, expires in 60 seconds, and authenticates nothing on
+     * its own — `GET /auth` validates against `sessionManager`, which has never
+     * heard of it.
+     */
+    issueExchangeTicket(session: SessionResult): string;
+    /** Spends a ticket for the session id it stands for, or `null`. */
+    redeemExchangeTicket(ticket: string): RedeemedTicket | null;
+    getSession(sessionId: string): unknown;
+    logout(sessionId: string): void;
+}
+export {};

package/dist/main.js

@@ -0,0 +1,194 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { waitForModule } from 'stonyx';
+import { setup, emit } from '@stonyx/events';
+import RestServer from '@stonyx/rest-server';
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
+import AuthRequest from './auth-request.js';
+setup(['authenticate']);
+/** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
+export const STATE_TTL_MS = 10 * 60 * 1000;
+/** Entropy of the client-held binding value, in bytes. */
+export const BINDING_VALUE_BYTES = 32;
+export default class OAuth {
+    static instance;
+    providers = new Map();
+    pendingStates = new Map();
+    stateTtl = STATE_TTL_MS;
+    sessionManager;
+    ticketStore = new TicketStore();
+    frontendCallbackUrl;
+    constructor() {
+        if (OAuth.instance)
+            return OAuth.instance;
+        OAuth.instance = this;
+    }
+    async init() {
+        // Self-register so log.oauth works even when @stonyx/oauth is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'magenta', logMethod = 'oauth' } = config.oauth;
+        log.defineType(logMethod, logColor);
+        const oauthConfig = config.oauth;
+        const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
+        this.frontendCallbackUrl = frontendCallbackUrl;
+        for (const [name, providerConfig] of Object.entries(providers)) {
+            const modulePath = providerConfig.module
+                ? `${config.rootPath}/${providerConfig.module}`
+                : `./providers/${name}.js`;
+            const { default: Provider } = await import(modulePath);
+            const flow = new Provider(providerConfig);
+            this.providers.set(name, { flow, tokenManager: new TokenManager(flow) });
+        }
+        this.sessionManager = new SessionManager(sessionDuration);
+        await waitForModule('rest-server');
+        RestServer.instance.mountRoute(AuthRequest, { name: 'auth', options: this });
+        log.oauth?.('OAuth module initialized');
+    }
+    getProvider(name) {
+        const provider = this.providers.get(name);
+        if (!provider)
+            throw new Error(`OAuth provider "${name}" is not configured`);
+        return provider;
+    }
+    /**
+     * SHA-256 of a binding value, hex encoded.
+     *
+     * The pending record stores the digest so that read access to the map does
+     * not hand over the value a callback must present.
+     */
+    static hash(value) {
+        return createHash('sha256').update(value).digest('hex');
+    }
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a, b) {
+        if (a.length !== b.length)
+            return false;
+        let difference = 0;
+        for (let index = 0; index < a.length; index++) {
+            difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+        }
+        return difference === 0;
+    }
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Stopping at the first value carrying the cookie's name instead makes a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. And
+     * the candidate list is deliberately uncapped — a cap does not bound an
+     * attack, it *is* one, reinstating that denial above its own threshold
+     * because the planted cookies are the ones that sort first. The work is
+     * already bounded by Node's 16 KB header limit.
+     *
+     * The reduce does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    static anyCandidateMatches(candidates, bindingHash) {
+        return candidates.reduce((matched, candidate) => OAuth.digestsMatch(OAuth.hash(candidate), bindingHash) || matched, false);
+    }
+    /**
+     * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+     * the client that asked for it.
+     *
+     * `state` on its own is replay-window limiting, not the CSRF binding it
+     * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+     * state issued to any visitor validated for any callback, so an attacker
+     * could harvest their own state and code, deliver them to a victim over a
+     * plain link, and log the victim into the attacker's account. The binding
+     * value is the thing the victim's browser carries and the attacker's does
+     * not (#36).
+     */
+    getAuthorizationUrl(providerName) {
+        const { flow } = this.getProvider(providerName);
+        const stateToken = randomUUID();
+        const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+        this.pendingStates.set(stateToken, {
+            bindingHash: OAuth.hash(bindingValue),
+            createdAt: Date.now(),
+        });
+        return { url: flow.buildAuthorizationUrl(stateToken), stateToken, bindingValue };
+    }
+    /**
+     * Withdraws a state that was issued but could not be handed to a client.
+     *
+     * Used by the login route when the binding cookie cannot be set: a state the
+     * client cannot be bound to is exactly the defect this mechanism exists to
+     * prevent, so it must not outlive the request that failed to bind it.
+     */
+    discardState(stateToken) {
+        this.pendingStates.delete(stateToken);
+    }
+    /**
+     * Validates and consumes a pending state, then completes the flow.
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name — see `anyCandidateMatches`.
+     */
+    async handleCallback(providerName, code, stateToken, bindingValues) {
+        const record = stateToken ? this.pendingStates.get(stateToken) : undefined;
+        if (!record)
+            throw new Error('Invalid or missing state token');
+        // Consumed on recognition, before the TTL and binding checks, so every
+        // state gets exactly one attempt whatever the outcome. Checking the
+        // binding first would leave the record in place on a mismatch and turn
+        // this endpoint into a repeatable, unauthenticated oracle against the
+        // binding value for the state's full lifetime.
+        this.pendingStates.delete(stateToken);
+        if (Date.now() - record.createdAt > this.stateTtl) {
+            throw new Error('State token has expired');
+        }
+        // No "absent means skip". An empty candidate list is a rejection, which is
+        // what makes an attacker-delivered link fail for a victim who never
+        // started the flow and therefore holds no binding cookie.
+        const candidates = bindingValues.filter(value => value.length > 0);
+        if (candidates.length === 0)
+            throw new Error('Missing state binding value');
+        if (!OAuth.anyCandidateMatches(candidates, record.bindingHash)) {
+            throw new Error('State token is not bound to this client');
+        }
+        // Everything below burns a live authorization code, so the binding is
+        // settled before `exchangeCode` is ever reached.
+        const { flow, tokenManager } = this.getProvider(providerName);
+        const tokens = await tokenManager.getTokens(code);
+        const rawUser = await flow.fetchUserInfo(tokens.accessToken);
+        const user = flow.normalizeUser(rawUser);
+        await emit('authenticate', user);
+        return this.sessionManager.create(user, tokens);
+    }
+    /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+    redirectUriFor(providerName) {
+        return this.providers.get(providerName)?.flow.redirectUri;
+    }
+    /**
+     * Mints the value the callback redirect is allowed to put in a URL (#45).
+     *
+     * The session id never travels in the redirect. What travels is a ticket
+     * that is single-use, expires in 60 seconds, and authenticates nothing on
+     * its own — `GET /auth` validates against `sessionManager`, which has never
+     * heard of it.
+     */
+    issueExchangeTicket(session) {
+        return this.ticketStore.issue(session.sessionId, session.expiresAt);
+    }
+    /** Spends a ticket for the session id it stands for, or `null`. */
+    redeemExchangeTicket(ticket) {
+        return this.ticketStore.redeem(ticket);
+    }
+    getSession(sessionId) {
+        return this.sessionManager.validate(sessionId);
+    }
+    logout(sessionId) {
+        this.sessionManager.destroy(sessionId);
+    }
+}

package/dist/oauth-flow.d.ts

@@ -0,0 +1,30 @@
+export interface OAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+}
+export interface TokenResult {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresIn: number;
+}
+export default class OAuthFlow {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }: OAuthConfig);
+    buildAuthorizationUrl(stateToken: string): string;
+    exchangeCode(code: string): Promise<TokenResult>;
+    refreshAccessToken(refreshToken: string): Promise<TokenResult>;
+    fetchUserInfo(accessToken: string): Promise<unknown>;
+    normalizeUser(rawUser: unknown): unknown;
+    revokeToken(_accessToken: string): Promise<void>;
+}

package/dist/oauth-flow.js

@@ -0,0 +1,83 @@
+export default class OAuthFlow {
+    clientId;
+    clientSecret;
+    redirectUri;
+    scopes;
+    authorizationUrl;
+    tokenUrl;
+    userInfoUrl;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.redirectUri = redirectUri;
+        this.scopes = scopes || [];
+        this.authorizationUrl = authorizationUrl;
+        this.tokenUrl = tokenUrl;
+        this.userInfoUrl = userInfoUrl;
+    }
+    buildAuthorizationUrl(stateToken) {
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: this.scopes.join(' '),
+            state: stateToken,
+        });
+        return `${this.authorizationUrl}?${params.toString()}`;
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    async refreshAccessToken(refreshToken) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token refresh failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || refreshToken,
+            expiresIn: data.expires_in,
+        };
+    }
+    async fetchUserInfo(accessToken) {
+        const response = await fetch(this.userInfoUrl, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!response.ok)
+            throw new Error(`User info fetch failed: ${response.status}`);
+        return response.json();
+    }
+    normalizeUser(rawUser) {
+        return { raw: rawUser };
+    }
+    async revokeToken(_accessToken) {
+        // Optional — providers override if supported
+    }
+}

package/dist/providers/discord.d.ts

@@ -0,0 +1,30 @@
+import OAuthFlow from '../oauth-flow.js';
+import type { TokenResult } from '../oauth-flow.js';
+interface DiscordProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    [key: string]: unknown;
+}
+interface DiscordUser {
+    id: string;
+    username: string;
+    global_name?: string;
+    avatar: string | null;
+    email?: string | null;
+}
+interface NormalizedDiscordUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatar: string | null;
+    email: string | null;
+    raw: DiscordUser;
+}
+export default class DiscordProvider extends OAuthFlow {
+    constructor(config: DiscordProviderConfig);
+    exchangeCode(code: string): Promise<TokenResult>;
+    normalizeUser(rawUser: DiscordUser): NormalizedDiscordUser;
+}
+export {};

package/dist/providers/discord.js

@@ -0,0 +1,43 @@
+import OAuthFlow from '../oauth-flow.js';
+export default class DiscordProvider extends OAuthFlow {
+    constructor(config) {
+        super({
+            ...config,
+            authorizationUrl: 'https://discord.com/oauth2/authorize',
+            tokenUrl: 'https://discord.com/api/oauth2/token',
+            userInfoUrl: 'https://discord.com/api/users/@me',
+        });
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    normalizeUser(rawUser) {
+        const { id, username, global_name, avatar, email } = rawUser;
+        return {
+            id,
+            username,
+            displayName: global_name || username,
+            avatar: avatar ? `https://cdn.discordapp.com/avatars/${id}/${avatar}.png` : null,
+            email: email || null,
+            raw: rawUser,
+        };
+    }
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,20 @@
+interface SessionData {
+    user: unknown;
+    tokens: unknown;
+    expiresAt: number;
+}
+export interface SessionResult {
+    sessionId: string;
+    user: unknown;
+    expiresAt: number;
+}
+export default class SessionManager {
+    sessions: Map<string, SessionData>;
+    duration: number;
+    constructor(duration: number);
+    create(user: unknown, tokens: unknown): SessionResult;
+    get(sessionId: string): SessionData | null;
+    destroy(sessionId: string): void;
+    validate(sessionId: string): unknown;
+}
+export {};

package/dist/session-manager.js

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+export default class SessionManager {
+    sessions = new Map();
+    duration;
+    constructor(duration) {
+        this.duration = duration;
+    }
+    create(user, tokens) {
+        const sessionId = randomUUID();
+        const expiresAt = Date.now() + (this.duration * 1000);
+        this.sessions.set(sessionId, { user, tokens, expiresAt });
+        return { sessionId, user, expiresAt };
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId) || null;
+    }
+    destroy(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    validate(sessionId) {
+        const session = this.get(sessionId);
+        if (!session)
+            return null;
+        if (Date.now() >= session.expiresAt) {
+            this.destroy(sessionId);
+            return null;
+        }
+        return session.user;
+    }
+}

package/dist/ticket-store.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Lifetime of an exchange ticket.
+ *
+ * Sized for one redirect plus one page load, and deliberately two orders of
+ * magnitude tighter than the 10-minute state TTL: the ticket is a bearer value
+ * travelling in a URL, and the whole point of #45 is that a bearer value in a
+ * URL must not be long-lived — in the fragment, so it reaches no server, but
+ * still into browser history and readable by scripts on the landing page.
+ */
+export declare const TICKET_TTL_MS: number;
+/** Entropy of a ticket, in bytes. */
+export declare const TICKET_BYTES = 32;
+interface TicketRecord {
+    sessionId: string;
+    expiresAt: number;
+    createdAt: number;
+}
+export interface RedeemedTicket {
+    sessionId: string;
+    expiresAt: number;
+}
+/**
+ * Single-use, short-lived tickets that stand in for a session id on the wire.
+ *
+ * The callback redirect hands the browser a ticket instead of the session id
+ * (#45), in the URL *fragment*, which no user agent transmits to any server.
+ * The ticket authenticates nothing — `GET /auth` reads the `session-id` header
+ * and knows only about `SessionManager` — so a ticket observed in history or
+ * by a script reading `location.hash` is worth something only inside the
+ * sub-second window before the landing page redeems it, and nothing at all
+ * afterwards.
+ *
+ * Known residual, stated rather than papered over: a ticket observed *within*
+ * that window is redeemable by the observer, because nothing here binds a
+ * ticket to the client that started the flow. Closing it means binding the way
+ * #36 bound the state, and that binding has to travel on a cookie the
+ * cross-origin exchange cannot carry.
+ *
+ * The blocker is `abofs/stonyx-rest-server#63`: `@stonyx/rest-server` calls
+ * `cors({ origin, methods })` and has no `credentials` support at all. It is
+ * *not* `abofs/stonyx-rest-server#45` — that issue is the response-header half
+ * and is already worked around in `auth-request.ts`, which sets and clears the
+ * binding cookie on a redirect by reaching through `req.res`. Closing #45
+ * would not make this residual closeable. It is a reduction, not an
+ * elimination.
+ *
+ * Like `OAuth.pendingStates`, an abandoned ticket is never collected. That is
+ * a pre-existing pattern in this module, not something this store introduces,
+ * and it is bounded here by a 60-second TTL rather than a 10-minute one.
+ * Tracked, with both maps named, at `abofs/stonyx-oauth#43`.
+ *
+ * ---
+ *
+ * **Why this is a second store rather than a reuse of `OAuth.pendingStates`.**
+ *
+ * The duplication is real and is not an oversight: `pendingStates` is also a
+ * single-use, TTL-bounded, consume-on-recognition map keyed by a
+ * `randomBytes`-minted opaque token, with the same delete-before-TTL-check
+ * ordering and the same never-collected caveat. The shared shape could be
+ * extracted into one primitive, and the two constants homes (`STATE_TTL_MS`
+ * and `BINDING_VALUE_BYTES` in `main.ts`, `TICKET_TTL_MS` and `TICKET_BYTES`
+ * here) could then live together.
+ *
+ * It is deliberately not done in the change that fixes #45. Widening a
+ * security fix into a refactor of the CSRF store means the #36 binding
+ * mechanism — whose invariants are load-bearing and separately guarded — moves
+ * in the same commit as the fix, for no security gain in either. The two also
+ * do not have the same invariants: `pendingStates` is a security control fed
+ * by an unauthenticated `GET`, holding a *digest* of a client secret, with a
+ * 10-minute budget sized for a provider round trip; this is a delivery
+ * convenience reachable only after a successfully bound callback, holding a
+ * value it hands back, with a 60-second budget sized for a page load.
+ * Collapsing them would couple the control to the convenience.
+ *
+ * The extraction is tracked at `abofs/stonyx-oauth#58`.
+ */
+export default class TicketStore {
+    tickets: Map<string, TicketRecord>;
+    ttl: number;
+    /**
+     * Mints a ticket for a freshly created session.
+     *
+     * The ticket is independent entropy, never a transform of the session id:
+     * anything derived from the credential is the credential.
+     */
+    issue(sessionId: string, expiresAt: number): string;
+    /**
+     * Spends a ticket, if it is live.
+     *
+     * Consumed on recognition, *before* the TTL check, for the same reason
+     * `OAuth.handleCallback` consumes a pending state before validating its
+     * binding: every ticket gets exactly one attempt whatever the outcome, so
+     * this endpoint is never a repeatable oracle. Deleting after the TTL check
+     * instead would leave an expired ticket in the map answering `400` forever
+     * while a live one answers `200` — an unauthenticated distinguisher.
+     *
+     * Returns `null` for unknown, spent and expired tickets alike. The caller
+     * maps all three to the same `400`; telling them apart is information the
+     * holder of a ticket they did not mint has no business having.
+     */
+    redeem(ticket: string): RedeemedTicket | null;
+}
+export {};