@greatwait/contracts 0.1.0-alpha.1

package/dist/oauth.js

@@ -0,0 +1,708 @@
+import { z } from "zod";
+import { SCOPES, environmentKindSchema, scopeSchema, } from "./authority.js";
+import { oauthClientIdSchema, oauthGrantIdSchema, projectIdSchema, } from "./identifiers.js";
+import { timestampSchema } from "./time.js";
+/**
+ * The delegated-authorization vocabulary: OAuth 2.1 as this product speaks it.
+ *
+ * Two things make this file worth reading before the routes that use it.
+ *
+ * **OAuth's wire shapes are not this product's wire shapes.** Everything on
+ * `/v1` answers `application/problem+json` with a `code` from `PROBLEM_CODES`;
+ * an OAuth endpoint answers `{"error": "invalid_grant"}` because RFC 6749 §5.2
+ * says so and every client in existence parses that. The two taxonomies are kept
+ * apart deliberately rather than reconciled — a client library that has to
+ * branch on which envelope it got back is a client library that will get it
+ * wrong. `OAUTH_ERRORS` below is the OAuth half, and it is closed for the same
+ * reason `PROBLEM_CODES` is.
+ *
+ * **The scope vocabulary is shared, and that is the whole point.** An OAuth
+ * grant carries `Scope` values from `authority.ts` — the same nine an API
+ * credential carries, capped by the same `capScopesToRole`. There is no
+ * OAuth-only scope and no OAuth-only operation, so a token cannot reach anything
+ * a key cannot, which is what architecture section 8 means by "API key and Clerk
+ * role mappings share one policy package".
+ */
+/**
+ * Where each OAuth endpoint lives.
+ *
+ * Stated once because two readers must agree: the router that serves them and
+ * the discovery documents that advertise them. A client fetches the metadata and
+ * then uses exactly the URLs it found there, so a path that drifts from its
+ * advertisement is not a 404 in one place — it is a client that cannot
+ * authenticate and cannot say why.
+ *
+ * Outside `/v1` on purpose, following the convention `CLERK_WEBHOOK_PATH` set.
+ * The `/v1` surface is the product's operation registry: every entry is
+ * projected into OpenAPI, the SDK, an MCP tool and the contract mock, and W1-07
+ * enforces parity across all of them. None of that is true of an OAuth endpoint,
+ * whose shape is fixed by a standard rather than by us, and one of which
+ * (`/oauth/token`) must never become an agent-callable tool.
+ */
+export const OAUTH_ROUTES = {
+    /** RFC 8414 authorization server metadata. */
+    authorizationServerMetadata: "/.well-known/oauth-authorization-server",
+    /** The browser-facing start of the flow. */
+    authorize: "/oauth/authorize",
+    /** What the consent screen reads to render itself. Session-authenticated. */
+    authorizationRequest: "/oauth/authorization-requests/:authorizationRequestId",
+    /** Where the consent screen posts approve or deny. Session-authenticated. */
+    consent: "/oauth/authorization-requests/:authorizationRequestId/consent",
+    // **No `grants` here since W4-08.** A member's list of connected
+    // applications is in no RFC and this file's own comment above called the
+    // consent endpoints "this product's own API" — so being outside `/v1` bought
+    // nothing and cost the published document, the generated client and an MCP
+    // disposition. `grants.list` and `grants.revoke` are operations now.
+    /** RFC 9728 protected resource metadata, which is how MCP clients start. */
+    protectedResourceMetadata: "/.well-known/oauth-protected-resource",
+    /** RFC 7591 dynamic client registration. */
+    register: "/oauth/register",
+    /** RFC 7009 token revocation. */
+    revoke: "/oauth/revoke",
+    /** RFC 6749 token endpoint. */
+    token: "/oauth/token",
+};
+/**
+ * Every error this authorization server emits, and nothing else.
+ *
+ * Closed rather than open because an `error` value is what a client branches on,
+ * exactly like a problem `code`. RFC 6749 §4.1.2.1 and §5.2 define most of
+ * these; `invalid_target` is RFC 8707's, for a `resource` naming something this
+ * server does not protect.
+ *
+ * Note what is *not* here: there is no error meaning "your membership was
+ * downgraded" and none meaning "that grant was revoked". Both are `invalid_grant`
+ * at the token endpoint, because RFC 6749 gives one code for "the grant is no
+ * longer usable" and inventing a second would tell a client which of the two
+ * happened — which is information about the account, delivered to whoever holds
+ * a dead token.
+ */
+export const OAUTH_ERRORS = [
+    "access_denied",
+    "invalid_client",
+    "invalid_client_metadata",
+    "invalid_grant",
+    "invalid_redirect_uri",
+    "invalid_request",
+    "invalid_scope",
+    "invalid_target",
+    "server_error",
+    "temporarily_unavailable",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "unsupported_response_type",
+];
+export const oauthErrorCodeSchema = z.enum(OAUTH_ERRORS);
+/**
+ * The error body, RFC 6749 §5.2.
+ *
+ * `error_description` is human-readable and must stay that way: it is displayed
+ * to developers and never parsed. FXO-1368 is the record of what happens when
+ * a caller does parse it — reconciliation that matched a provider's
+ * human-readable string broke when the wording changed. Anything a client needs
+ * to act on belongs in `error`.
+ */
+export const oauthErrorSchema = z.object({
+    error: oauthErrorCodeSchema,
+    error_description: z.string().min(1).optional(),
+    error_uri: z.url().optional(),
+});
+/**
+ * HTTP status for each error, so a route cannot pair a code with the wrong one.
+ *
+ * `invalid_client` is 401 because RFC 6749 §5.2 says so, and the difference is
+ * load-bearing: a client that cannot authenticate must not be told to fix its
+ * request. Everything else on the token endpoint is 400 — including
+ * `invalid_grant`, which is the code a revoked, replayed or expired grant
+ * produces, and which is deliberately *not* 401. A 401 invites a client to
+ * re-present the same dead credential.
+ */
+export const OAUTH_ERROR_STATUS = {
+    access_denied: 400,
+    invalid_client: 401,
+    // RFC 7591 §3.2.2's registration errors, which share this envelope and are
+    // 400 like every other request fault. Kept in one catalogue rather than a
+    // second so a route cannot reach for a code from the wrong standard.
+    invalid_client_metadata: 400,
+    invalid_grant: 400,
+    invalid_redirect_uri: 400,
+    invalid_request: 400,
+    invalid_scope: 400,
+    invalid_target: 400,
+    server_error: 500,
+    temporarily_unavailable: 503,
+    unauthorized_client: 400,
+    unsupported_grant_type: 400,
+    unsupported_response_type: 400,
+};
+/**
+ * Build an error body. The status comes from the table above rather than from
+ * the caller, so the two cannot contradict each other — the same argument
+ * `problem()` makes for `PROBLEM_CODES`.
+ */
+export function oauthError(error, description) {
+    return {
+        body: oauthErrorSchema.parse({
+            error,
+            ...(description === undefined ? {} : { error_description: description }),
+        }),
+        status: OAUTH_ERROR_STATUS[error],
+    };
+}
+/**
+ * The only grant types this server issues against.
+ *
+ * No implicit grant, no resource owner password credentials, no client
+ * credentials. The first two are removed by OAuth 2.1; the third would be a
+ * client acting with no human behind it, which is what an API credential already
+ * is and what `capScopesToRole` has no role to cap against.
+ */
+export const OAUTH_GRANT_TYPES = [
+    "authorization_code",
+    "refresh_token",
+];
+export const oauthGrantTypeSchema = z.enum(OAUTH_GRANT_TYPES);
+/** Authorization code is the only response type. See above. */
+export const OAUTH_RESPONSE_TYPES = ["code"];
+/**
+ * PKCE challenge methods, and `plain` is not one.
+ *
+ * OAuth 2.1 removes it, and the reason is worth stating where the constant is:
+ * `plain` sends the verifier as the challenge, so anyone who can read the
+ * authorization request can complete the exchange — which is the entire attack
+ * PKCE exists to stop. A client asking for `plain` is refused rather than
+ * downgraded to it.
+ */
+export const PKCE_METHODS = ["S256"];
+export const pkceMethodSchema = z.enum(PKCE_METHODS);
+/**
+ * RFC 7636 §4.1: 43–128 characters from an unreserved alphabet. The floor is
+ * what makes the verifier unguessable, so it is enforced rather than assumed.
+ */
+export const PKCE_VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]{43,128}$/u;
+/** The base64url SHA-256 of a verifier: 43 characters, no padding. */
+export const PKCE_CHALLENGE_PATTERN = /^[A-Za-z0-9\-_]{43}$/u;
+/**
+ * Client authentication methods this server accepts, which is one: none.
+ *
+ * **Every client here is a public client.** An MCP client is a desktop
+ * application, a CLI, or a browser extension; it cannot keep a secret, and RFC
+ * 7591 registration hands a `client_secret` to whoever asked for one without
+ * ever authenticating them. Issuing a secret to an unauthenticated registrant
+ * and then treating it as proof of identity is a confidence trick played on
+ * ourselves.
+ *
+ * What replaces it is PKCE, which is mandatory here, plus exact redirect
+ * matching — together those bind an authorization code to the software instance
+ * that started the flow, which is the property a client secret is usually
+ * pressed into providing. A confidential-client flow can be added later without
+ * a contract break; adding it now would be surface with no consumer.
+ */
+export const TOKEN_ENDPOINT_AUTH_METHODS = ["none"];
+/**
+ * How long a member has to finish consenting before the request expires.
+ *
+ * Short because a pending authorization request is a live intent to grant
+ * access, and a long-lived one is something an attacker can hope a member
+ * approves absent-mindedly later. Ten minutes is enough to sign in to Clerk from
+ * a cold browser and read the screen.
+ */
+export const AUTHORIZATION_REQUEST_TTL_SECONDS = 600;
+/**
+ * How long an issued authorization code may be exchanged.
+ *
+ * RFC 6749 §4.1.2 recommends a maximum of ten minutes; this is deliberately much
+ * shorter, because the code travels through the user's browser — a redirect
+ * chain, an address bar, a browser history entry, and whatever referrer policy
+ * the client's own page carries. Sixty seconds is more than a token exchange
+ * needs and less than a leak is useful for.
+ */
+export const AUTHORIZATION_CODE_TTL_SECONDS = 60;
+/**
+ * How long an access token is valid.
+ *
+ * The number that decides how stale a revocation may be *in the worst case where
+ * the token check is skipped* — which, on this server, is never: every request
+ * loads the grant and re-checks membership, so a revoked grant fails on its next
+ * use rather than at the end of this window. The lifetime is short anyway,
+ * because a token this cheap to refresh has no reason to be long-lived.
+ */
+export const ACCESS_TOKEN_TTL_SECONDS = 3600;
+/**
+ * How long a refresh token is valid, absent rotation.
+ *
+ * Rotation resets it, so an actively used grant survives indefinitely and an
+ * abandoned one stops working after thirty days. That is the behaviour a member
+ * expects from "apps I have connected": the ones they use keep working, and the
+ * ones they forgot about do not accumulate forever.
+ */
+export const REFRESH_TOKEN_TTL_SECONDS = 2_592_000;
+/**
+ * Token shapes.
+ *
+ * The same prefix-plus-secret construction API credentials use, for the same
+ * reason: a presented token is found by its non-secret leading segment before
+ * anything is compared, so verification never scans. The environment is in the
+ * prefix because a token that cannot be told apart from a live one at a glance
+ * is one somebody will paste into the wrong place.
+ *
+ * Three separate prefixes rather than one, because they are three different
+ * things with three different lifetimes, and a store that accepted a refresh
+ * token where an access token belonged would be one type confusion away from
+ * making the short lifetime meaningless.
+ */
+/** `oat_live_` and friends: four characters, the environment, two separators. */
+export const OAUTH_TOKEN_NAMESPACE_LENGTH = 9;
+/**
+ * Random characters after the namespace. Forty-eight of a 32-symbol alphabet is
+ * 240 bits — deliberately more than a credential's 160, because these are minted
+ * by machines at machine rates and nobody ever has to type one.
+ */
+export const OAUTH_TOKEN_SECRET_LENGTH = 48;
+export const ACCESS_TOKEN_PATTERN = /^oat_(?:live|test)_[0-9a-z]{48}$/u;
+export const REFRESH_TOKEN_PATTERN = /^ort_(?:live|test)_[0-9a-z]{48}$/u;
+export const AUTHORIZATION_CODE_PATTERN = /^oac_(?:live|test)_[0-9a-z]{48}$/u;
+/** Any of the three, for the one place that has to tell ours from anything else. */
+export const OAUTH_SECRET_PATTERN = /^o(?:at|rt|ac)_(?:live|test)_[0-9a-z]{48}$/u;
+/**
+ * A redirect URI, validated the way RFC 8252 says a public client's must be.
+ *
+ * Three shapes are accepted and everything else is refused:
+ *
+ * - `https://` anywhere. The ordinary case.
+ * - `http://` on a loopback host only — `127.0.0.1`, `[::1]`, `localhost`. A
+ *   native client receives its code on a listener it started itself, and there
+ *   is no TLS to have. Refusing these would refuse every desktop MCP client.
+ * - a private-use scheme containing a dot, such as `com.example.app:/callback`.
+ *   RFC 8252 §7.1's reverse-domain form, which is what a mobile or editor client
+ *   registers.
+ *
+ * A fragment is refused outright: RFC 6749 §3.1.2 forbids one, and the fragment
+ * is where the server appends nothing and the browser strips everything, so a
+ * client that registered one would silently never see its code.
+ *
+ * Userinfo is refused because `https://evil@good.example` is read as
+ * `good.example` by a URL parser and as `evil` by a human skimming a consent
+ * screen — and the consent screen is the one place a human is asked to make this
+ * exact judgement.
+ */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "::1", "localhost"]);
+export const redirectUriSchema = z
+    .string()
+    .min(1)
+    .max(2048)
+    .superRefine((value, context) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        context.addIssue({
+            code: "custom",
+            message: "must be an absolute URI",
+        });
+        return;
+    }
+    if (url.hash.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "must not contain a fragment",
+        });
+    }
+    if (url.username.length > 0 || url.password.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "must not contain userinfo",
+        });
+    }
+    if (url.protocol === "https:") {
+        return;
+    }
+    if (url.protocol === "http:") {
+        if (!LOOPBACK_HOSTS.has(url.hostname)) {
+            context.addIssue({
+                code: "custom",
+                message: "http is permitted only on a loopback host",
+            });
+        }
+        return;
+    }
+    // A private-use scheme. The dot is RFC 8252's own test for one, and it is
+    // what keeps `myapp:/callback` — a scheme anybody could claim — out.
+    if (!url.protocol.slice(0, -1).includes(".")) {
+        context.addIssue({
+            code: "custom",
+            message: "must be https, http on a loopback host, or a private-use scheme in reverse-domain form",
+        });
+    }
+});
+/** Whether a redirect URI names a loopback listener. Exported for the store. */
+export function isLoopbackRedirect(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The most redirect URIs one client may register. */
+export const MAX_REDIRECT_URIS = 8;
+/**
+ * RFC 7591 dynamic client registration.
+ *
+ * Registration is open — no credential is required to call it — and that is a
+ * deliberate, bounded decision rather than an oversight. An MCP client
+ * discovers this server, registers itself, and only then asks a human to
+ * approve it; requiring a credential first would mean every client had to be
+ * provisioned by hand before anyone could try it, which is the friction dynamic
+ * registration exists to remove.
+ *
+ * What makes it safe is that **a registered client holds no authority at all**.
+ * It cannot read, write, or name anything until a signed-in member approves a
+ * grant, and that grant is capped by the member's own role. The worst a
+ * registration flood achieves is rows in a table, which is a rate-limiting
+ * problem — W7-03's, and named there rather than solved here with an unmeasured
+ * limit.
+ *
+ * Unknown fields are dropped rather than refused. RFC 7591 §2 lets a client send
+ * metadata a server does not implement, and says the server returns what it
+ * actually registered — so a client sending `logo_uri` gets a registration back
+ * without one, not a 400.
+ */
+/**
+ * A URL the consent screen may put in front of a human.
+ *
+ * `https` and nothing else. The scheme check is the whole guard: `javascript:`
+ * and `data:` are the ones that execute, and `http:` is the one an intermediary
+ * can rewrite — on the page where what the human sees *is* the decision.
+ */
+export const httpsUriSchema = z
+    .url()
+    .max(2048)
+    .refine((value) => value.toLowerCase().startsWith("https://"), {
+    message: "must be an https URL",
+});
+export const clientRegistrationRequestSchema = z.object({
+    client_name: z.string().min(1).max(120),
+    client_uri: z.url().max(2048).optional(),
+    grant_types: z.array(oauthGrantTypeSchema).min(1).optional(),
+    /**
+     * RFC 7591 §2's presentation metadata, carried because the consent screen is
+     * where a human decides whether to trust the asking application.
+     *
+     * **`https` only, and enforced rather than described.** Both review lenses
+     * found this claiming the restriction in a comment while validating with a
+     * bare `z.url()`, which accepts `http:`, `javascript:` and `data:` — on
+     * fields a stranger sets through open registration and a human then reads
+     * while deciding whether to grant access. Nothing rendered them yet, which is
+     * the only reason it was not live cross-site scripting; the next story to
+     * wire them into an `href` would have inherited it, trusting the comment.
+     */
+    logo_uri: httpsUriSchema.optional(),
+    policy_uri: httpsUriSchema.optional(),
+    redirect_uris: z.array(redirectUriSchema).min(1).max(MAX_REDIRECT_URIS),
+    response_types: z.array(z.enum(OAUTH_RESPONSE_TYPES)).min(1).optional(),
+    scope: z.string().max(1024).optional(),
+    token_endpoint_auth_method: z.enum(TOKEN_ENDPOINT_AUTH_METHODS).optional(),
+    tos_uri: httpsUriSchema.optional(),
+});
+/**
+ * What registration answers with, RFC 7591 §3.2.1.
+ *
+ * No `client_secret`, and no `client_secret_expires_at` either — RFC 7591 says
+ * the latter is required *when a secret is issued*, and emitting it as `0`
+ * alongside no secret is how a client concludes it has a non-expiring one.
+ */
+export const clientRegistrationSchema = z.object({
+    client_id: oauthClientIdSchema,
+    client_id_issued_at: z.number().int().positive(),
+    client_name: z.string(),
+    client_uri: z.string().optional(),
+    grant_types: z.array(oauthGrantTypeSchema),
+    logo_uri: z.string().optional(),
+    policy_uri: z.string().optional(),
+    redirect_uris: z.array(z.string()),
+    response_types: z.array(z.enum(OAUTH_RESPONSE_TYPES)),
+    scope: z.string(),
+    token_endpoint_auth_method: z.enum(TOKEN_ENDPOINT_AUTH_METHODS),
+    tos_uri: z.string().optional(),
+});
+/**
+ * Scopes on the wire are one space-delimited string, RFC 6749 §3.3.
+ *
+ * Parsing drops anything not in `SCOPES` rather than refusing the request. The
+ * choice matters and follows `capScopesToRole`: a client asking for a scope this
+ * server does not know is asking for less than it thought, and the consent
+ * screen shows what it will actually get. Refusing outright would break every
+ * client that sends a scope some other server understood.
+ *
+ * A request whose scopes *all* fall away is a different case and is refused as
+ * `invalid_scope` by the caller — asking for nothing this server can grant is a
+ * mistake worth reporting.
+ */
+export function parseScopeString(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const requested = new Set(value.split(/\s+/u).filter((entry) => entry.length > 0));
+    return SCOPES.filter((scope) => requested.has(scope));
+}
+/** The inverse. Ordered by `SCOPES` so one grant has exactly one spelling. */
+export function formatScopeString(scopes) {
+    const held = new Set(scopes);
+    return SCOPES.filter((scope) => held.has(scope)).join(" ");
+}
+/**
+ * The authorization request, as it arrives on the query string.
+ *
+ * Everything is a string because a query string has no other type, and the
+ * coercions happen here rather than in the route. `state` is opaque and echoed
+ * back untouched — it is the client's CSRF defence and this server has no
+ * business interpreting it.
+ *
+ * `resource` is RFC 8707's, and MCP's authorization specification requires
+ * clients to send it. It is validated against this server's own resource
+ * identifier rather than merely recorded: a token minted for one audience and
+ * accepted by another is the confused-deputy problem RFC 8707 exists to close.
+ */
+export const authorizationParametersSchema = z.object({
+    client_id: oauthClientIdSchema,
+    code_challenge: z.string().regex(PKCE_CHALLENGE_PATTERN),
+    code_challenge_method: pkceMethodSchema,
+    redirect_uri: z.string().min(1).max(2048),
+    resource: z.string().max(2048).optional(),
+    response_type: z.enum(OAUTH_RESPONSE_TYPES),
+    scope: z.string().max(1024).optional(),
+    state: z.string().max(512).optional(),
+});
+/**
+ * What the consent screen is given to render.
+ *
+ * It names the client, the scopes, and the projects the member may grant
+ * within — architecture section 8 requires consent to name project, environment
+ * and scopes, and a screen that cannot show them cannot obtain that consent.
+ *
+ * `scopes` here is already capped to the member's current role, so the screen
+ * never displays a permission that would not actually be granted. A member who
+ * asked for `credentials:write` and holds `member` sees the reduced list, which
+ * is the honest thing to show and is also what will be recorded.
+ */
+export const consentPromptSchema = z.object({
+    client: z.object({
+        id: oauthClientIdSchema,
+        /**
+         * What the screen shows so a human can tell *who* is asking.
+         *
+         * All optional, and all attacker-controlled: a client registers itself and
+         * chooses its own name and logo. The screen must present them as claims
+         * rather than as endorsements — the value that is not attacker-controlled is
+         * `redirectUri`, which is where the access would actually go.
+         */
+        logoUri: z.string().optional(),
+        name: z.string(),
+        policyUri: z.string().optional(),
+        termsUri: z.string().optional(),
+        uri: z.string().optional(),
+    }),
+    /**
+     * The environments a grant may name. Both, always: a project owns one of each
+     * by construction, and the choice is the member's rather than the client's.
+     */
+    environmentKinds: z.array(environmentKindSchema).min(1),
+    expiresAt: timestampSchema,
+    /** Where the code will be delivered, so a human can check it. */
+    redirectUri: z.string(),
+    /**
+     * Active projects the member may grant within. Empty means the organization
+     * has no project yet, which the screen has to say rather than presenting an
+     * empty picker.
+     *
+     * A display aid rather than an authorization control: whatever the screen
+     * shows, the decision is re-resolved through `resolveAuthority`, so a project
+     * this list omitted — or one it should have — is decided there.
+     */
+    projects: z
+        .array(z.object({ id: projectIdSchema, name: z.string() }))
+        .max(200),
+    /** Scopes that would be granted: requested, capped by the member's role. */
+    scopes: z.array(scopeSchema),
+});
+/**
+ * The member's decision.
+ *
+ * `scopes` is the member's own narrowing — a consent screen that only offered
+ * all-or-nothing would train people to click through. It is intersected with
+ * what was requested and with the role ceiling, so it can only ever reduce.
+ *
+ * `project` and `environmentKind` are the *authority* the grant will carry, and
+ * they are chosen here rather than requested by the client. A client that could
+ * name a project would be selecting a tenant, which the `/v1` conventions forbid
+ * outright and which is no less forbidden because the request arrived through a
+ * browser.
+ */
+export const consentDecisionSchema = z.discriminatedUnion("decision", [
+    z.object({
+        decision: z.literal("approve"),
+        environmentKind: environmentKindSchema,
+        project: projectIdSchema,
+        scopes: z.array(scopeSchema).min(1),
+    }),
+    z.object({ decision: z.literal("deny") }),
+]);
+/**
+ * Where to send the browser next.
+ *
+ * Returned as a body rather than served as a 302, because the caller is the
+ * consent screen's `fetch` rather than the browser itself — a redirect answered
+ * to `fetch` would be followed by the client, delivering the code to the
+ * consent screen's own JavaScript instead of to the client's redirect URI.
+ */
+export const consentOutcomeSchema = z.object({
+    redirectTo: z.string(),
+});
+/** RFC 6749 §5.1. `expires_in` is seconds, and relative, as the standard says. */
+export const tokenResponseSchema = z.object({
+    access_token: z.string(),
+    expires_in: z.number().int().positive(),
+    refresh_token: z.string(),
+    scope: z.string(),
+    token_type: z.literal("Bearer"),
+});
+/**
+ * The token request, form-encoded per RFC 6749 §4.1.3 and §6.
+ *
+ * A discriminated union on `grant_type` so the two exchanges cannot borrow each
+ * other's fields: an authorization-code request without a `code_verifier` is
+ * refused by the shape rather than by a check somebody has to remember, which is
+ * what makes "PKCE is mandatory" a property of the contract.
+ */
+export const tokenRequestSchema = z.discriminatedUnion("grant_type", [
+    z.object({
+        client_id: oauthClientIdSchema,
+        code: z.string().min(1).max(256),
+        code_verifier: z.string().regex(PKCE_VERIFIER_PATTERN),
+        grant_type: z.literal("authorization_code"),
+        redirect_uri: z.string().min(1).max(2048),
+        resource: z.string().max(2048).optional(),
+    }),
+    z.object({
+        client_id: oauthClientIdSchema,
+        grant_type: z.literal("refresh_token"),
+        refresh_token: z.string().min(1).max(256),
+        resource: z.string().max(2048).optional(),
+        scope: z.string().max(1024).optional(),
+    }),
+]);
+/** RFC 7009 §2.1. The hint is advisory and this server ignores it. */
+export const revocationRequestSchema = z.object({
+    client_id: oauthClientIdSchema,
+    token: z.string().min(1).max(256),
+    token_type_hint: z.enum(["access_token", "refresh_token"]).optional(),
+});
+/**
+ * What became of a grant.
+ *
+ * `revoked` is terminal and covers every way a grant dies — the member revoked
+ * it, a code or refresh token was replayed, or the client revoked its own token.
+ * There is no `expired` state: a grant whose refresh token lapsed is still a
+ * grant the member may want to see and revoke, and collapsing it into `revoked`
+ * would say somebody decided something when nobody did.
+ */
+export const OAUTH_GRANT_STATUSES = ["active", "revoked"];
+export const oauthGrantStatusSchema = z.enum(OAUTH_GRANT_STATUSES);
+/**
+ * Why a grant became terminal.
+ *
+ * Recorded because "my integration stopped working" is a support question, and
+ * the four answers are genuinely different: somebody revoked it deliberately,
+ * the client revoked its own token, or one of the two replay defences fired.
+ * The last two are security events and the first two are not, and an audit trail
+ * that cannot tell them apart cannot answer either question.
+ */
+export const OAUTH_REVOCATION_REASONS = [
+    "authorization-code-replayed",
+    "client-revoked",
+    "member-revoked",
+    "refresh-token-replayed",
+];
+export const oauthRevocationReasonSchema = z.enum(OAUTH_REVOCATION_REASONS);
+/**
+ * A grant as the member sees it. No token material, present or past.
+ *
+ * This is the shape architecture section 8's "user-visible grant revocation"
+ * needs: enough to recognise which application this is and decide whether to
+ * keep it, and nothing that would let a reader of the list use it.
+ */
+export const oauthGrantSchema = z.object({
+    client: z.object({ id: oauthClientIdSchema, name: z.string() }),
+    createdAt: timestampSchema,
+    environmentKind: environmentKindSchema,
+    id: oauthGrantIdSchema,
+    lastUsedAt: timestampSchema.optional(),
+    project: projectIdSchema,
+    revocationReason: oauthRevocationReasonSchema.optional(),
+    revokedAt: timestampSchema.optional(),
+    scopes: z.array(scopeSchema).min(1),
+    status: oauthGrantStatusSchema,
+});
+export const oauthGrantListSchema = z.object({
+    data: z.array(oauthGrantSchema),
+});
+/**
+ * What disconnecting answers with.
+ *
+ * The grant rather than an empty body, for the reason `credentialRevokedSchema`
+ * gives: a member who clicked disconnect wants to see *which* connection stopped
+ * and when, and a 204 makes them ask for that separately.
+ */
+export const oauthGrantRevokedSchema = z.object({ grant: oauthGrantSchema });
+/**
+ * RFC 8414 authorization server metadata.
+ *
+ * Only the fields a client uses are advertised. Two are worth noting for what
+ * they refuse rather than what they offer: `code_challenge_methods_supported` is
+ * `["S256"]`, which tells a conforming client that `plain` will be rejected
+ * before it tries; and `grant_types_supported` omits everything OAuth 2.1
+ * removed, so a client cannot conclude from silence that implicit is available.
+ */
+export const authorizationServerMetadataSchema = z.object({
+    authorization_endpoint: z.url(),
+    code_challenge_methods_supported: z.array(z.enum(PKCE_METHODS)).min(1),
+    grant_types_supported: z.array(oauthGrantTypeSchema).min(1),
+    issuer: z.url(),
+    registration_endpoint: z.url(),
+    response_modes_supported: z.array(z.literal("query")).min(1),
+    response_types_supported: z.array(z.enum(OAUTH_RESPONSE_TYPES)).min(1),
+    revocation_endpoint: z.url(),
+    scopes_supported: z.array(scopeSchema).min(1),
+    token_endpoint: z.url(),
+    token_endpoint_auth_methods_supported: z
+        .array(z.enum(TOKEN_ENDPOINT_AUTH_METHODS))
+        .min(1),
+});
+/**
+ * RFC 9728 protected resource metadata.
+ *
+ * This is where an MCP client's discovery actually begins: it calls a protected
+ * endpoint, receives 401 with `WWW-Authenticate: Bearer resource_metadata=…`,
+ * fetches this document, and learns which authorization server to talk to. A
+ * server that serves the RFC 8414 document but not this one is discoverable only
+ * by clients that already knew where to look.
+ */
+export const protectedResourceMetadataSchema = z.object({
+    authorization_servers: z.array(z.url()).min(1),
+    bearer_methods_supported: z.array(z.literal("header")).min(1),
+    resource: z.url(),
+    scopes_supported: z.array(scopeSchema).min(1),
+});
+/**
+ * The `WWW-Authenticate` value a protected endpoint returns on 401.
+ *
+ * RFC 9728 §5.1. The `resource_metadata` parameter is the whole mechanism —
+ * without it a client that receives a 401 knows only that it is unauthenticated,
+ * and has nowhere to go next.
+ */
+export function bearerChallenge(resourceMetadataUrl) {
+    return `Bearer resource_metadata="${resourceMetadataUrl}"`;
+}