@12-apps/mcp 3.1.0 → 3.2.1

package/dist/create-api-mcp-oauth-CwVXKK-A.d.ts

@@ -0,0 +1,647 @@
+import { CryptoKey, JWK } from 'jose';
+
+/**
+ * Single-use guard for the stateless authorization codes (12-23, ported from
+ * the origin host's `lib/mcp/oauth/token-replay.ts`).
+ *
+ * A code is a signed blob with a `jti`, so "already redeemed" has to be remembered
+ * somewhere. The in-process option remembers it IN THIS PROCESS: a small map of
+ * `jti → expiry`, self-pruning once the code that carried it would have expired
+ * anyway, so the set never grows without bound.
+ *
+ * ⚠️ MULTI-INSTANCE LIMITATION (best-effort single-use): that map lives in ONE
+ * process. On a horizontally-scaled deployment a code could be replayed against a
+ * second instance that has not yet seen the `jti`, within the ≤60s code lifetime.
+ * Single-use is therefore strictly guaranteed only on a SINGLE instance — which is
+ * why choosing it is explicit and cannot happen by omission: `codeReplay` has no
+ * default, so a host either names a shared store or types `'in-process'`. BEFORE
+ * running this surface on more than one instance, pass a `codeReplay` store backed
+ * by something shared and atomic — a short-TTL row with a unique constraint, or a
+ * distributed cache with an atomic set-if-absent. The port exists precisely so
+ * that is a config change rather than a patch to the grant handler.
+ */
+interface CodeReplayStore {
+    /**
+     * Record a code's `jti` as consumed. `false` means it was ALREADY recorded (a
+     * replay); `true` is the first redemption. Must be atomic to be a real guard.
+     */
+    consume(jti: string, nowMs: number): Promise<boolean> | boolean;
+}
+/**
+ * The in-process store — correct on ONE instance, see the caveat above. Reached by
+ * passing `codeReplay: 'in-process'`, which is a required acknowledgement rather
+ * than a default: the config has no default for this field precisely because the
+ * only possible one would fail open on a multi-pod deployment.
+ */
+declare function inProcessCodeReplayStore(): CodeReplayStore;
+
+/**
+ * Signing-key / JWK loading for the OAuth authorization server (12-23, ported
+ * from the origin host's `lib/mcp/oauth/keys.ts`).
+ *
+ * ES256 (P-256) from PEM material, the published public JWK (with `kid` for
+ * rotation), and a safe-by-default absence signal (`null`) when no key is
+ * configured — callers then refuse to issue tokens and serve the JWKS as 503
+ * rather than falling back to a weaker mode while the surface is mounted.
+ *
+ * WHERE the PEM comes from is the host's business: `loadSigningKeyFromEnv` keeps
+ * the origin host's env-var wiring, and any other provider (a secrets manager, a KMS
+ * export) satisfies the same `McpSigningKeyProvider` shape.
+ */
+/** JWS algorithm for the signing key pair (asymmetric, self-validated via JWKS). */
+declare const SIGNING_ALG = "ES256";
+/** A public JWK safe to publish at the JWKS endpoint (never carries `d`). */
+interface PublicSigningJwk extends JWK {
+    kid: string;
+    kty: "EC";
+    crv: "P-256";
+    alg: typeof SIGNING_ALG;
+    use: "sig";
+}
+/** The loaded signing material: the private key for signing + its public JWK. */
+interface McpSigningKey {
+    privateKey: CryptoKey;
+    publicJwk: PublicSigningJwk;
+    kid: string;
+}
+/**
+ * How the surface obtains signing material. Returning `null` means "not
+ * provisioned": the AS then mints nothing and the JWKS answers 503.
+ */
+type McpSigningKeyProvider = () => Promise<McpSigningKey | null>;
+/**
+ * Build a provider over a PKCS#8 PEM + `kid` pair, with a per-process cache.
+ *
+ * Parsing PKCS#8 and exporting the JWK is pure for a given (pem, kid), so the
+ * promise is cached keyed on the material itself. A rotated key (different pem or
+ * kid) produces a different cache key and re-parses — the cache never masks a
+ * rotation.
+ *
+ * Rotation is BY `kid`: each key is published in the JWKS and selected by the
+ * `kid` header on issued JWTs, so publishing old + new during an overlap window
+ * lets both verify.
+ */
+declare function signingKeyProvider(read: () => {
+    pem: string | undefined;
+    kid: string | undefined;
+}): McpSigningKeyProvider;
+/** Env var carrying the ES256 private key as a PKCS#8 PEM (the origin host's name). */
+declare const DEFAULT_SIGNING_KEY_ENV = "MCP_OAUTH_SIGNING_KEY";
+/** Env var carrying the key id (`kid`) used to select the key during rotation. */
+declare const DEFAULT_SIGNING_KEY_ID_ENV = "MCP_OAUTH_SIGNING_KEY_ID";
+/**
+ * The env-backed provider — the origin host's wiring, kept identical, with the
+ * variable names as arguments so the package states no host's vocabulary.
+ */
+declare function loadSigningKeyFromEnv(keyEnv?: string, kidEnv?: string): McpSigningKeyProvider;
+
+/**
+ * The persistence PORTS of the authorization server (12-23).
+ *
+ * Three tables back the AS, and the package owns all three (see
+ * `prisma/mcp.prisma`): registered clients, rotating refresh tokens, and the
+ * per-user record of which AI host is live. What the package does NOT own is the
+ * client library used to reach them — so every read and write in the surface goes
+ * through these narrow ports, and `createPrismaMcpStores` (in
+ * `./prisma-stores.ts`) fills them for the common case in one line.
+ *
+ * The shapes are deliberately CLOSED and small: a host on something other than
+ * Prisma has a finite surface to fill, and the harness fills exactly this with
+ * hand-written SQL over a real Postgres.
+ */
+/** The two token-endpoint auth methods the AS accepts (matches the DB CHECK). */
+type TokenEndpointAuthMethod = "none" | "client_secret_basic";
+/** A registered OAuth client (an external host app — Claude.ai, ChatGPT…). */
+interface StoredOAuthClient {
+    clientId: string;
+    /** SHA-256 hex of the secret; `null` for a public PKCE client. */
+    clientSecretHash: string | null;
+    /** The EXACT-MATCH allowlist the authorize endpoint validates against. */
+    redirectUris: string[];
+    clientName: string | null;
+    tokenEndpointAuthMethod: string;
+    grantTypes: string[];
+    scopes: string[];
+}
+/** What `register` persists (the durable subset of RFC 7591 metadata). */
+interface NewOAuthClient {
+    clientId: string;
+    clientSecretHash: string | null;
+    redirectUris: string[];
+    clientName: string | null;
+    tokenEndpointAuthMethod: TokenEndpointAuthMethod;
+    grantTypes: string[];
+    scopes: string[];
+}
+interface OAuthClientStore {
+    create(client: NewOAuthClient): Promise<StoredOAuthClient>;
+    /** By the PUBLIC `client_id`, or `null` when unknown. */
+    findByClientId(clientId: string): Promise<StoredOAuthClient | null>;
+}
+/** A rotating refresh token, stored HASHED — never plaintext. */
+interface StoredRefreshToken {
+    tokenHash: string;
+    userEmail: string;
+    /** The original OAuth subject, kept stable across every rotation. */
+    userSub: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: Date;
+    /** The prior token's hash — the rotation lineage. `null` for a root token. */
+    rotatedFrom: string | null;
+    revokedAt: Date | null;
+}
+/** A token about to be stored (the plaintext never is). */
+type NewRefreshToken = Omit<StoredRefreshToken, "revokedAt">;
+interface RefreshTokenStore {
+    create(token: NewRefreshToken): Promise<void>;
+    findByHash(tokenHash: string): Promise<StoredRefreshToken | null>;
+    /** Whether some token was already rotated FROM this hash (replay detection). */
+    hasSuccessor(tokenHash: string): Promise<boolean>;
+    /** Every token of one `(userEmail, clientId)` family — the lineage walk's input. */
+    listFamily(userEmail: string, clientId: string): Promise<StoredRefreshToken[]>;
+    /** Revoke exactly these hashes (idempotent). */
+    revokeHashes(tokenHashes: readonly string[], at: Date): Promise<void>;
+    /**
+     * CLAIM the parent and store the successor, atomically. The whole of OAuth 2.1
+     * §4.3.1 replay protection rests on this one method, so read the contract before
+     * implementing it.
+     *
+     * Returns `true` when THIS call is the one that consumed `parentHash`, `false`
+     * when another call already had. `false` MUST mean nothing was written: no
+     * successor row, no second revocation.
+     *
+     * An implementation MUST revoke the parent CONDITIONALLY on it still being
+     * unrevoked — `updateMany({ where: { tokenHash: parentHash, revokedAt: null } })`,
+     * requiring a count of exactly 1 — and create the successor in the SAME
+     * transaction. An unconditional `update` is NOT enough: two concurrent rotations
+     * of one parent would both succeed, leaving two live successors of one token with
+     * no replay ever detected, because the replay rule fires on a THIRD use of the
+     * parent that then never comes. That is replay protection defeated by WINNING a
+     * race rather than by arriving second — precisely the attack rotation exists to
+     * stop, since an attacker holding a stolen refresh token need only fire it
+     * alongside the legitimate client to walk away with a live, independently
+     * rotating family.
+     *
+     * Atomicity against a CRASH is necessary too (a half-applied rotation leaves a
+     * live parent AND a live child) but it is not sufficient, and it is the easier
+     * half to satisfy by accident.
+     */
+    rotate(successor: NewRefreshToken, parentHash: string, at: Date): Promise<boolean>;
+    /**
+     * Revoke every LIVE token a user holds for one client; returns how many were
+     * actually ended (already-revoked rows are skipped, so a repeat reports 0).
+     */
+    revokeLiveForClient(userEmail: string, clientId: string): Promise<number>;
+}
+/** The AI provider a connection is attributed to. */
+type McpConnectionHost = string;
+/** A live connection, as the account surface shows it. */
+interface StoredMcpConnection {
+    oauthClientId: string;
+    clientName: string | null;
+    /** `null` for a pre-attribution connection. */
+    host: string | null;
+    connectedAt: Date;
+    lastActiveAt: Date;
+}
+interface McpConnectionStore {
+    /** Liveness of one `(user, client)` pair, for the activity throttle. */
+    lastActiveAt(userId: string, oauthClientId: string): Promise<Date | null>;
+    /**
+     * Record (or refresh) liveness. Any activity CLEARS a prior `revokedAt` — the
+     * host is talking to us again — and must never blank a known `host` when this
+     * grant cannot derive one.
+     */
+    recordActivity(input: {
+        userId: string;
+        oauthClientId: string;
+        clientName: string | null;
+        host: string | null;
+        at: Date;
+    }): Promise<void>;
+    /** A user's active (non-revoked) connections, most-recently-active first. */
+    listActive(userId: string): Promise<StoredMcpConnection[]>;
+    /**
+     * Revoke every live connection of one provider for this user and return the
+     * OAuth client ids that were revoked — the caller ends their refresh tokens,
+     * which is what actually cuts access.
+     */
+    revokeByHost(userId: string, host: McpConnectionHost): Promise<string[]>;
+    /**
+     * The self-report path: attribute this user's just-connected, still-unattributed
+     * connection to `host`, or refresh the one already attributed to it. Returns
+     * rows touched.
+     */
+    announce(userId: string, host: McpConnectionHost): Promise<number>;
+}
+/** The stores the AS needs. `connections` is optional — see the config docs. */
+interface McpOauthStores {
+    clients: OAuthClientStore;
+    refreshTokens: RefreshTokenStore;
+    connections?: McpConnectionStore;
+}
+
+/** RFC 7591 registration input (the durable subset the store persists). */
+interface RegisterClientInput {
+    /** The exact-match redirect-uri allowlist (open-redirect guard). */
+    redirectUris: string[];
+    clientName?: string | null;
+    /**
+     * `none` (public PKCE client, the default) or `client_secret_basic`
+     * (confidential — a secret is generated and its hash stored).
+     */
+    tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+    /** Grant types; defaults to authorization_code + refresh_token. */
+    grantTypes?: string[];
+    scopes: string[];
+}
+/**
+ * The registration RESULT. `clientSecret` is present (plaintext, ONCE) only for a
+ * confidential client — it is never stored and never returned again.
+ */
+interface RegisteredClient {
+    clientId: string;
+    clientSecret?: string;
+    redirectUris: string[];
+    clientName: string | null;
+    tokenEndpointAuthMethod: TokenEndpointAuthMethod;
+    grantTypes: string[];
+    scopes: string[];
+}
+/** SHA-256 hex digest — the at-rest form of the client secret. */
+declare function hashSecret(secret: string): string;
+/**
+ * Register an OAuth client under a generated `clientId`. For a confidential
+ * client a random secret is generated and its hash stored; the plaintext is
+ * returned once.
+ */
+declare function registerClient(store: OAuthClientStore, input: RegisterClientInput): Promise<RegisteredClient>;
+/**
+ * Open-redirect guard: a redirect target is accepted ONLY when it EXACTLY equals a
+ * registered `redirect_uri`. No normalization, no prefix, no trailing-slash
+ * leniency — an intercepted authorization request must not be steerable to any URI
+ * the client did not register.
+ */
+declare function matchesRedirectUri(client: Pick<StoredOAuthClient, "redirectUris">, redirectUri: string): boolean;
+/**
+ * Provider attribution rules: the canonical root domains that own each host's
+ * OAuth callback. A redirect host matches a root only as the exact domain or a
+ * real (dot-guarded) subdomain — never a suffix, so `evilchatgpt.com` never
+ * matches `chatgpt.com`.
+ */
+interface ProviderAttributionRule {
+    roots: readonly string[];
+    provider: string;
+}
+/** The origin host's rules, and a sane default for any host talking to the same two. */
+declare const DEFAULT_PROVIDER_ROOTS: readonly ProviderAttributionRule[];
+/**
+ * Best-effort provider attribution from a client's redirect URIs: the host that
+ * owns the callback (`claude.ai` → claude, `chatgpt.com` → chatgpt). Returns
+ * `null` when nothing matches — the UI then falls back to what the owner
+ * completed the flow with, and a self-report (the `announce` path) can attribute
+ * it later.
+ */
+declare function providerFromRedirectUris(redirectUris: readonly string[], rules?: readonly ProviderAttributionRule[]): string | null;
+
+/**
+ * The config seam of the authorization server, and its resolved form (12-23).
+ *
+ * Everything a HOST knows and the package cannot: who the signed-in caller is,
+ * where the data lives, which origins are trusted, whether the surface is turned
+ * on at all, and where its endpoints are mounted. Everything else — the RFC wire,
+ * PKCE, rotation, replay, the discovery documents — is the package's.
+ */
+/** The identity an authorize request binds a code to. From the SESSION only. */
+interface McpOauthSession {
+    /**
+     * The OAuth subject (the origin host passes the Google `sub`, falling back to the
+     * email). Carried through every rotation so a refreshed token keeps the same
+     * stable `sub`.
+     */
+    subject: string;
+    /** The signed-in user's email — the identity the AS binds to. */
+    email: string;
+}
+/** Where each endpoint of the surface lives, from the origin root. */
+interface McpOauthPaths {
+    authorize: string;
+    token: string;
+    register: string;
+    jwks: string;
+    authorizationServerMetadata: string;
+    protectedResourceMetadata: string;
+}
+declare const DEFAULT_OAUTH_PATHS: McpOauthPaths;
+/** How a connection's liveness is recorded on a successful grant. */
+interface McpConnectionRecording {
+    /**
+     * The host's DB user id for a token's email, or `null` when there is no user row
+     * yet (recording is then skipped — email is the identity, not the id).
+     */
+    resolveUserId: (email: string) => Promise<string | null> | string | null;
+    /** Provider attribution rules; defaults to claude/chatgpt roots. */
+    providerRules?: readonly ProviderAttributionRule[];
+    /** Don't rewrite on every grant — refresh liveness at most this often. */
+    activityThrottleMs?: number;
+}
+interface McpOauthConfig {
+    /** Where the three owned tables live (see `./stores.ts`). */
+    stores: McpOauthStores;
+    /**
+     * Resolve the caller's COOKIE SESSION for the authorize endpoint. `null` sends
+     * the caller through the host's sign-in flow; no code is ever minted for an
+     * unauthenticated request, and a client can never supply the identity itself.
+     */
+    resolveSession: (request: Request) => Promise<McpOauthSession | null> | McpOauthSession | null;
+    /**
+     * The operator gate. `false` makes the whole surface inert — authorize/token/jwks
+     * answer 404 and registration answers 403 — which is how the origin host ships it OFF
+     * by default (`MCP_BEARER_ENABLED`). Default: enabled (mounting is the opt-in).
+     */
+    enabled?: boolean | (() => boolean);
+    /**
+     * Signing material. Default: the env-backed provider with the origin host's variable
+     * names. `null` from the provider means "not provisioned": nothing is minted and
+     * the JWKS answers 503 rather than falling back to a weaker mode.
+     */
+    signingKey?: McpSigningKeyProvider;
+    /**
+     * The trusted PUBLIC origin allowlist — REQUIRED behind a reverse proxy, where
+     * the server sees only its internal bind. The FIRST entry is canonical. With
+     * none configured a forwarded host is never trusted (see `resolveTrustedOrigin`).
+     */
+    trustedOrigins?: readonly string[];
+    /** Scopes the AS advertises and validates against. Default `mcp:read mcp:write`. */
+    scopes?: readonly string[];
+    /** Where the MCP resource is mounted — the token audience. Default `/api/mcp`. */
+    resourcePath?: string;
+    /** Endpoint paths, if the host mounts them somewhere else. */
+    paths?: Partial<McpOauthPaths>;
+    /** Where an unauthenticated authorize request is sent. Default `/login`. */
+    loginPath?: string;
+    /**
+     * The query parameter carrying the post-login return path. Default
+     * `callbackUrl` (Auth.js's name).
+     */
+    loginCallbackParam?: string;
+    accessTokenTtlSeconds?: number;
+    refreshTokenTtlMs?: number;
+    /**
+     * The single-use guard for authorization codes — REQUIRED, and required on
+     * purpose. Pass a shared atomic store, or the literal `'in-process'` to accept
+     * the single-instance limitation explicitly.
+     *
+     * There is deliberately NO default, because a default here would be the only one
+     * in this config that fails OPEN. Every other one fails closed: no signing key
+     * mints nothing and answers JWKS 503; `enabled: false` is 404 everywhere; an
+     * empty `trustedOrigins` never trusts a forwarded host. An in-process default
+     * instead silently permits cross-instance code replay — against an OAuth 2.1
+     * MUST, on the very deployment shape a reusable package exists for (two pods
+     * behind one load balancer), with nothing in the types to notice. Scaling out
+     * must not be able to weaken the guard without somebody having typed something.
+     */
+    codeReplay: CodeReplayStore | "in-process";
+    /**
+     * Approve an authorize request before a code is minted — the CONSENT step.
+     *
+     * Registration is open whenever `enabled` is true (RFC 7591), so without an
+     * approval step anyone may register a client carrying their OWN redirect URI and
+     * their OWN scope ceiling, send a signed-in admin one link, and have the endpoint
+     * mint them a code with no interaction: the redirect URI is exact-matched against
+     * the attacker's own registration and the scope ceiling is the attacker's too, so
+     * every other guard here holds and none of them helps.
+     *
+     * Until a host supplies this, `authorize` REFUSES any client it cannot see the
+     * operator behind — i.e. any client not named in {@link preApprovedClientIds}.
+     * Return `false` to deny (the caller gets an `access_denied` redirect, exactly as
+     * a human refusal would).
+     */
+    resolveApproval?: (request: Request, client: StoredOAuthClient, scopes: readonly string[]) => Promise<boolean> | boolean;
+    /**
+     * Client ids the OPERATOR registered, exempt from the approval gate above — the
+     * escape hatch for a host that ships its own first-party clients and has no
+     * consent screen to offer. Anything NOT listed here is treated as dynamically
+     * registered, i.e. as attacker-controllable.
+     */
+    preApprovedClientIds?: readonly string[];
+    /** Liveness recording on a grant; omit to record nothing. */
+    connections?: McpConnectionRecording;
+}
+/** The config with every default applied — what the handlers actually read. */
+interface McpOauthContext {
+    stores: McpOauthStores;
+    resolveSession: McpOauthConfig["resolveSession"];
+    enabled: () => boolean;
+    signingKey: McpSigningKeyProvider;
+    trustedOrigins: readonly string[];
+    scopes: readonly string[];
+    resourcePath: string;
+    paths: McpOauthPaths;
+    loginPath: string;
+    loginCallbackParam: string;
+    accessTokenTtlSeconds: number;
+    refreshTokenTtlMs: number;
+    codeReplay: CodeReplayStore;
+    /**
+     * The resolved consent decision for one authorize request. Always present: with
+     * no host seam it refuses every client the operator did not pre-approve, so the
+     * handler has no "unset" case to forget.
+     */
+    approve: (request: Request, client: StoredOAuthClient, scopes: readonly string[]) => Promise<boolean>;
+    connections?: McpConnectionRecording;
+    /** The trusted public origin for THIS request (issuance and verification agree). */
+    originOf: (request: Request) => string;
+}
+declare function resolveMcpOauthConfig(config: McpOauthConfig): McpOauthContext;
+
+/**
+ * The OAuth 2.1 authorization-server foundation: the shared scope source, the
+ * issuer/audience derivation, and the trusted-origin resolver every URL in the
+ * surface is built from (12-23, ported from the origin host's
+ * `lib/mcp/oauth/config.ts`).
+ *
+ * Keeping the scopes and the origin resolution in ONE place is what stops the
+ * two discovery documents — RFC 8414 `/.well-known/oauth-authorization-server`
+ * and RFC 9728 `/.well-known/oauth-protected-resource` — from drifting apart,
+ * and what makes a token minted for an origin verify against that same origin.
+ *
+ * What was env-reading in the host is CONFIG here (the package must not learn a
+ * host's variable names); `trustedOriginsFromEnv` is the one-line helper that
+ * keeps the origin host's wiring identical.
+ */
+/** Scopes advertised by both discovery documents. `mcp:write` gates mutating tools. */
+declare const MCP_SUPPORTED_SCOPES: readonly ["mcp:read", "mcp:write"];
+type McpScope = (typeof MCP_SUPPORTED_SCOPES)[number];
+/** Path the MCP JSON-RPC endpoint is mounted at — the access token's audience. */
+declare const DEFAULT_MCP_RESOURCE_PATH = "/api/mcp";
+/** The OAuth `iss` — the deployment origin, used verbatim. */
+declare function issuer(origin: string): string;
+/** The access-token `aud` — the MCP resource URL (`${origin}${resourcePath}`). */
+declare function resourceAudience(origin: string, resourcePath?: string): string;
+/**
+ * Read a comma-separated allowlist out of an environment variable — the origin host
+ * passes `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')`, so the behaviour
+ * is identical while the variable's NAME stays the host's.
+ */
+declare function trustedOriginsFromEnv(name: string): string[];
+/**
+ * THE single trusted-origin resolver, shared by token ISSUANCE (the `iss`/`aud` a
+ * token is minted with) and bearer VERIFICATION (the expected `aud` a protected
+ * route checks). Because both sides pass the SAME request's headers, a token
+ * minted for the allowlisted origin verifies against that same origin — they
+ * cannot drift (e.g. mint `https://app.example.com` but verify
+ * `http://0.0.0.0:3000` and reject a valid token).
+ *
+ * The origin must NEVER be attacker-controllable. Behind a reverse proxy the
+ * server sees only its internal bind on `request.url`, so the public origin comes
+ * from the proxy's `X-Forwarded-Host` — but a forwarded host is honored ONLY when
+ * it is on the operator-configured allowlist; ANY other value (a spoofed/foreign
+ * host, or an absent header) resolves to the canonical (FIRST) allowlisted origin.
+ * So even if the edge forwards `X-Forwarded-Host: evil.example.com`, the origin
+ * stays the trusted one.
+ *
+ * With NO allowlist configured a forwarded host is NEVER trusted — a spoofed
+ * header must not be able to choose the issuer — so `fallbackOrigin` (the
+ * request's OWN origin) is used instead. A proxied deployment therefore REQUIRES
+ * the allowlist; until it is set the surface fails closed to the internal origin
+ * rather than a foreign one.
+ */
+declare function resolveTrustedOrigin(getHeader: (name: string) => string | null, fallbackOrigin: string | undefined, trustedOrigins?: readonly string[]): string | undefined;
+/**
+ * The PUBLIC origin every URL in the surface derives from (issuer, endpoint URLs,
+ * access-token `iss`/`aud`). A thin wrapper over {@link resolveTrustedOrigin}
+ * bound to a `Request`, falling back to the request URL's origin when no
+ * allowlist is configured.
+ */
+declare function originFromRequest(request: Request, trustedOrigins?: readonly string[]): string;
+
+/**
+ * JWT access-token issuer + verifier (12-23, ported from the origin host's
+ * `lib/mcp/oauth/jwt.ts` — behaviour unchanged; the signing key arrives through a
+ * provider and the resource path is config).
+ *
+ * The access token is a short-lived, ES256-signed JWT bound to the signed-in
+ * user. It carries the claims the resource server checks LOCALLY against the
+ * published JWKS (no introspection round-trip): `iss` (the issuer origin), `aud`
+ * (`${origin}${resourcePath}`), `sub`, `email`, `scope` (space-delimited), `iat`,
+ * `exp` (short TTL), and `jti`; the JWT header carries `kid` so the verifier can
+ * select the public key during rotation.
+ *
+ * Failures are typed so the caller maps them to the right OAuth challenge
+ * (`invalid_token` vs `insufficient_scope`).
+ */
+/** Access-token lifetime — short-lived (15 min) per the spec. */
+declare const ACCESS_TOKEN_TTL_SECONDS: number;
+/** The identity a verified access token resolves to. */
+interface VerifiedAccessToken {
+    email: string;
+    subject: string;
+    scopes: string[];
+}
+/** Distinct verification failure reasons the caller maps to OAuth challenges. */
+type AccessTokenErrorCode = "invalid_token" | "insufficient_scope";
+/** A typed verification failure — `code` drives the `WWW-Authenticate` challenge. */
+declare class AccessTokenError extends Error {
+    readonly code: AccessTokenErrorCode;
+    constructor(code: AccessTokenErrorCode, message?: string);
+}
+/** Inputs bound into a minted access token. */
+interface SignAccessTokenInput {
+    email: string;
+    subject: string;
+    scopes: readonly McpScope[] | readonly string[];
+    origin: string;
+    /** Where the MCP resource is mounted. Default `/api/mcp`. */
+    resourcePath?: string;
+    /** Token lifetime in seconds. Default 15 minutes. */
+    ttlSeconds?: number;
+}
+/** Deterministic-clock option shared by mint + verify. */
+interface ClockOption {
+    /** Epoch milliseconds; defaults to `Date.now()`. Injected for deterministic tests. */
+    now?: number;
+}
+/**
+ * Mint an ES256-signed access token bound to the user.
+ *
+ * Returns `null` when no signing key is configured (safe-by-default: the AS
+ * refuses to issue rather than falling back to a weaker mode). Sets the `kid`
+ * header from the loaded key so the verifier can resolve the public JWK during
+ * rotation.
+ */
+declare function signAccessToken(loadSigningKey: McpSigningKeyProvider, input: SignAccessTokenInput, options?: ClockOption): Promise<string | null>;
+/** Options for {@link verifyAccessToken}. */
+interface VerifyAccessTokenOptions extends ClockOption {
+    /** The deployment origin — derives the expected `iss` and `aud`. */
+    origin: string;
+    /** Where the MCP resource is mounted. Default `/api/mcp`. */
+    resourcePath?: string;
+    /** When set, the token must carry this scope or verification fails `insufficient_scope`. */
+    requiredScope?: McpScope | string;
+}
+declare function verifyAccessToken(loadSigningKey: McpSigningKeyProvider, token: string, options: VerifyAccessTokenOptions): Promise<VerifiedAccessToken>;
+
+/**
+ * The OAuth 2.1 authorization server, as one mount (12-23).
+ *
+ * `@12-apps/mcp` shipped the OpenAPI→tools generator, the bearer proxy and the two
+ * discovery BUILDERS, and held zero authorization logic — which meant every new app
+ * still wrote the AS itself: ~1.5k LOC of authorize/token/register plus the code,
+ * token, PKCE, rotation and replay machinery under them. All of that is the
+ * surface's contract, not a host's, so it lives here.
+ *
+ * Routes are FRAMEWORK-NEUTRAL descriptors whose handler takes a Fetch `Request`
+ * and answers a Fetch `Response`. Unlike the report-builder-shaped surfaces there
+ * is no `{ data }` envelope to adapt: an OAuth response is a 302 with a `Location`,
+ * a form-encoded exchange answering RFC 6749 §5.1/§5.2 JSON, or an RFC 8414/9728
+ * document — shapes fixed by specification that a wrapper would only break. So the
+ * adapters are one line each, and a host with a file-per-route layout can export
+ * the named handlers directly:
+ *
+ *   export const GET = mcpOauth.handlers.authorize;      // app/api/oauth/authorize
+ *   export const POST = mcpOauth.handlers.token;         // app/api/oauth/token
+ *
+ * What stays the HOST's: the cookie session (`resolveSession`), where the data
+ * lives (`stores`), which origins are trusted, the operator gate, and its sign-in
+ * path. Everything else is the RFCs'.
+ */
+interface McpOauthRoute {
+    method: "GET" | "POST";
+    /** Absolute path from the ORIGIN ROOT — `.well-known/*` cannot live under a prefix. */
+    path: string;
+    handle(request: Request): Promise<Response>;
+}
+interface McpOauthHandlers {
+    /** `GET` — Authorization Code + PKCE, identity from the session only. */
+    authorize: (request: Request) => Promise<Response>;
+    /** `POST` — the two grants, form-encoded, RFC 6749 bodies. */
+    token: (request: Request) => Promise<Response>;
+    /** `POST` — RFC 7591 dynamic client registration (403 when the gate is off). */
+    register: (request: Request) => Promise<Response>;
+    /** `GET` — the public JWKS (503 while no key is provisioned). */
+    jwks: (request: Request) => Promise<Response>;
+    /** `GET` — RFC 8414 authorization-server metadata. */
+    authorizationServerMetadata: (request: Request) => Promise<Response>;
+    /** `GET` — RFC 9728 protected-resource metadata. */
+    protectedResourceMetadata: (request: Request) => Promise<Response>;
+}
+interface ApiMcpOauth {
+    /** Every endpoint, in mount order. */
+    routes: McpOauthRoute[];
+    /** The same handlers by name, for a host whose router is its file tree. */
+    handlers: McpOauthHandlers;
+    /**
+     * Verify a bearer token the way THIS surface mints them — the resource server's
+     * half. Bound to the same signing key, resource path and trusted-origin
+     * resolution, which is what stops "minted for origin A, verified against origin
+     * B" from rejecting valid tokens.
+     */
+    verifyBearer: (token: string, request: Request, options?: Omit<VerifyAccessTokenOptions, "origin" | "resourcePath">) => Promise<VerifiedAccessToken>;
+    /** The resolved config, for a host that needs the same origin/audience answers. */
+    context: McpOauthContext;
+}
+declare function createApiMcpOauth(config: McpOauthConfig): ApiMcpOauth;
+
+export { trustedOriginsFromEnv as $, type ApiMcpOauth as A, type StoredMcpConnection as B, type CodeReplayStore as C, DEFAULT_MCP_RESOURCE_PATH as D, type VerifyAccessTokenOptions as E, createApiMcpOauth as F, hashSecret as G, inProcessCodeReplayStore as H, issuer as I, loadSigningKeyFromEnv as J, matchesRedirectUri as K, originFromRequest as L, type McpOauthConfig as M, type NewOAuthClient as N, type OAuthClientStore as O, type ProviderAttributionRule as P, providerFromRedirectUris as Q, type RefreshTokenStore as R, type StoredOAuthClient as S, type TokenEndpointAuthMethod as T, registerClient as U, type VerifiedAccessToken as V, resolveMcpOauthConfig as W, resolveTrustedOrigin as X, resourceAudience as Y, signAccessToken as Z, signingKeyProvider as _, type McpSigningKeyProvider as a, verifyAccessToken as a0, type NewRefreshToken as b, type StoredRefreshToken as c, type McpOauthStores as d, type McpConnectionStore as e, ACCESS_TOKEN_TTL_SECONDS as f, AccessTokenError as g, type AccessTokenErrorCode as h, DEFAULT_OAUTH_PATHS as i, DEFAULT_PROVIDER_ROOTS as j, DEFAULT_SIGNING_KEY_ENV as k, DEFAULT_SIGNING_KEY_ID_ENV as l, MCP_SUPPORTED_SCOPES as m, type McpConnectionRecording as n, type McpOauthContext as o, type McpOauthHandlers as p, type McpOauthPaths as q, type McpOauthRoute as r, type McpOauthSession as s, type McpScope as t, type McpSigningKey as u, type PublicSigningJwk as v, type RegisterClientInput as w, type RegisteredClient as x, SIGNING_ALG as y, type SignAccessTokenInput as z };