@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/oauth/server.js

@@ -0,0 +1,769 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { BASE_PATH } from "../api.js";
+import { CurrentPrincipal, withPrincipal } from "../authentication.js";
+import { RequestId, errorBodyForWire } from "../errors.js";
+import { fixedWindowLimiter, clientAddress } from "../rate-limit.js";
+import { OntologyBackend, } from "../runtime-contract.js";
+import { ACCESS_TOKEN_PREFIX, appSessionResource, ACCESS_TOKEN_TTL_MS, AUTHORIZATION_SERVER_PATH, CLIENT_ID_PREFIX, CLIENT_SECRET_PREFIX, CODE_PREFIX, CODE_TTL_MS, DEVICE_GRANT, DEVICE_TTL_MS, DEVICE_INTERVAL, humanCode, normalizedUserCode, CONSENT_PATH, FULL_SCOPE, PROTECTED_RESOURCE_PATH, READ_SCOPE, REFRESH_TOKEN_PREFIX, REFRESH_TOKEN_TTL_MS, REQUEST_TTL_MS, SCOPES, grantedScope, isLoopback, newSecret, publicOrigin, sameSecret, sameResource, secretHash, verifierMatches, } from "./protocol.js";
+import { decryptReplay, encryptReplay } from "./refresh-replay.js";
+/** The authorization server's endpoints, under the ontology service's path. */
+export const OAUTH_PATH = `${BASE_PATH}/oauth`;
+const REGISTER_PATH = `${OAUTH_PATH}/register`;
+const AUTHORIZE_PATH = `${OAUTH_PATH}/authorize`;
+const DEVICE_PATH = `${OAUTH_PATH}/device_authorization`;
+const DEVICE_REQUEST_PATH = `${OAUTH_PATH}/device`;
+const TOKEN_PATH = `${OAUTH_PATH}/token`;
+const REVOKE_PATH = `${OAUTH_PATH}/revoke`;
+const REQUESTS_PATH = `${OAUTH_PATH}/requests`;
+/** Registrations one client address may make per minute; each one is a row in the database. */
+export const REGISTRATION_LIMIT = { limit: 20, windowMs: 60_000, maxKeys: 10_000 };
+const MAX_REDIRECT_URIS = 10;
+const MAX_URI_LENGTH = 2000;
+const MAX_NAME_LENGTH = 100;
+const MAX_STATE_LENGTH = 1000;
+/** The metadata, registration, token and revocation endpoints are read by clients on any origin. */
+const CORS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET, POST, OPTIONS",
+    "access-control-allow-headers": "authorization, content-type, mcp-protocol-version",
+};
+const NO_STORE = { "cache-control": "no-store", pragma: "no-cache" };
+function json(body, status = 200, headers = {}) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: { ...CORS, ...headers } });
+}
+/** An OAuth error (RFC 6749 §5.2), as the token, registration and revocation endpoints answer. */
+function oauthError(error, description, status = 400) {
+    return json({ error, error_description: description }, status, error === "invalid_client"
+        ? { "www-authenticate": 'Basic realm="ontology"', ...NO_STORE }
+        : NO_STORE);
+}
+/** Where the MCP server is, on the origin the client reached. */
+export function mcpResource(origin) {
+    return `${origin}/mcp`;
+}
+/**
+ * The `WWW-Authenticate` challenge of the MCP server: it names the protected resource metadata,
+ * which is how a client learns where members authorize it (RFC 9728).
+ */
+export function mcpChallenge(origin, missing) {
+    const metadata = `resource_metadata="${origin}${PROTECTED_RESOURCE_PATH}/mcp"`;
+    return missing
+        ? `Bearer ${metadata}, scope="${FULL_SCOPE}"`
+        : `Bearer error="invalid_token", ${metadata}`;
+}
+function protectedResourceMetadata(origin) {
+    return {
+        resource: mcpResource(origin),
+        authorization_servers: [origin],
+        scopes_supported: SCOPES,
+        bearer_methods_supported: ["header"],
+        resource_name: "Ontology",
+    };
+}
+function authorizationServerMetadata(origin) {
+    const authMethods = [
+        "none",
+        "client_secret_post",
+        "client_secret_basic",
+    ];
+    return {
+        issuer: origin,
+        authorization_endpoint: `${origin}${AUTHORIZE_PATH}`,
+        token_endpoint: `${origin}${TOKEN_PATH}`,
+        registration_endpoint: `${origin}${REGISTER_PATH}`,
+        revocation_endpoint: `${origin}${REVOKE_PATH}`,
+        scopes_supported: SCOPES,
+        response_types_supported: ["code"],
+        response_modes_supported: ["query"],
+        device_authorization_endpoint: `${origin}${DEVICE_PATH}`,
+        grant_types_supported: ["authorization_code", "refresh_token", DEVICE_GRANT],
+        token_endpoint_auth_methods_supported: authMethods,
+        revocation_endpoint_auth_methods_supported: authMethods,
+        code_challenge_methods_supported: ["S256"],
+        authorization_response_iss_parameter_supported: true,
+    };
+}
+function searchParams(request) {
+    return Object.fromEntries(new URL(request.url, "http://ontology.invalid").searchParams);
+}
+/** A form body (RFC 6749 §4.1.3), or a JSON object from clients that send one. */
+function bodyParams(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        const contentType = request.headers["content-type"]?.toLowerCase() ?? "";
+        if (contentType.includes("application/json")) {
+            try {
+                const parsed = JSON.parse(text);
+                return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+                    ? Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === "string"))
+                    : {};
+            }
+            catch {
+                return {};
+            }
+        }
+        return Object.fromEntries(new URLSearchParams(text));
+    });
+}
+function jsonBody(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+/** Why a redirect URI cannot be registered, or `undefined` when it can (RFC 8252 for native apps). */
+function redirectUriProblem(value) {
+    if (typeof value !== "string" || value.length > MAX_URI_LENGTH || !URL.canParse(value)) {
+        return "is not an absolute URL";
+    }
+    const url = new URL(value);
+    if (url.hash !== "") {
+        return "has a fragment";
+    }
+    if (url.protocol === "https:") {
+        return undefined;
+    }
+    if (url.protocol === "http:") {
+        return isLoopback(url.host) ? undefined : "uses http on a host other than this computer";
+    }
+    if (["javascript:", "data:", "file:", "vbscript:", "blob:", "about:"].includes(url.protocol)) {
+        return "uses a scheme that cannot receive a redirect";
+    }
+    // A native app's private-use scheme, such as cursor://.
+    return undefined;
+}
+/**
+ * Whether a redirect URI is one the client registered. A loopback URI matches on any port, as
+ * native apps listen on whichever port is free (RFC 8252 §7.3).
+ */
+function registeredRedirect(client, value) {
+    return client.redirectUris.some((registered) => {
+        if (registered === value) {
+            return true;
+        }
+        if (!URL.canParse(registered) || !URL.canParse(value)) {
+            return false;
+        }
+        const expected = new URL(registered);
+        const actual = new URL(value);
+        return (expected.protocol === "http:" &&
+            isLoopback(expected.host) &&
+            actual.protocol === "http:" &&
+            expected.hostname === actual.hostname &&
+            expected.pathname === actual.pathname &&
+            expected.search === actual.search);
+    });
+}
+/** The redirect URI with the response's parameters, and `iss` to name this server (RFC 9207). */
+function redirectWith(redirectUri, params) {
+    const url = new URL(redirectUri);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== null) {
+            url.searchParams.set(key, value);
+        }
+    }
+    return url.toString();
+}
+/** A page for problems the client cannot be told about, because its redirect URI is not trusted. */
+function authorizeFailure(detail) {
+    return HttpServerResponse.text(`This authorization link cannot be used: ${detail}`, {
+        status: 400,
+        headers: NO_STORE,
+    });
+}
+function register(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        if (limiter.take(clientAddress(request)) !== undefined) {
+            return oauthError("too_many_requests", "Too many registrations; try again in a minute.", 429);
+        }
+        const body = yield* jsonBody(request);
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+            return oauthError("invalid_client_metadata", "Send the client metadata as a JSON object.");
+        }
+        const metadata = body;
+        const deviceOnly = Array.isArray(metadata.grant_types) &&
+            metadata.grant_types.includes(DEVICE_GRANT) &&
+            !metadata.grant_types.includes("authorization_code");
+        const redirectUris = metadata.redirect_uris ?? (deviceOnly ? [] : undefined);
+        if (!Array.isArray(redirectUris) ||
+            (!deviceOnly && redirectUris.length === 0) ||
+            redirectUris.length > MAX_REDIRECT_URIS) {
+            return oauthError("invalid_redirect_uri", `redirect_uris lists between 1 and ${MAX_REDIRECT_URIS} URIs.`);
+        }
+        for (const uri of redirectUris) {
+            const problem = redirectUriProblem(uri);
+            if (problem !== undefined) {
+                return oauthError("invalid_redirect_uri", `${String(uri)} ${problem}.`);
+            }
+        }
+        // RFC 7591 §2: without a method, the client authenticates with client_secret_basic.
+        const authMethod = metadata.token_endpoint_auth_method ?? "client_secret_basic";
+        if (authMethod !== "none" &&
+            authMethod !== "client_secret_post" &&
+            authMethod !== "client_secret_basic") {
+            return oauthError("invalid_client_metadata", "token_endpoint_auth_method is none, client_secret_post or client_secret_basic.");
+        }
+        const grantTypes = metadata.grant_types ?? ["authorization_code"];
+        const responseTypes = metadata.response_types ?? (deviceOnly ? [] : ["code"]);
+        if (!Array.isArray(grantTypes) ||
+            !grantTypes.every((type) => type === "authorization_code" || type === "refresh_token" || type === DEVICE_GRANT) ||
+            !Array.isArray(responseTypes) ||
+            !responseTypes.every((type) => type === "code")) {
+            return oauthError("invalid_client_metadata", "This server grants authorization_code and refresh_token, with the code response type.");
+        }
+        const name = typeof metadata.client_name === "string" && metadata.client_name.trim() !== ""
+            ? metadata.client_name.trim().slice(0, MAX_NAME_LENGTH)
+            : "An MCP client";
+        const clientUri = typeof metadata.client_uri === "string" &&
+            metadata.client_uri.length <= MAX_URI_LENGTH &&
+            URL.canParse(metadata.client_uri) &&
+            new URL(metadata.client_uri).protocol === "https:"
+            ? metadata.client_uri
+            : null;
+        const secret = authMethod === "none" ? undefined : newSecret(CLIENT_SECRET_PREFIX);
+        const client = {
+            id: newSecret(CLIENT_ID_PREFIX),
+            name,
+            redirectUris: redirectUris,
+            authMethod,
+            secretHash: secret === undefined ? null : secretHash(secret),
+            clientUri,
+        };
+        yield* store.saveClient(client);
+        return json({
+            client_id: client.id,
+            client_id_issued_at: Math.floor(Date.now() / 1000),
+            ...(secret === undefined ? {} : { client_secret: secret, client_secret_expires_at: 0 }),
+            client_name: client.name,
+            redirect_uris: client.redirectUris,
+            token_endpoint_auth_method: client.authMethod,
+            grant_types: grantTypes,
+            response_types: responseTypes,
+            ...(clientUri === null ? {} : { client_uri: clientUri }),
+        }, 201, NO_STORE);
+    });
+}
+/**
+ * `GET /api/ontology/oauth/authorize`: checks the client's request, keeps it for the member to
+ * decide, and sends the browser to the app's consent page, which signs the member in first.
+ */
+function authorize(store) {
+    return (request) => Effect.gen(function* () {
+        const params = searchParams(request);
+        const origin = publicOrigin(request);
+        const client = params.client_id === undefined ? undefined : yield* store.findClient(params.client_id);
+        if (client === undefined) {
+            return authorizeFailure("the client is not registered with this app.");
+        }
+        const redirectUri = params.redirect_uri ??
+            (client.redirectUris.length === 1 ? client.redirectUris[0] : undefined);
+        if (redirectUri === undefined || !registeredRedirect(client, redirectUri)) {
+            return authorizeFailure("the redirect URI is not one the client registered.");
+        }
+        const state = params.state ?? null;
+        const fail = (error, description) => HttpServerResponse.redirect(redirectWith(redirectUri, {
+            error,
+            error_description: description,
+            state,
+            iss: origin,
+        }), { status: 302, headers: NO_STORE });
+        if (params.response_type !== "code") {
+            return fail("unsupported_response_type", "Only the code response type is supported.");
+        }
+        if (params.code_challenge === undefined || params.code_challenge_method !== "S256") {
+            return fail("invalid_request", "PKCE with the S256 method is required.");
+        }
+        if (!/^[A-Za-z0-9_-]{43}$/.test(params.code_challenge)) {
+            return fail("invalid_request", "code_challenge is not an S256 challenge.");
+        }
+        if (state !== null && state.length > MAX_STATE_LENGTH) {
+            return fail("invalid_request", "state is too long.");
+        }
+        const resource = params.resource ?? mcpResource(origin);
+        if (!sameResource(resource, mcpResource(origin))) {
+            return fail("invalid_target", `This server issues tokens for ${mcpResource(origin)} only.`);
+        }
+        const id = newSecret();
+        yield* store.saveRequest({
+            id,
+            clientId: client.id,
+            redirectUri,
+            state,
+            codeChallenge: params.code_challenge,
+            scope: grantedScope(params.scope),
+            resource,
+            expiresAt: new Date(Date.now() + REQUEST_TTL_MS),
+        });
+        return HttpServerResponse.redirect(`${origin}${CONSENT_PATH}?request=${id}`, {
+            status: 302,
+            headers: NO_STORE,
+        });
+    });
+}
+/** The member deciding a request: the requests endpoints answer members only. */
+function requireMember() {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        return principal.kind === "member" ? principal : undefined;
+    });
+}
+function notMember(requestId) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "forbidden",
+        detail: "Only a signed-in member can authorize an agent.",
+        requestId,
+    }), { status: 403 });
+}
+function requestNotFound(requestId, reason) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "not_found",
+        detail: "The authorization request expired or was already decided. Connect the agent again.",
+        ...(reason === undefined ? {} : { reason }),
+        requestId,
+    }), { status: 404 });
+}
+function unavailableDevice(device) {
+    if (device === undefined) {
+        return "unknown";
+    }
+    if (device.status !== "pending") {
+        return "decided";
+    }
+    return device.expiresAt.getTime() <= Date.now() ? "expired" : undefined;
+}
+function routeId() {
+    return Effect.map(HttpRouter.params, (params) => params.id ?? "");
+}
+/** `GET /api/ontology/oauth/requests/:id`: what the consent page shows the member. */
+function describeRequest(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const member = yield* requireMember();
+        if (member === undefined) {
+            return notMember(requestId);
+        }
+        const pending = yield* store.findRequest(yield* routeId());
+        const client = pending === undefined ? undefined : yield* store.findClient(pending.clientId);
+        if (pending === undefined || client === undefined) {
+            return requestNotFound(requestId);
+        }
+        return HttpServerResponse.jsonUnsafe({
+            id: pending.id,
+            client: {
+                name: client.name,
+                uri: client.clientUri,
+                redirect_uri: pending.redirectUri,
+                redirect_host: new URL(pending.redirectUri).host || pending.redirectUri,
+            },
+            scope: pending.scope,
+            permissions: member.permissions,
+            expires_at: pending.expiresAt.toISOString(),
+        }, { headers: NO_STORE });
+    });
+}
+/**
+ * `POST /api/ontology/oauth/requests/:id/approve` and `/deny`: the member's decision, once. The
+ * answer is where the app sends the browser: the client's redirect URI with a code, or with
+ * `access_denied`. A member may narrow the scope to reading only, never widen it.
+ */
+function decideRequest(store, decision, request) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const member = yield* requireMember();
+        if (member === undefined) {
+            return notMember(requestId);
+        }
+        const body = decision === "approve" ? yield* jsonBody(request) : undefined;
+        const pending = yield* store.takeRequest(yield* routeId());
+        if (pending === undefined) {
+            return requestNotFound(requestId);
+        }
+        // The issuer the client discovered: the origin of the MCP server it asked for. The app calls this
+        // endpoint itself, possibly on another origin in development.
+        const origin = new URL(pending.resource).origin;
+        if (decision === "deny") {
+            return HttpServerResponse.jsonUnsafe({
+                redirect: redirectWith(pending.redirectUri, {
+                    error: "access_denied",
+                    error_description: "The member did not authorize the client.",
+                    state: pending.state,
+                    iss: origin,
+                }),
+            });
+        }
+        const narrowed = typeof body === "object" &&
+            body !== null &&
+            body.scope === READ_SCOPE;
+        const grant = {
+            id: randomUUID(),
+            clientId: pending.clientId,
+            userId: member.id,
+            scope: narrowed ? READ_SCOPE : pending.scope,
+            resource: pending.resource,
+        };
+        const code = isLoopback(new URL(pending.redirectUri).host)
+            ? `${CODE_PREFIX}${humanCode(3)}`
+            : newSecret(CODE_PREFIX);
+        yield* store.saveGrant(grant, {
+            hash: secretHash(code),
+            grantId: grant.id,
+            kind: "code",
+            expiresAt: new Date(Date.now() + CODE_TTL_MS),
+            redirectUri: pending.redirectUri,
+            codeChallenge: pending.codeChallenge,
+        });
+        return HttpServerResponse.jsonUnsafe({
+            redirect: redirectWith(pending.redirectUri, { code, state: pending.state, iss: origin }),
+        });
+    });
+}
+/** The client a token or revocation request authenticates as (RFC 6749 §2.3). */
+function authenticateClient(store, request, params) {
+    return Effect.gen(function* () {
+        const authorization = request.headers.authorization ?? "";
+        let clientId = params.client_id;
+        let secret = params.client_secret;
+        let method = secret === undefined ? "none" : "client_secret_post";
+        if (authorization.toLowerCase().startsWith("basic ")) {
+            const decoded = Buffer.from(authorization.slice(6).trim(), "base64").toString("utf8");
+            const separator = decoded.indexOf(":");
+            if (separator > 0) {
+                try {
+                    clientId = decodeURIComponent(decoded.slice(0, separator));
+                    secret = decodeURIComponent(decoded.slice(separator + 1));
+                }
+                catch {
+                    return undefined;
+                }
+                method = "client_secret_basic";
+            }
+        }
+        const client = clientId === undefined ? undefined : yield* store.findClient(clientId);
+        if (client === undefined) {
+            return undefined;
+        }
+        if (client.authMethod === "none") {
+            return client;
+        }
+        return method !== "none" &&
+            secret !== undefined &&
+            client.secretHash !== null &&
+            sameSecret(secret, client.secretHash)
+            ? client
+            : undefined;
+    });
+}
+function issueTokens(store, grant, previous) {
+    return Effect.gen(function* () {
+        const accessToken = newSecret(ACCESS_TOKEN_PREFIX);
+        const refreshToken = newSecret(REFRESH_TOKEN_PREFIX);
+        const now = Date.now();
+        yield* store.saveTokens([
+            {
+                hash: secretHash(accessToken),
+                grantId: grant.id,
+                kind: "access",
+                expiresAt: new Date(now + ACCESS_TOKEN_TTL_MS),
+            },
+            {
+                hash: secretHash(refreshToken),
+                grantId: grant.id,
+                kind: "refresh",
+                expiresAt: new Date(now + REFRESH_TOKEN_TTL_MS),
+            },
+        ]);
+        const response = {
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: refreshToken,
+            scope: grant.scope,
+        };
+        if (previous !== undefined) {
+            yield* store.saveRefreshReplay(secretHash(previous), encryptReplay(previous, {
+                ...response,
+                access_token_expires_at: now + ACCESS_TOKEN_TTL_MS,
+            }), secretHash(refreshToken));
+        }
+        return json(response, 200, NO_STORE);
+    });
+}
+function replayTokens(store, grant, previous, encrypted, graceMs) {
+    return Effect.gen(function* () {
+        const { access_token_expires_at: expiresAt, ...saved } = decryptReplay(previous, encrypted);
+        const now = Date.now();
+        if (expiresAt !== undefined &&
+            expiresAt > now &&
+            now < expiresAt - ACCESS_TOKEN_TTL_MS + graceMs) {
+            return json({ ...saved, expires_in: Math.ceil((expiresAt - now) / 1000) }, 200, NO_STORE);
+        }
+        // A delayed retry can outlive its access token. Keep the same unused refresh successor:
+        // rotating it here would make another lost response unrecoverable again.
+        const response = {
+            ...saved,
+            access_token: newSecret(ACCESS_TOKEN_PREFIX),
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+        };
+        yield* store.saveTokens([
+            {
+                hash: secretHash(response.access_token),
+                grantId: grant.id,
+                kind: "access",
+                expiresAt: new Date(now + ACCESS_TOKEN_TTL_MS),
+            },
+        ]);
+        yield* store.saveRefreshReplay(secretHash(previous), encryptReplay(previous, { ...response, access_token_expires_at: now + ACCESS_TOKEN_TTL_MS }), secretHash(response.refresh_token));
+        return json(response, 200, NO_STORE);
+    });
+}
+/**
+ * `POST /api/ontology/oauth/token`: a code with its PKCE verifier, or a refresh token, for an access
+ * token and a new refresh token. Refresh retries recover their immediate unused successor; reuse
+ * of an older generation revokes the grant. A member who may no longer sign in gets nothing.
+ */
+function token(store, graceMs) {
+    return (request) => Effect.gen(function* () {
+        const params = yield* bodyParams(request);
+        const client = yield* authenticateClient(store, request, params);
+        if (client === undefined) {
+            return oauthError("invalid_client", "The client is unknown or its secret is wrong.", 401);
+        }
+        if (params.grant_type === DEVICE_GRANT) {
+            if (!params.device_code) {
+                return oauthError("invalid_request", "device_code is required.");
+            }
+            const result = yield* store.pollDevice(secretHash(params.device_code), client.id, params.resource);
+            if (result.status !== "approved") {
+                return oauthError(result.status, "The device authorization has not completed.");
+            }
+            const device = result.device;
+            const member = device.userId === null ? undefined : yield* store.memberPrincipal(device.userId);
+            if (member === undefined) {
+                return oauthError("access_denied", "The member can no longer use this app.");
+            }
+            const grant = {
+                id: randomUUID(),
+                clientId: client.id,
+                userId: member.id,
+                resource: device.resource,
+                scope: device.scope,
+            };
+            yield* store.saveGrant(grant);
+            return yield* issueTokens(store, grant);
+        }
+        const kind = params.grant_type === "authorization_code"
+            ? "code"
+            : params.grant_type === "refresh_token"
+                ? "refresh"
+                : undefined;
+        if (kind === undefined) {
+            return oauthError("unsupported_grant_type", "This server supports authorization_code, refresh_token and device_code.");
+        }
+        const presented = kind === "code" ? params.code : params.refresh_token;
+        if (presented === undefined) {
+            return oauthError("invalid_request", kind === "code" ? "code is required." : "refresh_token is required.");
+        }
+        const hash = secretHash(presented);
+        return yield* store.withTokenLock(hash, Effect.gen(function* () {
+            const owner = yield* store.findGrantOfToken(hash);
+            // Authenticate the binding before consumption or reuse detection.
+            if (owner === undefined || owner.clientId !== client.id) {
+                return oauthError("invalid_grant", "The grant is invalid, expired or revoked.");
+            }
+            if (params.resource !== undefined && !sameResource(params.resource, owner.resource)) {
+                return oauthError("invalid_target", "The grant is for a different resource.");
+            }
+            if ((yield* store.memberPrincipal(owner.userId)) === undefined) {
+                // Deny access without permanently destroying authorization on an inconclusive lookup.
+                return oauthError("invalid_grant", "The member can no longer use this app.");
+            }
+            const used = yield* store.useToken(hash, kind);
+            if (used.status === "reused") {
+                const replay = kind === "refresh" ? yield* store.refreshReplay(hash, graceMs) : undefined;
+                if (replay !== undefined) {
+                    return yield* replayTokens(store, used.grant, presented, replay, graceMs);
+                }
+                if (kind === "code" || used.successorUsed === true) {
+                    yield* store.revokeGrant(used.grant.id);
+                    yield* Effect.logWarning("ontology.oauth.token_reused").pipe(Effect.annotateLogs({ grantId: used.grant.id, kind }));
+                }
+            }
+            if (used.status !== "valid") {
+                return oauthError("invalid_grant", "The grant is invalid, expired or revoked.");
+            }
+            const { grant, token: stored } = used;
+            if (kind === "code") {
+                if (params.redirect_uri !== undefined && params.redirect_uri !== stored.redirectUri) {
+                    return oauthError("invalid_grant", "redirect_uri does not match the authorization.");
+                }
+                if (params.code_verifier === undefined ||
+                    stored.codeChallenge === undefined ||
+                    !verifierMatches(params.code_verifier, stored.codeChallenge)) {
+                    return oauthError("invalid_grant", "code_verifier does not match the code challenge.");
+                }
+            }
+            return yield* issueTokens(store, grant, kind === "refresh" ? presented : undefined);
+        }));
+    });
+}
+/** `POST /api/ontology/oauth/revoke` (RFC 7009): revokes the grant of a token of the client's. */
+function revoke(store) {
+    return (request) => Effect.gen(function* () {
+        const params = yield* bodyParams(request);
+        const client = yield* authenticateClient(store, request, params);
+        if (client === undefined) {
+            return oauthError("invalid_client", "The client is unknown or its secret is wrong.", 401);
+        }
+        if (params.token !== undefined) {
+            const grant = yield* store.findGrantOfToken(secretHash(params.token));
+            if (grant !== undefined && grant.clientId === client.id) {
+                yield* store.revokeGrant(grant.id);
+            }
+        }
+        // Answered alike whether the token was known, so that revocation reveals nothing.
+        return json({}, 200, NO_STORE);
+    });
+}
+/** RFC 8628: the device secret never appears on a browser URL or in storage. */
+function deviceAuthorization(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        if (limiter.take(clientAddress(request)) !== undefined) {
+            return oauthError("too_many_requests", "Try again in a minute.", 429);
+        }
+        const params = yield* bodyParams(request);
+        const client = yield* authenticateClient(store, request, params);
+        if (client === undefined) {
+            return oauthError("invalid_client", "The client is unknown or its secret is wrong.", 401);
+        }
+        const origin = publicOrigin(request);
+        const resource = mcpResource(origin);
+        if (params.resource !== undefined && !sameResource(params.resource, resource)) {
+            return oauthError("invalid_target", "Use this app's MCP resource.");
+        }
+        const code = newSecret("ssd_");
+        let userCode;
+        let saved;
+        do {
+            userCode = humanCode();
+            saved = yield* store.saveDevice({
+                hash: secretHash(code),
+                userCodeHash: secretHash(normalizedUserCode(userCode)),
+                clientId: client.id,
+                scope: grantedScope(params.scope),
+                resource,
+                expiresAt: new Date(Date.now() + DEVICE_TTL_MS),
+                interval: DEVICE_INTERVAL,
+                status: "pending",
+                userId: null,
+            });
+        } while (!saved);
+        const verification = `${origin}${CONSENT_PATH}?device=1`;
+        return json({
+            device_code: code,
+            user_code: userCode,
+            verification_uri: verification,
+            verification_uri_complete: `${verification}&user_code=${encodeURIComponent(userCode)}`,
+            expires_in: DEVICE_TTL_MS / 1000,
+            interval: DEVICE_INTERVAL,
+        }, 200, NO_STORE);
+    });
+}
+function verifyDevice(store, request, decision, limiter) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const member = yield* requireMember();
+        if (member === undefined) {
+            return notMember(requestId);
+        }
+        if (limiter.take(clientAddress(request)) !== undefined ||
+            !(yield* store.deviceAttempt(member.id))) {
+            return oauthError("too_many_requests", "Too many verification attempts. Try again in ten minutes.", 429);
+        }
+        const body = yield* bodyParams(request);
+        const code = normalizedUserCode(body.user_code ?? "");
+        const hash = secretHash(code);
+        const pending = /^[A-HJ-NP-Z2-9]{8}$/.test(code) ? yield* store.findDevice(hash) : undefined;
+        const unavailable = unavailableDevice(pending);
+        if (pending === undefined || unavailable !== undefined) {
+            return requestNotFound(requestId, unavailable);
+        }
+        if (decision !== "lookup") {
+            const decided = yield* store.decideDevice(hash, member.id, body.scope, decision);
+            return decided
+                ? json({ status: decision === "approve" ? "approved" : "denied" }, 200, NO_STORE)
+                : requestNotFound(requestId);
+        }
+        const client = yield* store.findClient(pending.clientId);
+        return json({
+            id: `device:${code}`,
+            client: {
+                name: client?.name ?? "MCP client",
+                uri: client?.clientUri ?? null,
+                redirect_uri: "",
+                redirect_host: client?.clientUri ? new URL(client.clientUri).host : "unverified client",
+            },
+            scope: pending.scope,
+            permissions: member.permissions,
+            expires_at: pending.expiresAt.toISOString(),
+        }, 200, NO_STORE);
+    });
+}
+const PREFLIGHT = HttpServerResponse.empty({ status: 204, headers: CORS });
+/**
+ * The MCP server's OAuth 2.1 authorization server, on the app's own origin: the protected resource
+ * and authorization server metadata, dynamic client registration, the authorization endpoint that
+ * hands the member to the app's consent page, the endpoints the consent page decides with, and the
+ * token and revocation endpoints. Without the OAuth tables, it serves nothing.
+ */
+export function oauthLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.oauth;
+        if (store === undefined) {
+            return;
+        }
+        const limiter = fixedWindowLimiter(REGISTRATION_LIMIT);
+        const deviceLimiter = fixedWindowLimiter(REGISTRATION_LIMIT);
+        const verificationLimiter = fixedWindowLimiter({
+            limit: 20,
+            windowMs: 600_000,
+            maxKeys: 10_000,
+        });
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const asMember = (answer) => (request) => Effect.gen(function* () {
+            const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+            return yield* withPrincipal(bearer, options.verifyToken, backend, answer(request), {
+                oauthResource: appSessionResource(publicOrigin(request)),
+            });
+        });
+        const metadata = (document) => (request) => Effect.succeed(json(document(publicOrigin(request))));
+        for (const path of [PROTECTED_RESOURCE_PATH, `${PROTECTED_RESOURCE_PATH}/mcp`]) {
+            yield* router.add("GET", path, metadata(protectedResourceMetadata));
+            yield* router.add("OPTIONS", path, PREFLIGHT);
+        }
+        yield* router.add("GET", AUTHORIZATION_SERVER_PATH, metadata(authorizationServerMetadata));
+        yield* router.add("OPTIONS", AUTHORIZATION_SERVER_PATH, PREFLIGHT);
+        yield* router.add("POST", REGISTER_PATH, register(store, limiter));
+        yield* router.add("OPTIONS", REGISTER_PATH, PREFLIGHT);
+        yield* router.add("GET", AUTHORIZE_PATH, authorize(store));
+        yield* router.add("POST", DEVICE_PATH, deviceAuthorization(store, deviceLimiter));
+        yield* router.add("OPTIONS", DEVICE_PATH, PREFLIGHT);
+        for (const decision of ["lookup", "approve", "deny"]) {
+            yield* router.add("POST", `${DEVICE_REQUEST_PATH}/${decision}`, asMember((request) => verifyDevice(store, request, decision, verificationLimiter)));
+        }
+        yield* router.add("POST", TOKEN_PATH, token(store, options.refreshReuseGraceMs ?? 45_000));
+        yield* router.add("OPTIONS", TOKEN_PATH, PREFLIGHT);
+        yield* router.add("POST", REVOKE_PATH, revoke(store));
+        yield* router.add("OPTIONS", REVOKE_PATH, PREFLIGHT);
+        yield* router.add("GET", `${REQUESTS_PATH}/:id`, asMember(() => describeRequest(store)));
+        yield* router.add("POST", `${REQUESTS_PATH}/:id/approve`, asMember((request) => decideRequest(store, "approve", request)));
+        yield* router.add("POST", `${REQUESTS_PATH}/:id/deny`, asMember((request) => decideRequest(store, "deny", request)));
+    }));
+}