@plitzi/sdk-server 0.33.2 → 0.34.1

package/dist/core/http/stages/oauth.js

@@ -0,0 +1,118 @@
+import { readRawBody } from "../../requestParser.js";
+import { authorizationServerMetadata, protectedResourceMetadata } from "../../oauth/metadata.js";
+import { getAccess } from "../../oauth/records.js";
+import { sendErrorJson, sendJson } from "../../oauth/respond.js";
+import { handleAuthorizeStart, handleAuthorizeSubmit } from "../../oauth/authorize.js";
+import { bearerOf, sendChallenge } from "../../oauth/challenge.js";
+import { handleRegister } from "../../oauth/register.js";
+import { handleRevoke, handleToken } from "../../oauth/token.js";
+//#region src/core/http/stages/oauth.ts
+var matchesWellKnown = (path, wellKnown) => path === wellKnown || path.startsWith(`${wellKnown}/`);
+var isOAuthPath = (path) => matchesWellKnown(path, "/.well-known/oauth-protected-resource") || matchesWellKnown(path, "/.well-known/oauth-authorization-server") || path === "/register" || path === "/authorize" || path === "/revoke" || path === "/token";
+var formParams = (req, body) => {
+	const params = { ...req.query };
+	for (const [key, value] of new URLSearchParams(body).entries()) params[key] = value;
+	return params;
+};
+var parseJson = (body) => {
+	try {
+		return JSON.parse(body);
+	} catch {
+		return;
+	}
+};
+/** OAuth 2.1 authorization for the MCP server, mounted ONLY when a deployment configures `oauth`. Without it the
+*  stage falls straight through and the server keeps its anonymous contract: discovery 404s, the public surface
+*  (handshake, listings, the guide, plitzi_render) answers without a token, and nothing below changes.
+*
+*  It sits before the MCP stage because that one answers every path on a dedicated MCP server — these endpoints
+*  would otherwise be swallowed by the JSON-RPC transport, which is exactly the 406 a host hits on /register. */
+var createOAuthStage = (oauth) => async (ctx) => {
+	const { path, method } = ctx.req;
+	if (!oauth || !isOAuthPath(path)) return false;
+	const { res } = ctx;
+	if (path !== "/authorize") {
+		res.setHeader("Access-Control-Allow-Origin", "*");
+		res.setHeader("Access-Control-Allow-Headers", "*");
+		res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+	}
+	if (method === "OPTIONS") {
+		res.setStatus(204);
+		res.end();
+		return true;
+	}
+	if (method === "GET" && matchesWellKnown(path, "/.well-known/oauth-protected-resource")) {
+		sendJson(res, 200, protectedResourceMetadata(oauth, ctx.req));
+		return true;
+	}
+	if (method === "GET" && matchesWellKnown(path, "/.well-known/oauth-authorization-server")) {
+		sendJson(res, 200, authorizationServerMetadata(oauth, ctx.req));
+		return true;
+	}
+	if (path === "/authorize" && method === "GET") {
+		await handleAuthorizeStart(oauth, res, ctx.req.query, ctx.req);
+		return true;
+	}
+	if (path === "/authorize" && method === "POST") {
+		await handleAuthorizeSubmit(oauth, res, formParams(ctx.req, await readRawBody(ctx.raw)), ctx.req);
+		return true;
+	}
+	if (path === "/revoke" && method === "POST") {
+		await handleRevoke(oauth, res, formParams(ctx.req, await readRawBody(ctx.raw)));
+		return true;
+	}
+	if (path === "/token" && method === "POST") {
+		await handleToken(oauth, res, formParams(ctx.req, await readRawBody(ctx.raw)));
+		return true;
+	}
+	if (path === "/register" && method === "POST") {
+		await handleRegister(oauth, res, parseJson(await readRawBody(ctx.raw)));
+		return true;
+	}
+	sendErrorJson(res, 405, "invalid_request", `${method} is not allowed on ${path}.`);
+	return true;
+};
+var CHALLENGE_DESCRIPTIONS = {
+	"no-credential": "Authorization is required to use this server.",
+	"unknown-credential": "The access token is invalid, expired or revoked.",
+	"store-unreachable": "The access token could not be verified right now.",
+	"adapter-failed": "The access token could not be verified right now."
+};
+var challengeReason = async (oauth, ctx, token) => {
+	if (!token) return "no-credential";
+	try {
+		const record = await getAccess(oauth.adapters.store, token);
+		if (record) {
+			const credential = record.credential ?? token;
+			ctx.req.headers["x-access-token"] = credential;
+			ctx.req.headers.authorization = `Bearer ${credential}`;
+			return;
+		}
+	} catch {
+		return "store-unreachable";
+	}
+	try {
+		return await ctx.config.adapters.getGrant?.(ctx.req) === void 0 ? "unknown-credential" : void 0;
+	} catch {
+		return "adapter-failed";
+	}
+};
+/** The protected-resource half of OAuth: an MCP call that presents no bearer this server can verify is refused
+*  with RFC 6750's challenge instead of being served the anonymous surface. That 401 is the whole handshake — it
+*  is how a host learns the server needs authorization, where its metadata lives and which scopes to ask for, and
+*  a 200 tells it none of that. Only the JSON-RPC POST is guarded: the CORS preflight, the GET 405 and the
+*  discovery probes carry no credential and must keep answering as they do.
+*
+*  Mounted only when `oauth` is configured. A deployment that configures none keeps the open server it had, where
+*  the whole public surface — handshake, listings, the guide, plitzi_render — answers without a token; with OAuth
+*  on, the grant that carries no space is what covers that same ground. */
+var createOAuthGuardStage = (oauth) => async (ctx) => {
+	if (!oauth || ctx.req.method !== "POST") return false;
+	const reason = await challengeReason(oauth, ctx, bearerOf(ctx.req));
+	if (!reason) return false;
+	ctx.operation = `oauth-challenge:${reason}`;
+	sendChallenge(oauth, ctx.req, ctx.res, CHALLENGE_DESCRIPTIONS[reason]);
+	return true;
+};
+//#endregion
+export { createOAuthGuardStage, createOAuthStage };

package/dist/core/http/types.d.ts

@@ -1,5 +1,6 @@
 import { RawResponse } from '../../helpers/buildResponseHelpers';
 import { ServerCaches } from '../../helpers/cache';
+import { ActionsModule } from '../../modules/actions';
 import { PluginManager } from '../../plugins/manager';
 import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
 import { IncomingMessage } from 'node:http';
@@ -13,9 +14,20 @@ export interface BaseContext {
     /** Set by the stage that answers when the path alone does not identify the work (the MCP endpoint serves every
      *  JSON-RPC method on the same URL). The dispatcher folds it into the access log. */
     operation?: string;
+    /**
+     * Aborted when the client goes away.
+     *
+     * The pipeline had no request lifecycle at all before this: a stage that kept working after the socket closed
+     * had no way to find out, which is affordable for a page render and is not for anything long-lived. Stages that
+     * spend real work on behalf of a caller should hand this to whatever they call.
+     */
+    signal: AbortSignal;
 }
 export interface SSRContext extends BaseContext {
     config: SSRPageServerConfig;
+    /** Built at boot when the deployment configured `action.lookups`, so its task registry is validated once and
+     *  its guards are a single set for the process. Absent means this server runs no actions. */
+    actions?: ActionsModule;
     renderFn: SSRTemplateFn;
     caches: ServerCaches;
     pluginManager: PluginManager;

package/dist/core/oauth/authorize.d.ts

@@ -0,0 +1,22 @@
+import { OAuthParams } from './params';
+import { OAuthConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * GET /authorize — the entry point a host opens in the user's browser.
+ *
+ * This server does not ask for a password. It reads whoever the browser already is and, from there:
+ *
+ * - **signed in** — straight to the grant screen, which is the only page this module still renders. Choosing what
+ *   to connect is authorization, and authorization is this server's job; who somebody is is not.
+ * - **not signed in, guest allowed** — the grant screen with nothing to grant and the guest button on it. It is
+ *   deliberately NOT a redirect: a guest has no session and never will, so bouncing them to sign in would take
+ *   the option away from the only people it exists for.
+ * - **not signed in, no guest** — off to `signInUrl`, carrying this whole request as where to come back to.
+ */
+export declare const handleAuthorizeStart: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams, req: SSRRequest) => Promise<void>;
+/**
+ * POST /authorize — the grant screen coming back, either with a chosen target or with the guest button.
+ *
+ * There is no credentials branch any more: nothing here reads a username or a password, and the only way to reach
+ * this with an identity is to carry a `pending` id that was minted after {@link OAuthAdapters.identify} succeeded.
+ */
+export declare const handleAuthorizeSubmit: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams, req: SSRRequest) => Promise<void>;

package/dist/core/oauth/authorize.js

@@ -0,0 +1,254 @@
+import { renderConsentPage } from "./consentPage.js";
+import { AUTHORIZE_PATH } from "./metadata.js";
+import { field, optionalField } from "./params.js";
+import { randomId } from "./pkce.js";
+import { dropPending, getClient, getPending, putCode, putPending } from "./records.js";
+import { redirectToSignIn, redirectWithCode, redirectWithError, sendErrorPage, sendHtml } from "./respond.js";
+//#region src/core/oauth/authorize.ts
+var DEFAULT_CODE_TTL_SECONDS = 60;
+var DEFAULT_GUEST_LABEL = "Continue without an account";
+var DEFAULT_GUEST_USER = {
+	id: "guest",
+	label: "Guest"
+};
+var guestView = (guest) => ({
+	label: guest.label ?? DEFAULT_GUEST_LABEL,
+	description: guest.target.description
+});
+var hiddenFieldsFor = (request, pendingId) => {
+	const hidden = {
+		client_id: request.clientId,
+		redirect_uri: request.redirectUri,
+		code_challenge: request.challenge,
+		code_challenge_method: "S256"
+	};
+	if (request.state !== void 0) hidden["state"] = request.state;
+	if (request.scope !== void 0) hidden["scope"] = request.scope;
+	if (pendingId !== void 0) hidden["pending"] = pendingId;
+	return hidden;
+};
+var renderConsent = (res, view) => {
+	sendHtml(res, 200, renderConsentPage(view));
+};
+/**
+* This request, as the address to come back to after signing in.
+*
+* Rebuilt from the params rather than read off `req.url` because the two can differ — a proxy may rewrite the
+* path — and what has to survive the round trip is the QUERY, which is the authorization request itself.
+*/
+var authorizeUrl = (config, req, params) => {
+	const base = config.issuer ?? `https://${req.headers.host ?? ""}`;
+	const url = new URL(AUTHORIZE_PATH, base);
+	for (const [key, value] of Object.entries(params)) if (typeof value === "string") url.searchParams.set(key, value);
+	return url.toString();
+};
+/**
+* The sign-in screen's own address, carrying `guest=1` when this server would take somebody without an account.
+*
+* The hint is the only thing that tells that screen so. It is shared by every client now, most of which require an
+* account, so it cannot offer a way past itself by default — and without the hint, leaving this screen for it is a
+* ONE-WAY door: whoever went to see what signing in involves has no way back to the guest button except the
+* browser's own history, on a page they arrived at from another application entirely.
+*
+* Every hand-off to that screen goes through here, which is the point: the door is one-way from the grant screen's
+* "sign in" link and from "use another account" alike, and the second one is where it was missed.
+*/
+var signInBase = (config) => {
+	if (!config.guest) return config.signInUrl;
+	const url = new URL(config.signInUrl);
+	url.searchParams.set("guest", "1");
+	return url.toString();
+};
+/** The sign-in address with this request as the destination — what the grant screen's "sign in" link points at. */
+var signInWithReturn = (config, req, params) => {
+	const url = new URL(signInBase(config));
+	url.searchParams.set("redirect", authorizeUrl(config, req, params));
+	return url.toString();
+};
+/**
+* The same address again, rebuilt from the request rather than from the query it arrived as.
+*
+* The grant screen is reached by a GET with the parameters in the URL and by a POST with them in hidden fields, and
+* the "use another account" link has to work on both — so it is built from the parts the request is MADE of, which
+* both paths already carry, instead of from whichever shape they came in.
+*/
+var authorizeUrlFor = (config, req, request) => {
+	const base = config.issuer ?? `https://${req.headers.host ?? ""}`;
+	const url = new URL(AUTHORIZE_PATH, base);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", request.clientId);
+	url.searchParams.set("redirect_uri", request.redirectUri);
+	url.searchParams.set("code_challenge", request.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (request.state !== void 0) url.searchParams.set("state", request.state);
+	if (request.scope !== void 0) url.searchParams.set("scope", request.scope);
+	return url.toString();
+};
+/** Validates the parts of an authorization request that decide WHERE a failure may be reported. Until the client
+*  and its redirect target check out, nothing may be sent back to the client. */
+var resolveRequest = async (config, res, params) => {
+	const clientId = field(params, "client_id");
+	const redirectUri = field(params, "redirect_uri");
+	const client = clientId ? await getClient(config.adapters.store, clientId) : void 0;
+	if (!client) {
+		sendErrorPage(res, "Unknown client", "This application is not registered with the server, or its registration expired.");
+		return;
+	}
+	if (!redirectUri || !client.redirectUris.includes(redirectUri)) {
+		sendErrorPage(res, "Invalid redirect", "The application asked to be sent back to an address it did not register.");
+		return;
+	}
+	const state = optionalField(params, "state");
+	const responseType = field(params, "response_type");
+	if (responseType && responseType !== "code") {
+		redirectWithError(res, redirectUri, "unsupported_response_type", "Only the authorization code flow is supported.", state);
+		return;
+	}
+	const challenge = field(params, "code_challenge");
+	const method = field(params, "code_challenge_method");
+	if (!challenge || method !== "S256") {
+		redirectWithError(res, redirectUri, "invalid_request", "PKCE with code_challenge_method=S256 is required.", state);
+		return;
+	}
+	return {
+		clientId,
+		redirectUri,
+		challenge,
+		state,
+		scope: optionalField(params, "scope")
+	};
+};
+/** Consent granted: mint the bearer now, park it behind a one-shot code and send the browser back. Minting here
+*  rather than at redemption keeps a failure the user can act on — no space, revoked access — on this screen. */
+var completeGrant = async (config, res, request, user, target) => {
+	const issued = await config.adapters.issueToken(user, target);
+	if (!issued) {
+		redirectWithError(res, request.redirectUri, "access_denied", "The account may not grant access to this resource.", request.state);
+		return;
+	}
+	const code = randomId();
+	await putCode(config.adapters.store, code, {
+		clientId: request.clientId,
+		redirectUri: request.redirectUri,
+		challenge: request.challenge,
+		token: issued.token,
+		expiresInSeconds: issued.expiresInSeconds,
+		scope: request.scope,
+		user,
+		target
+	}, config.codeTtlSeconds ?? DEFAULT_CODE_TTL_SECONDS);
+	redirectWithCode(res, request.redirectUri, code, request.state);
+};
+/**
+* Show a signed-in account what it may grant, and end the flow if there is nothing.
+*
+* `pendingId` is minted here because the screen it renders is the one that POSTs back, and the record is what
+* proves — on that POST — that identity was established before anything was granted.
+*/
+var askForTarget = async (config, res, request, user, error) => {
+	const targets = await config.adapters.grantTargets(user);
+	if (targets.length === 0) {
+		redirectWithError(res, request.redirectUri, "access_denied", "This account has nothing to grant access to.", request.state);
+		return;
+	}
+	const pendingId = randomId();
+	await putPending(config.adapters.store, pendingId, {
+		clientId: request.clientId,
+		redirectUri: request.redirectUri,
+		challenge: request.challenge,
+		state: request.state,
+		scope: request.scope,
+		user
+	});
+	renderConsent(res, {
+		action: AUTHORIZE_PATH,
+		hidden: hiddenFieldsFor(request, pendingId),
+		targets,
+		user,
+		canSwitchUser: config.adapters.signOut !== void 0,
+		error,
+		branding: config.branding ?? {}
+	});
+};
+/**
+* GET /authorize — the entry point a host opens in the user's browser.
+*
+* This server does not ask for a password. It reads whoever the browser already is and, from there:
+*
+* - **signed in** — straight to the grant screen, which is the only page this module still renders. Choosing what
+*   to connect is authorization, and authorization is this server's job; who somebody is is not.
+* - **not signed in, guest allowed** — the grant screen with nothing to grant and the guest button on it. It is
+*   deliberately NOT a redirect: a guest has no session and never will, so bouncing them to sign in would take
+*   the option away from the only people it exists for.
+* - **not signed in, no guest** — off to `signInUrl`, carrying this whole request as where to come back to.
+*/
+var handleAuthorizeStart = async (config, res, params, req) => {
+	const request = await resolveRequest(config, res, params);
+	if (!request) return;
+	const user = await config.adapters.identify(req);
+	if (user) {
+		await askForTarget(config, res, request, user);
+		return;
+	}
+	if (config.guest) {
+		renderConsent(res, {
+			action: AUTHORIZE_PATH,
+			hidden: hiddenFieldsFor(request),
+			targets: [],
+			guest: guestView(config.guest),
+			signInUrl: signInWithReturn(config, req, params),
+			branding: config.branding ?? {}
+		});
+		return;
+	}
+	redirectToSignIn(res, signInBase(config), authorizeUrl(config, req, params));
+};
+/**
+* POST /authorize — the grant screen coming back, either with a chosen target or with the guest button.
+*
+* There is no credentials branch any more: nothing here reads a username or a password, and the only way to reach
+* this with an identity is to carry a `pending` id that was minted after {@link OAuthAdapters.identify} succeeded.
+*/
+var handleAuthorizeSubmit = async (config, res, params, req) => {
+	const request = await resolveRequest(config, res, params);
+	if (!request) return;
+	/**
+	* "Use another account": end the session and start this same request over.
+	*
+	* Before the pending record is read, because there is nothing to grant — the point is that whoever is signed in
+	* is not who should be. The request goes back out through `signInUrl` exactly as an unidentified visitor's would,
+	* so the sign-in screen brings them here again with the new session in place.
+	*/
+	if (config.adapters.signOut && optionalField(params, "switch")) {
+		const pendingId = optionalField(params, "pending");
+		if (pendingId) await dropPending(config.adapters.store, pendingId);
+		await config.adapters.signOut(req, res);
+		redirectToSignIn(res, signInBase(config), authorizeUrlFor(config, req, request));
+		return;
+	}
+	const { guest } = config;
+	if (guest && optionalField(params, "guest")) {
+		await completeGrant(config, res, request, guest.user ?? DEFAULT_GUEST_USER, guest.target);
+		return;
+	}
+	const pendingId = optionalField(params, "pending");
+	if (!pendingId) {
+		redirectWithError(res, request.redirectUri, "invalid_request", "The grant was submitted without a session.", request.state);
+		return;
+	}
+	const pending = await getPending(config.adapters.store, pendingId);
+	if (!pending || pending.clientId !== request.clientId) {
+		redirectWithError(res, request.redirectUri, "access_denied", "The sign-in expired. Try connecting again.", request.state);
+		return;
+	}
+	const chosen = (await config.adapters.grantTargets(pending.user)).find((target) => target.value === field(params, "target"));
+	if (!chosen) {
+		await dropPending(config.adapters.store, pendingId);
+		await askForTarget(config, res, request, pending.user, "Choose what to grant access to.");
+		return;
+	}
+	await dropPending(config.adapters.store, pendingId);
+	await completeGrant(config, res, request, pending.user, chosen);
+};
+//#endregion
+export { handleAuthorizeStart, handleAuthorizeSubmit };

package/dist/core/oauth/authorize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/oauth/challenge.d.ts

@@ -0,0 +1,11 @@
+import { OAuthConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** The credential on an MCP request. `Authorization: Bearer` is what RFC 6750 defines and what a remote host
+ *  sends; `x-access-token` is the platform's own header, which the builder and the CLI already use — a request
+ *  carrying either presents a credential, and the same verification decides whether it is a good one. */
+export declare const bearerOf: (req: SSRRequest) => string;
+/** RFC 6750 §3 — the answer to an MCP request that presents no usable credential, and the only thing that starts
+ *  an authorization flow: a host runs OAuth off a 401 whose `WWW-Authenticate` names the resource metadata, and
+ *  IGNORES the header on a 200. Answering such a request with the anonymous surface instead is what leaves a
+ *  connector unable to attach the grant it just completed — the flow succeeds and the host still reports that
+ *  authorization failed. `scope` states what to ask for, so consent is not widened to everything advertised. */
+export declare const sendChallenge: (config: OAuthConfig, req: SSRRequest, res: SSRResponseHelpers, description: string) => void;

package/dist/core/oauth/challenge.js

@@ -0,0 +1,33 @@
+import { resourceMetadataUrl, scopesOf } from "./metadata.js";
+import { sendJson } from "./respond.js";
+//#region src/core/oauth/challenge.ts
+/** The credential on an MCP request. `Authorization: Bearer` is what RFC 6750 defines and what a remote host
+*  sends; `x-access-token` is the platform's own header, which the builder and the CLI already use — a request
+*  carrying either presents a credential, and the same verification decides whether it is a good one. */
+var bearerOf = (req) => {
+	const header = req.headers["x-access-token"] ?? req.headers.authorization ?? "";
+	return (Array.isArray(header) ? header[0] ?? "" : header).replace(/^Bearer\s+/i, "").trim();
+};
+var parameter = (name, value) => `${name}="${value.replace(/"/gu, "")}"`;
+/** RFC 6750 §3 — the answer to an MCP request that presents no usable credential, and the only thing that starts
+*  an authorization flow: a host runs OAuth off a 401 whose `WWW-Authenticate` names the resource metadata, and
+*  IGNORES the header on a 200. Answering such a request with the anonymous surface instead is what leaves a
+*  connector unable to attach the grant it just completed — the flow succeeds and the host still reports that
+*  authorization failed. `scope` states what to ask for, so consent is not widened to everything advertised. */
+var sendChallenge = (config, req, res, description) => {
+	const params = [
+		parameter("error", "invalid_token"),
+		parameter("error_description", description),
+		parameter("resource_metadata", resourceMetadataUrl(config, req)),
+		parameter("scope", scopesOf(config).join(" "))
+	];
+	res.setHeader("WWW-Authenticate", `Bearer ${params.join(", ")}`);
+	res.setHeader("Access-Control-Allow-Origin", "*");
+	res.setHeader("Access-Control-Expose-Headers", "WWW-Authenticate");
+	sendJson(res, 401, {
+		error: "invalid_token",
+		error_description: description
+	});
+};
+//#endregion
+export { bearerOf, sendChallenge };

package/dist/core/oauth/consentPage.d.ts

@@ -0,0 +1,12 @@
+import { OAuthConsentView } from '@plitzi/sdk-shared';
+/**
+ * The grant screen — the ONE page this server renders, and it never asks who anybody is.
+ *
+ * It used to be two steps, the first of which took a username and a password. That is gone: signing in happens on
+ * the deployment's own sign-in screen (`OAuthConfig.signInUrl`), and this page is reached either already signed in
+ * — pick what to connect — or as a visitor who may only take the guest connection.
+ */
+export declare const renderConsentPage: (view: OAuthConsentView) => string;
+/** The dead end for a request that cannot be redirected back — a bad `redirect_uri` or an unknown client. Bouncing
+ *  those to the client would make this server an open redirector, so the user is told here instead. */
+export declare const renderErrorPage: (title: string, detail: string) => string;

package/dist/core/oauth/consentPage.js

@@ -0,0 +1,131 @@
+//#region src/core/oauth/consentPage.ts
+var escapeHtml = (value) => value.replace(/[&<>"']/gu, (character) => {
+	switch (character) {
+		case "&": return "&amp;";
+		case "<": return "&lt;";
+		case ">": return "&gt;";
+		case "\"": return "&quot;";
+		default: return "&#39;";
+	}
+});
+var STYLES = `
+  :root { color-scheme: light dark; --bg: #f6f7f9; --panel: #ffffff; --ink: #16181d; --muted: #6b7280;
+    --line: #e2e5ea; --accent: #2563eb; --danger: #b91c1c; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #0f1115; --panel: #171a21; --ink: #e8eaee; --muted: #9aa1ad; --line: #262b35;
+      --accent: #60a5fa; --danger: #f87171; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 24px;
+    background: var(--bg); color: var(--ink);
+    font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  main { width: 100%; max-width: 420px; background: var(--panel); border: 1px solid var(--line);
+    border-radius: 14px; padding: 32px; }
+  img.logo { display: block; height: 32px; margin-bottom: 20px; }
+  h1 { margin: 0 0 6px; font-size: 20px; font-weight: 600; }
+  p.lede { margin: 0 0 24px; color: var(--muted); font-size: 14px; }
+  input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+  ul.targets { list-style: none; margin: 0 0 20px; padding: 0; display: grid; gap: 8px; }
+  ul.targets label { display: flex; gap: 10px; align-items: flex-start; margin: 0; padding: 12px;
+    border: 1px solid var(--line); border-radius: 8px; font-weight: 400; cursor: pointer; }
+  ul.targets strong { display: block; font-weight: 500; }
+  ul.targets span { color: var(--muted); font-size: 13px; }
+  button { width: 100%; padding: 11px 16px; border: 0; border-radius: 8px; background: var(--accent);
+    color: #fff; font: inherit; font-weight: 500; cursor: pointer; }
+  button.guest { margin-top: 10px; background: transparent; color: var(--accent);
+    border: 1px solid var(--line); }
+  p.error { margin: 0 0 16px; padding: 10px 12px; border-radius: 8px; color: var(--danger);
+    border: 1px solid currentColor; font-size: 14px; }
+  p.note { margin: 10px 0 0; color: var(--muted); font-size: 13px; text-align: center; }
+  p.note a { color: var(--accent); }
+`;
+var hiddenFields = (hidden) => Object.entries(hidden).map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`).join("\n      ");
+var guestButton = (guest) => {
+	const note = guest.description ? `\n      <p class="note">${escapeHtml(guest.description)}</p>` : "";
+	return `\n      <button class="guest" type="submit" name="guest" value="1" formnovalidate>${escapeHtml(guest.label)}</button>${note}`;
+};
+/**
+* The way out for somebody signed in as the wrong account.
+*
+* Under the grant button rather than beside the account name, because it is the escape hatch and not the action:
+* almost everybody who reaches this screen is who they meant to be, and the ones who are not have no other route
+* back — they arrived from another application, and the deployment's sign-out page is somewhere they cannot get to
+* from here without abandoning the connection.
+*
+* `formnovalidate` for the same reason the guest button carries it: this submit is not the form's own answer.
+*/
+var switchUserButton = () => "\n      <button class=\"guest\" type=\"submit\" name=\"switch\" value=\"1\" formnovalidate>Use another account</button>";
+var targetFields = (view) => {
+	return `<ul class="targets">
+        ${view.targets.map((target, index) => {
+		const description = target.description ? `<span>${escapeHtml(target.description)}</span>` : "";
+		return `<li><label>
+          <input type="radio" name="target" value="${escapeHtml(target.value)}"${index === 0 ? " checked" : ""}>
+          <span><strong>${escapeHtml(target.label)}</strong>${description}</span>
+        </label></li>`;
+	}).join("\n        ")}
+      </ul>
+      <button type="submit">Allow access</button>${view.canSwitchUser ? switchUserButton() : ""}`;
+};
+/** What a visitor who has not signed in is offered: the guest connection, and a way to go and sign in. */
+var anonymousFields = (view) => {
+	const signIn = view.signInUrl ? `\n      <p class="note"><a href="${escapeHtml(view.signInUrl)}">Sign in to connect a space instead</a></p>` : "";
+	return `${view.guest ? guestButton(view.guest) : ""}${signIn}`;
+};
+/**
+* The grant screen — the ONE page this server renders, and it never asks who anybody is.
+*
+* It used to be two steps, the first of which took a username and a password. That is gone: signing in happens on
+* the deployment's own sign-in screen (`OAuthConfig.signInUrl`), and this page is reached either already signed in
+* — pick what to connect — or as a visitor who may only take the guest connection.
+*/
+var renderConsentPage = (view) => {
+	const productName = view.branding.productName ?? "Plitzi";
+	const logo = view.branding.logoUrl ? `<img class="logo" src="${escapeHtml(view.branding.logoUrl)}" alt="${escapeHtml(productName)}">` : "";
+	const error = view.error ? `<p class="error">${escapeHtml(view.error)}</p>` : "";
+	const lede = view.user ? `Signed in as ${escapeHtml(view.user.label)}. Choose what to grant access to.` : `Connect ${escapeHtml(productName)} without an account, or sign in first.`;
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex">
+  <link rel="icon" href="data:,">
+  <title>${escapeHtml(productName)}</title>
+  <style>${STYLES}${view.branding.css ?? ""}</style>
+</head>
+<body>
+  <main>
+    ${logo}
+    <h1>${escapeHtml(productName)}</h1>
+    <p class="lede">${lede}</p>
+    ${error}
+    <form method="post" action="${escapeHtml(view.action)}">
+      ${hiddenFields(view.hidden)}
+      ${view.user ? targetFields(view) : anonymousFields(view)}
+    </form>
+  </main>
+</body>
+</html>`;
+};
+/** The dead end for a request that cannot be redirected back — a bad `redirect_uri` or an unknown client. Bouncing
+*  those to the client would make this server an open redirector, so the user is told here instead. */
+var renderErrorPage = (title, detail) => `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex">
+  <link rel="icon" href="data:,">
+  <title>${escapeHtml(title)}</title>
+  <style>${STYLES}</style>
+</head>
+<body>
+  <main>
+    <h1>${escapeHtml(title)}</h1>
+    <p class="lede">${escapeHtml(detail)}</p>
+  </main>
+</body>
+</html>`;
+//#endregion
+export { renderConsentPage, renderErrorPage };

package/dist/core/oauth/metadata.d.ts

@@ -0,0 +1,41 @@
+import { OAuthConfig, SSRRequest } from '@plitzi/sdk-shared';
+export declare const AUTHORIZE_PATH = "/authorize";
+export declare const TOKEN_PATH = "/token";
+export declare const REVOKE_PATH = "/revoke";
+export declare const REGISTER_PATH = "/register";
+export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+export declare const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+/** The identifier the two documents agree on. This server is both the protected resource and its own
+ *  authorization server, so one origin names both. Derived from the request unless pinned, which keeps a
+ *  deployment correct across its dev, staging and production hosts without per-environment config. */
+export declare const issuerOf: (config: OAuthConfig, req: SSRRequest) => string;
+export declare const scopesOf: (config: OAuthConfig) => string[];
+/** Where the challenge points a host, for an MCP endpoint served at `req.path`. RFC 9728 §3.1 appends the
+ *  resource's own path to the well-known path, and a host that reads the document back expects its `resource` to
+ *  name the URL it was configured with — so a server mounted at /mcp must be pointed at the suffixed document,
+ *  not the bare one. */
+export declare const resourceMetadataUrl: (config: OAuthConfig, req: SSRRequest) => string;
+/** RFC 9728. The document Claude Desktop asks for FIRST, and the one whose absence ends the flow before anything
+ *  else is tried — a 404 here is what a host reports as `mcp_auth_start_failed`.
+ *
+ *  `resource` echoes the path the document was asked for: Claude requires it to match the server URL the user
+ *  typed, path included, and a dedicated MCP server answers JSON-RPC on every path — so `/.well-known/…/mcp`
+ *  describes `https://host/mcp` while the bare path describes the origin.
+ *
+ *  A server mounted at the ORIGIN is `https://host/`, WITH the trailing slash: a host parses the URL the user
+ *  typed before it does anything with it, and an empty path renders as `/` — Claude's connector was observed
+ *  asking for exactly `resource=https%3A%2F%2Fhost%2F`, so that is the form the document must claim.
+ *
+ *  It does NOT make a bare-origin connector work, and nothing here can. Claude's remote-connector service will
+ *  not open a session against an MCP endpoint whose URL has no path: the whole grant succeeds — discovery,
+ *  registration, consent, a 200 from /token with the scope it asked for — and then it reports
+ *  `McpAuthorizationError` ("the integration rejected the credentials it just issued") without ever presenting
+ *  the bearer. Verified against the same deployment, minutes apart: at /mcp the token is followed by
+ *  `initialize`, at / nothing follows it, in the ingress log as well as this server's. Claiming `https://host/mcp`
+ *  from the bare document would only fail sooner — a client checks that the resource it is handed is no MORE
+ *  specific than the URL it holds. Publish the connector URL WITH its path. */
+export declare const protectedResourceMetadata: (config: OAuthConfig, req: SSRRequest) => Record<string, unknown>;
+/** RFC 8414. Public clients with PKCE only: a desktop host stores no secret, so `none` is the sole endpoint auth
+ *  method and S256 the sole challenge method. `offline_access` is advertised whenever refresh grants are issued,
+ *  which is the signal a host looks for before asking for one. */
+export declare const authorizationServerMetadata: (config: OAuthConfig, req: SSRRequest) => Record<string, unknown>;