@greatwait/contracts 0.1.0-alpha.1

package/dist/oauth.d.ts

@@ -0,0 +1,796 @@
+import { z } from "zod";
+import { type Scope } from "./authority.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 declare const OAUTH_ROUTES: {
+    /** RFC 8414 authorization server metadata. */
+    readonly authorizationServerMetadata: "/.well-known/oauth-authorization-server";
+    /** The browser-facing start of the flow. */
+    readonly authorize: "/oauth/authorize";
+    /** What the consent screen reads to render itself. Session-authenticated. */
+    readonly authorizationRequest: "/oauth/authorization-requests/:authorizationRequestId";
+    /** Where the consent screen posts approve or deny. Session-authenticated. */
+    readonly consent: "/oauth/authorization-requests/:authorizationRequestId/consent";
+    /** RFC 9728 protected resource metadata, which is how MCP clients start. */
+    readonly protectedResourceMetadata: "/.well-known/oauth-protected-resource";
+    /** RFC 7591 dynamic client registration. */
+    readonly register: "/oauth/register";
+    /** RFC 7009 token revocation. */
+    readonly revoke: "/oauth/revoke";
+    /** RFC 6749 token endpoint. */
+    readonly 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 declare const OAUTH_ERRORS: readonly ["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 declare const oauthErrorCodeSchema: z.ZodEnum<{
+    invalid_request: "invalid_request";
+    access_denied: "access_denied";
+    invalid_client: "invalid_client";
+    invalid_client_metadata: "invalid_client_metadata";
+    invalid_grant: "invalid_grant";
+    invalid_redirect_uri: "invalid_redirect_uri";
+    invalid_scope: "invalid_scope";
+    invalid_target: "invalid_target";
+    server_error: "server_error";
+    temporarily_unavailable: "temporarily_unavailable";
+    unauthorized_client: "unauthorized_client";
+    unsupported_grant_type: "unsupported_grant_type";
+    unsupported_response_type: "unsupported_response_type";
+}>;
+export type OAuthErrorCode = z.infer<typeof oauthErrorCodeSchema>;
+/**
+ * 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 declare const oauthErrorSchema: z.ZodObject<{
+    error: z.ZodEnum<{
+        invalid_request: "invalid_request";
+        access_denied: "access_denied";
+        invalid_client: "invalid_client";
+        invalid_client_metadata: "invalid_client_metadata";
+        invalid_grant: "invalid_grant";
+        invalid_redirect_uri: "invalid_redirect_uri";
+        invalid_scope: "invalid_scope";
+        invalid_target: "invalid_target";
+        server_error: "server_error";
+        temporarily_unavailable: "temporarily_unavailable";
+        unauthorized_client: "unauthorized_client";
+        unsupported_grant_type: "unsupported_grant_type";
+        unsupported_response_type: "unsupported_response_type";
+    }>;
+    error_description: z.ZodOptional<z.ZodString>;
+    error_uri: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type OAuthErrorBody = z.infer<typeof oauthErrorSchema>;
+/**
+ * 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 declare const OAUTH_ERROR_STATUS: Readonly<Record<OAuthErrorCode, 400 | 401 | 500 | 503>>;
+/**
+ * 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 declare function oauthError(error: OAuthErrorCode, description?: string): {
+    readonly body: OAuthErrorBody;
+    readonly status: 400 | 401 | 500 | 503;
+};
+/**
+ * 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 declare const OAUTH_GRANT_TYPES: readonly ["authorization_code", "refresh_token"];
+export declare const oauthGrantTypeSchema: z.ZodEnum<{
+    authorization_code: "authorization_code";
+    refresh_token: "refresh_token";
+}>;
+export type OAuthGrantType = z.infer<typeof oauthGrantTypeSchema>;
+/** Authorization code is the only response type. See above. */
+export declare const OAUTH_RESPONSE_TYPES: readonly ["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 declare const PKCE_METHODS: readonly ["S256"];
+export declare const pkceMethodSchema: z.ZodEnum<{
+    S256: "S256";
+}>;
+/**
+ * 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 declare const PKCE_VERIFIER_PATTERN: RegExp;
+/** The base64url SHA-256 of a verifier: 43 characters, no padding. */
+export declare const PKCE_CHALLENGE_PATTERN: RegExp;
+/**
+ * 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 declare const TOKEN_ENDPOINT_AUTH_METHODS: readonly ["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 declare 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 declare 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 declare 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 declare const REFRESH_TOKEN_TTL_SECONDS = 2592000;
+/**
+ * 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 declare 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 declare const OAUTH_TOKEN_SECRET_LENGTH = 48;
+export declare const ACCESS_TOKEN_PATTERN: RegExp;
+export declare const REFRESH_TOKEN_PATTERN: RegExp;
+export declare const AUTHORIZATION_CODE_PATTERN: RegExp;
+/** Any of the three, for the one place that has to tell ours from anything else. */
+export declare const OAUTH_SECRET_PATTERN: RegExp;
+export declare const redirectUriSchema: z.ZodString;
+/** Whether a redirect URI names a loopback listener. Exported for the store. */
+export declare function isLoopbackRedirect(value: string): boolean;
+/** The most redirect URIs one client may register. */
+export declare 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 declare const httpsUriSchema: z.ZodURL;
+export declare const clientRegistrationRequestSchema: z.ZodObject<{
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodURL>;
+    grant_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>>;
+    logo_uri: z.ZodOptional<z.ZodURL>;
+    policy_uri: z.ZodOptional<z.ZodURL>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    response_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        code: "code";
+    }>>>;
+    scope: z.ZodOptional<z.ZodString>;
+    token_endpoint_auth_method: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+    }>>;
+    tos_uri: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type ClientRegistrationRequest = z.infer<typeof clientRegistrationRequestSchema>;
+/**
+ * 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 declare const clientRegistrationSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_id_issued_at: z.ZodNumber;
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodString>;
+    grant_types: z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>;
+    logo_uri: z.ZodOptional<z.ZodString>;
+    policy_uri: z.ZodOptional<z.ZodString>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    response_types: z.ZodArray<z.ZodEnum<{
+        code: "code";
+    }>>;
+    scope: z.ZodString;
+    token_endpoint_auth_method: z.ZodEnum<{
+        none: "none";
+    }>;
+    tos_uri: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ClientRegistration = z.infer<typeof clientRegistrationSchema>;
+/**
+ * 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 declare function parseScopeString(value: string | undefined): readonly Scope[];
+/** The inverse. Ordered by `SCOPES` so one grant has exactly one spelling. */
+export declare function formatScopeString(scopes: readonly Scope[]): string;
+/**
+ * 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 declare const authorizationParametersSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    code_challenge: z.ZodString;
+    code_challenge_method: z.ZodEnum<{
+        S256: "S256";
+    }>;
+    redirect_uri: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    response_type: z.ZodEnum<{
+        code: "code";
+    }>;
+    scope: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuthorizationParameters = z.infer<typeof authorizationParametersSchema>;
+/**
+ * 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 declare const consentPromptSchema: z.ZodObject<{
+    client: z.ZodObject<{
+        id: z.ZodString;
+        logoUri: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        policyUri: z.ZodOptional<z.ZodString>;
+        termsUri: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    environmentKinds: z.ZodArray<z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>>;
+    expiresAt: z.ZodString;
+    redirectUri: z.ZodString;
+    projects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, z.core.$strip>;
+export type ConsentPrompt = z.infer<typeof consentPromptSchema>;
+/**
+ * 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 declare const consentDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    decision: z.ZodLiteral<"approve">;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    project: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    decision: z.ZodLiteral<"deny">;
+}, z.core.$strip>], "decision">;
+export type ConsentDecision = z.infer<typeof consentDecisionSchema>;
+/**
+ * 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 declare const consentOutcomeSchema: z.ZodObject<{
+    redirectTo: z.ZodString;
+}, z.core.$strip>;
+export type ConsentOutcome = z.infer<typeof consentOutcomeSchema>;
+/** RFC 6749 §5.1. `expires_in` is seconds, and relative, as the standard says. */
+export declare const tokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    expires_in: z.ZodNumber;
+    refresh_token: z.ZodString;
+    scope: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+}, z.core.$strip>;
+export type TokenResponse = z.infer<typeof tokenResponseSchema>;
+/**
+ * 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 declare const tokenRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    client_id: z.ZodString;
+    code: z.ZodString;
+    code_verifier: z.ZodString;
+    grant_type: z.ZodLiteral<"authorization_code">;
+    redirect_uri: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    client_id: z.ZodString;
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "grant_type">;
+export type TokenRequest = z.infer<typeof tokenRequestSchema>;
+/** RFC 7009 §2.1. The hint is advisory and this server ignores it. */
+export declare const revocationRequestSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    token: z.ZodString;
+    token_type_hint: z.ZodOptional<z.ZodEnum<{
+        refresh_token: "refresh_token";
+        access_token: "access_token";
+    }>>;
+}, z.core.$strip>;
+export type RevocationRequest = z.infer<typeof revocationRequestSchema>;
+/**
+ * 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 declare const OAUTH_GRANT_STATUSES: readonly ["active", "revoked"];
+export declare const oauthGrantStatusSchema: z.ZodEnum<{
+    active: "active";
+    revoked: "revoked";
+}>;
+export type OAuthGrantStatus = z.infer<typeof oauthGrantStatusSchema>;
+/**
+ * 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 declare const OAUTH_REVOCATION_REASONS: readonly ["authorization-code-replayed", "client-revoked", "member-revoked", "refresh-token-replayed"];
+export declare const oauthRevocationReasonSchema: z.ZodEnum<{
+    "authorization-code-replayed": "authorization-code-replayed";
+    "client-revoked": "client-revoked";
+    "member-revoked": "member-revoked";
+    "refresh-token-replayed": "refresh-token-replayed";
+}>;
+export type OAuthRevocationReason = z.infer<typeof oauthRevocationReasonSchema>;
+/**
+ * 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 declare const oauthGrantSchema: z.ZodObject<{
+    client: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    id: z.ZodString;
+    lastUsedAt: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
+    revocationReason: z.ZodOptional<z.ZodEnum<{
+        "authorization-code-replayed": "authorization-code-replayed";
+        "client-revoked": "client-revoked";
+        "member-revoked": "member-revoked";
+        "refresh-token-replayed": "refresh-token-replayed";
+    }>>;
+    revokedAt: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+    status: z.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+    }>;
+}, z.core.$strip>;
+export type OAuthGrant = z.infer<typeof oauthGrantSchema>;
+export declare const oauthGrantListSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        client: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        createdAt: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        id: z.ZodString;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revocationReason: z.ZodOptional<z.ZodEnum<{
+            "authorization-code-replayed": "authorization-code-replayed";
+            "client-revoked": "client-revoked";
+            "member-revoked": "member-revoked";
+            "refresh-token-replayed": "refresh-token-replayed";
+        }>>;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+        status: z.ZodEnum<{
+            active: "active";
+            revoked: "revoked";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OAuthGrantList = z.infer<typeof oauthGrantListSchema>;
+/**
+ * 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 declare const oauthGrantRevokedSchema: z.ZodObject<{
+    grant: z.ZodObject<{
+        client: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        createdAt: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        id: z.ZodString;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revocationReason: z.ZodOptional<z.ZodEnum<{
+            "authorization-code-replayed": "authorization-code-replayed";
+            "client-revoked": "client-revoked";
+            "member-revoked": "member-revoked";
+            "refresh-token-replayed": "refresh-token-replayed";
+        }>>;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+        status: z.ZodEnum<{
+            active: "active";
+            revoked: "revoked";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type OAuthGrantRevoked = z.infer<typeof oauthGrantRevokedSchema>;
+/**
+ * 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 declare const authorizationServerMetadataSchema: z.ZodObject<{
+    authorization_endpoint: z.ZodURL;
+    code_challenge_methods_supported: z.ZodArray<z.ZodEnum<{
+        S256: "S256";
+    }>>;
+    grant_types_supported: z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>;
+    issuer: z.ZodURL;
+    registration_endpoint: z.ZodURL;
+    response_modes_supported: z.ZodArray<z.ZodLiteral<"query">>;
+    response_types_supported: z.ZodArray<z.ZodEnum<{
+        code: "code";
+    }>>;
+    revocation_endpoint: z.ZodURL;
+    scopes_supported: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+    token_endpoint: z.ZodURL;
+    token_endpoint_auth_methods_supported: z.ZodArray<z.ZodEnum<{
+        none: "none";
+    }>>;
+}, z.core.$strip>;
+export type AuthorizationServerMetadata = z.infer<typeof authorizationServerMetadataSchema>;
+/**
+ * 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 declare const protectedResourceMetadataSchema: z.ZodObject<{
+    authorization_servers: z.ZodArray<z.ZodURL>;
+    bearer_methods_supported: z.ZodArray<z.ZodLiteral<"header">>;
+    resource: z.ZodURL;
+    scopes_supported: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, z.core.$strip>;
+export type ProtectedResourceMetadata = z.infer<typeof protectedResourceMetadataSchema>;
+/**
+ * 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 declare function bearerChallenge(resourceMetadataUrl: string): string;