@plitzi/sdk-server 0.32.10 → 0.32.12

package/dist/modules/oauth/consentPage.js

@@ -0,0 +1,111 @@
+//#region src/modules/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; }
+  label { display: block; margin-bottom: 6px; font-size: 13px; font-weight: 500; }
+  input[type="text"], input[type="password"] { width: 100%; margin-bottom: 16px; padding: 10px 12px;
+    border: 1px solid var(--line); border-radius: 8px; background: var(--bg); color: var(--ink); font: inherit; }
+  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; }
+  p.error { margin: 0 0 16px; padding: 10px 12px; border-radius: 8px; color: var(--danger);
+    border: 1px solid currentColor; font-size: 14px; }
+`;
+var hiddenFields = (hidden) => Object.entries(hidden).map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`).join("\n      ");
+var credentialsFields = () => `<label for="username">Email or username</label>
+      <input id="username" name="username" type="text" autocomplete="username" autocapitalize="none"
+        spellcheck="false" required autofocus>
+      <label for="password">Password</label>
+      <input id="password" name="password" type="password" autocomplete="current-password" required>
+      <button type="submit">Sign in</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>`;
+};
+/** The built-in consent screen: a credentials step, then a step to pick what the client gets access to. Replace it
+*  wholesale via `oauth.renderConsent` — the field names read back here are the contract, not the markup. */
+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.step === "credentials" ? `Sign in to connect ${escapeHtml(productName)}.` : `Signed in as ${escapeHtml(view.user?.label ?? "")}. Choose what to grant access to.`;
+	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.step === "credentials" ? credentialsFields() : targetFields(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/modules/oauth/metadata.js

@@ -0,0 +1,43 @@
+import { requestOrigin } from "../../core/requestParser.js";
+//#region src/modules/oauth/metadata.ts
+var AUTHORIZE_PATH = "/authorize";
+var TOKEN_PATH = "/token";
+var REGISTER_PATH = "/register";
+var PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+var AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+var DEFAULT_SCOPES = ["plitzi"];
+/** 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. */
+var issuerOf = (config, req) => config.issuer ?? requestOrigin(req);
+var scopesOf = (config) => config.scopes ?? DEFAULT_SCOPES;
+/** 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`. */
+var protectedResourceMetadata = (config, req) => {
+	const issuer = issuerOf(config, req);
+	return {
+		resource: issuer,
+		authorization_servers: [issuer],
+		scopes_supported: scopesOf(config),
+		bearer_methods_supported: ["header"]
+	};
+};
+/** 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. */
+var authorizationServerMetadata = (config, req) => {
+	const issuer = issuerOf(config, req);
+	const grantTypes = config.refreshTtlSeconds === 0 ? ["authorization_code"] : ["authorization_code", "refresh_token"];
+	return {
+		issuer,
+		authorization_endpoint: `${issuer}${AUTHORIZE_PATH}`,
+		token_endpoint: `${issuer}${TOKEN_PATH}`,
+		registration_endpoint: `${issuer}${REGISTER_PATH}`,
+		response_types_supported: ["code"],
+		grant_types_supported: grantTypes,
+		code_challenge_methods_supported: ["S256"],
+		token_endpoint_auth_methods_supported: ["none"],
+		scopes_supported: scopesOf(config)
+	};
+};
+//#endregion
+export { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, issuerOf, protectedResourceMetadata, scopesOf };

package/dist/modules/oauth/params.js

@@ -0,0 +1,5 @@
+//#region src/modules/oauth/params.ts
+var field = (params, name) => params[name] ?? "";
+var optionalField = (params, name) => params[name] || void 0;
+//#endregion
+export { field, optionalField };

package/dist/modules/oauth/pkce.js

@@ -0,0 +1,15 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/modules/oauth/pkce.ts
+/** An unguessable, URL-safe identifier for the values this layer hands out (codes, refresh tokens, client ids).
+*  256 bits from the CSPRNG, so they are also unguessable by anyone who collects a few of them. */
+var randomId = () => randomBytes(32).toString("base64url");
+/** RFC 7636 S256, the only method this server accepts — `plain` puts the verifier on the wire, and a public
+*  client on a desktop host has no other proof it is the one that started the flow. */
+var verifyChallenge = (verifier, challenge) => {
+	if (!verifier || !challenge) return false;
+	const computed = Buffer.from(createHash("sha256").update(verifier).digest("base64url"));
+	const expected = Buffer.from(challenge);
+	return computed.length === expected.length && timingSafeEqual(computed, expected);
+};
+//#endregion
+export { randomId, verifyChallenge };

package/dist/modules/oauth/records.js

@@ -0,0 +1,35 @@
+//#region src/modules/oauth/records.ts
+var CLIENT_TTL_SECONDS = 3600 * 24 * 90;
+var PENDING_TTL_SECONDS = 600;
+var keyOf = (kind, id) => `oauth:${kind}:${id}`;
+var readJson = async (store, kind, id) => {
+	const raw = await store.get(keyOf(kind, id));
+	if (!raw) return;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+};
+var writeJson = async (store, kind, id, value, ttlSeconds) => {
+	await store.put(keyOf(kind, id), JSON.stringify(value), ttlSeconds);
+};
+var putClient = (store, client) => writeJson(store, "client", client.clientId, client, CLIENT_TTL_SECONDS);
+var getClient = (store, clientId) => readJson(store, "client", clientId);
+var putPending = (store, id, pending) => writeJson(store, "pending", id, pending, PENDING_TTL_SECONDS);
+var getPending = (store, id) => readJson(store, "pending", id);
+var dropPending = async (store, id) => {
+	await store.drop(keyOf("pending", id));
+};
+var putCode = (store, code, record, ttlSeconds) => writeJson(store, "code", code, record, ttlSeconds);
+var getCode = (store, code) => readJson(store, "code", code);
+var dropCode = async (store, code) => {
+	await store.drop(keyOf("code", code));
+};
+var putRefresh = (store, token, record, ttlSeconds) => writeJson(store, "refresh", token, record, ttlSeconds);
+var getRefresh = (store, token) => readJson(store, "refresh", token);
+var dropRefresh = async (store, token) => {
+	await store.drop(keyOf("refresh", token));
+};
+//#endregion
+export { dropCode, dropPending, dropRefresh, getClient, getCode, getPending, getRefresh, putClient, putCode, putPending, putRefresh };

package/dist/modules/oauth/register.js

@@ -0,0 +1,48 @@
+import { randomId } from "./pkce.js";
+import { putClient } from "./records.js";
+import { sendErrorJson, sendJson } from "./respond.js";
+//#region src/modules/oauth/register.ts
+var isUsableRedirectUri = (value) => {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (url.protocol === "https:") return true;
+	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+};
+var stringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+/** RFC 7591 dynamic client registration. A remote host has no way to be configured into this server ahead of
+*  time, so it registers itself on first connect; the record it gets back is only ever used to pin the redirect
+*  target, since a public client authenticates with PKCE rather than with credentials. */
+var handleRegister = async (config, res, body) => {
+	if (typeof body !== "object" || body === null) {
+		sendErrorJson(res, 400, "invalid_request", "Expected a JSON client metadata object.");
+		return;
+	}
+	const metadata = body;
+	const redirectUris = stringList(metadata["redirect_uris"]).filter(isUsableRedirectUri);
+	if (redirectUris.length === 0) {
+		sendErrorJson(res, 400, "invalid_request", "redirect_uris must list at least one https (or loopback) URI.");
+		return;
+	}
+	const clientName = typeof metadata["client_name"] === "string" ? metadata["client_name"] : "MCP client";
+	const clientId = randomId();
+	await putClient(config.adapters.store, {
+		clientId,
+		clientName,
+		redirectUris
+	});
+	sendJson(res, 201, {
+		client_id: clientId,
+		client_id_issued_at: Math.floor(Date.now() / 1e3),
+		client_name: clientName,
+		redirect_uris: redirectUris,
+		grant_types: config.refreshTtlSeconds === 0 ? ["authorization_code"] : ["authorization_code", "refresh_token"],
+		response_types: ["code"],
+		token_endpoint_auth_method: "none"
+	});
+};
+//#endregion
+export { handleRegister };

package/dist/modules/oauth/respond.js

@@ -0,0 +1,44 @@
+import { renderErrorPage } from "./consentPage.js";
+//#region src/modules/oauth/respond.ts
+var sendJson = (res, status, body) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(JSON.stringify(body));
+};
+var sendHtml = (res, status, html) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "text/html; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(html);
+};
+var sendErrorJson = (res, status, error, description) => sendJson(res, status, {
+	error,
+	error_description: description
+});
+/** Shown when the authorization request itself is unusable — an unknown client, a `redirect_uri` that is not
+*  registered. Redirecting those back would turn the endpoint into an open redirector. */
+var sendErrorPage = (res, title, detail) => sendHtml(res, 400, renderErrorPage(title, detail));
+/** The other half of RFC 6749 error handling: once the redirect target is known to be legitimate, failures go
+*  back to the client so the host can report them, carrying `state` so it can match the response to its request. */
+var redirectWithError = (res, redirectUri, error, description, state) => {
+	const url = new URL(redirectUri);
+	url.searchParams.set("error", error);
+	url.searchParams.set("error_description", description);
+	if (state !== void 0) url.searchParams.set("state", state);
+	res.setStatus(302);
+	res.setHeader("Location", url.toString());
+	res.setHeader("Cache-Control", "no-store");
+	res.end();
+};
+var redirectWithCode = (res, redirectUri, code, state) => {
+	const url = new URL(redirectUri);
+	url.searchParams.set("code", code);
+	if (state !== void 0) url.searchParams.set("state", state);
+	res.setStatus(302);
+	res.setHeader("Location", url.toString());
+	res.setHeader("Cache-Control", "no-store");
+	res.end();
+};
+//#endregion
+export { redirectWithCode, redirectWithError, sendErrorJson, sendErrorPage, sendHtml, sendJson };

package/dist/modules/oauth/token.js

@@ -0,0 +1,92 @@
+import { scopesOf } from "./metadata.js";
+import { field, optionalField } from "./params.js";
+import { randomId, verifyChallenge } from "./pkce.js";
+import { dropCode, dropRefresh, getCode, getRefresh, putRefresh } from "./records.js";
+import { sendErrorJson, sendJson } from "./respond.js";
+//#region src/modules/oauth/token.ts
+var DEFAULT_REFRESH_TTL_SECONDS = 3600 * 24 * 30;
+var refreshTtlOf = (config) => config.refreshTtlSeconds ?? DEFAULT_REFRESH_TTL_SECONDS;
+var scopeOf = (config, requested) => requested ?? scopesOf(config).join(" ");
+/** The token response, plus a rotated refresh grant when refresh is enabled. Rotation is unconditional: a refresh
+*  token is a long-lived credential, so the one just used never stays valid. */
+var sendTokens = async (config, res, token, expiresInSeconds, grant) => {
+	const ttl = refreshTtlOf(config);
+	const body = {
+		access_token: token,
+		token_type: "Bearer",
+		scope: scopeOf(config, grant.scope)
+	};
+	if (expiresInSeconds !== void 0) body["expires_in"] = expiresInSeconds;
+	if (ttl > 0) {
+		const refreshToken = randomId();
+		await putRefresh(config.adapters.store, refreshToken, grant, ttl);
+		body["refresh_token"] = refreshToken;
+	}
+	sendJson(res, 200, body);
+};
+var exchangeCode = async (config, res, params) => {
+	const code = field(params, "code");
+	const record = code ? await getCode(config.adapters.store, code) : void 0;
+	if (!record) {
+		sendErrorJson(res, 400, "invalid_grant", "The authorization code is unknown or has expired.");
+		return;
+	}
+	await dropCode(config.adapters.store, code);
+	if (record.clientId !== field(params, "client_id")) {
+		sendErrorJson(res, 400, "invalid_grant", "The authorization code was issued to another client.");
+		return;
+	}
+	const redirectUri = optionalField(params, "redirect_uri");
+	if (redirectUri !== void 0 && redirectUri !== record.redirectUri) {
+		sendErrorJson(res, 400, "invalid_grant", "redirect_uri does not match the authorization request.");
+		return;
+	}
+	if (!verifyChallenge(field(params, "code_verifier"), record.challenge)) {
+		sendErrorJson(res, 400, "invalid_grant", "The PKCE code verifier does not match the challenge.");
+		return;
+	}
+	await sendTokens(config, res, record.token, record.expiresInSeconds, {
+		clientId: record.clientId,
+		scope: record.scope,
+		user: record.user,
+		target: record.target
+	});
+};
+var exchangeRefresh = async (config, res, params) => {
+	if (refreshTtlOf(config) === 0) {
+		sendErrorJson(res, 400, "unsupported_grant_type", "This server issues no refresh tokens.");
+		return;
+	}
+	const refreshToken = field(params, "refresh_token");
+	const record = refreshToken ? await getRefresh(config.adapters.store, refreshToken) : void 0;
+	if (!record) {
+		sendErrorJson(res, 400, "invalid_grant", "The refresh token is unknown or has expired.");
+		return;
+	}
+	await dropRefresh(config.adapters.store, refreshToken);
+	if (record.clientId !== field(params, "client_id")) {
+		sendErrorJson(res, 400, "invalid_grant", "The refresh token was issued to another client.");
+		return;
+	}
+	const issued = await config.adapters.issueToken(record.user, record.target);
+	if (!issued) {
+		sendErrorJson(res, 400, "invalid_grant", "The account no longer has access to this resource.");
+		return;
+	}
+	await sendTokens(config, res, issued.token, issued.expiresInSeconds, record);
+};
+/** POST /token. Public clients only, so there is no client authentication to check — PKCE is what proves the
+*  caller is the one that started the flow. */
+var handleToken = async (config, res, params) => {
+	switch (field(params, "grant_type")) {
+		case "authorization_code":
+			await exchangeCode(config, res, params);
+			return;
+		case "refresh_token":
+			await exchangeRefresh(config, res, params);
+			return;
+		default: sendErrorJson(res, 400, "unsupported_grant_type", "Supported grants: authorization_code, refresh_token.");
+	}
+};
+//#endregion
+export { handleToken };

package/dist/plugins/manager.js

@@ -1,6 +1,7 @@
 import { compilePlugin } from "./compile.js";
 import { copyPlugin } from "./copy.js";
 import { detectAction, isComponentSource } from "./detect.js";
+import { assertPluginSources } from "./validate.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region src/plugins/manager.ts
@@ -19,6 +20,7 @@ var PluginManager = class {
 	nameIndex = /* @__PURE__ */ new Map();
 	devMode = false;
 	constructor(plugins, cacheDir, ttlMs, devMode = false) {
+		assertPluginSources(plugins);
 		this.plugins = plugins;
 		this.outputDir = path.resolve(process.cwd(), cacheDir ?? DEFAULT_CACHE_DIR);
 		this.ttlMs = ttlMs ?? DEFAULT_TTL_MS;

package/dist/plugins/validate.js

@@ -0,0 +1,23 @@
+import { isComponentSource } from "./detect.js";
+import fs from "node:fs";
+//#region src/plugins/validate.ts
+var isRemote = (js) => js.startsWith("http://") || js.startsWith("https://");
+/** The file a plugin source needs on disk, or null when nothing local is involved — a remote URL (fetched and
+*  cached at request time) or a component handed in directly. */
+var localSourcePath = (source) => {
+	if (isComponentSource(source) || isRemote(source.js)) return null;
+	return source.js;
+};
+/** Fail at boot on a plugin whose entry file is missing. A plugin entry is a plain string path in the server
+*  config, so nothing — not tsc, not eslint — notices when that file is moved or deleted; without this check the
+*  server starts happily and only dies on the first render that needs the plugin, with an esbuild resolve error
+*  far from its cause. */
+var assertPluginSources = (plugins) => {
+	const missing = Object.entries(plugins).map(([name, source]) => ({
+		name,
+		file: localSourcePath(source)
+	})).filter((entry) => entry.file !== null && !fs.existsSync(entry.file)).map((entry) => `  ${entry.name}: ${entry.file ?? ""}`);
+	if (missing.length > 0) throw new Error(`Plugin entry file not found (declared in the server config):\n${missing.join("\n")}`);
+};
+//#endregion
+export { assertPluginSources, localSourcePath };

package/dist/src/core/http/dispatcher.test.d.ts

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

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

@@ -10,6 +10,9 @@ export interface BaseContext {
     res: SSRResponseHelpers;
     config: SSRServerConfig;
     port: number;
+    /** 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;
 }
 export interface SSRContext extends BaseContext {
     renderFn: SSRTemplateFn;

package/dist/src/core/requestParser.d.ts

@@ -4,4 +4,9 @@ export declare const parseRequest: (raw: IncomingMessage) => SSRRequest;
 /** The public origin the request was addressed to (proxy-aware via x-forwarded-proto, port included), or an empty
  *  string when the request carries no usable authority. */
 export declare const requestOrigin: (req: SSRRequest) => string;
+/** The address the request came from, seen through the proxies a deployment sits behind: Cloudflare states the
+ *  peer it accepted in `cf-connecting-ip`, the ingress in `x-real-ip`, and `x-forwarded-for` lists the chain with
+ *  the original client first. All three are plain headers a direct client can forge, so this is log/diagnostic
+ *  material — never an authorisation input. Falls back to the socket peer, which no client controls. */
+export declare const clientIp: (raw: IncomingMessage, req: SSRRequest) => string;
 export declare const readRawBody: (raw: IncomingMessage) => Promise<string>;

package/dist/src/core/services/oauth.d.ts

@@ -0,0 +1,8 @@
+import { Stage } from '../http/types';
+/** 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. */
+export declare const oauthStage: Stage;

package/dist/src/helpers/buildResponseHelpers.d.ts

@@ -1,6 +1,8 @@
 import { SSRResponseHelpers } from '@plitzi/sdk-shared';
 export type RawResponse = {
     headersSent: boolean;
+    /** The status actually written to the wire — the access log reads it once the response is out. */
+    statusCode: number;
     setHeader(name: string, value: string | number | readonly string[]): unknown;
     getHeaders(): Record<string, string | number | readonly string[]>;
     writeHead(statusCode: number, headers?: Record<string, string | number | readonly string[]>): unknown;

package/dist/src/helpers/serverLog.d.ts

@@ -0,0 +1,10 @@
+import { ServerLogEvent, ServerLogger } from '@plitzi/sdk-shared';
+/** One line for any {@link ServerLogEvent}: an HTTP request reads as an access-log line
+ *  (`[SSR] 203.0.113.7 GET /pricing 200 12ms ok`), the MCP events as what happened inside one
+ *  (`[mcp] tools/call plitzi_apply {operations:[3]} 41ms ok`). Rendering is a pure format — the dispatcher
+ *  already stripped query values, collected no headers, cookies or tokens and summarised tool args by shape;
+ *  the client IP it does carry is personal data, so a sink that persists these lines must say so. */
+export declare const renderLogEvent: (event: ServerLogEvent) => string;
+/** A drop-in `SSRServerConfig.logger` for consumers that just want the log on the console. Consumers with their
+ *  own logging stack should pass their own sink instead and read the structured event. */
+export declare const consoleLogger: ServerLogger;

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 export { createServer, createSSRServer, createMCPServer, resolveServices } from './core/createServer';
 export { registerHealthCheck, buildHealthPayload } from './core/health';
+export { consoleLogger, renderLogEvent } from './helpers/serverLog';
 export type { HealthCheckApp, HealthIdentity } from './core/health';
 export { createJsonAdapters } from './adapters/jsonAdapters';
 export { AIEngine, toolResponseOk, toolResponseErr, zodToJsonSchema, getAllowedModes, bindTools, isToolActive, resolveToolHandler, isCallToolResult, toolResponseFromResult } from './modules/ai';

package/dist/src/mcp.d.ts

@@ -4,6 +4,7 @@
  *  AI engine…), so pulling `createMCPServer` from there makes the process load that whole graph — including the
  *  React element packages its types come from — where this entry loads only the MCP server. */
 export { createMCPServer } from './core/server/mcpServer';
+export { consoleLogger, renderLogEvent } from './helpers/serverLog';
 export { createMcpServer, handleMcp, serveMcp, readMcpBody } from './modules/mcp/handler';
 export { createHttpPreviewClient } from './modules/mcp/previewClient';
 export { createHttpScreenshotClient } from './modules/mcp/screenshotClient';

package/dist/src/modules/mcp/handler.d.ts

@@ -1,16 +1,16 @@
 import { createMcpServer } from './server';
 import { PreviewClient, ScreenshotClient } from './types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { SSRAdapters, SSRRequest, McpLogger } from '@plitzi/sdk-shared';
+import { SSRAdapters, SSRRequest, ServerLogger } from '@plitzi/sdk-shared';
 import { IncomingMessage, ServerResponse } from 'node:http';
 /** Per-request wiring the MCP service does not resolve itself: the renderer clients and the log sink. Everything
  *  here is optional — the service degrades feature by feature. */
 export type McpRequestOptions = {
     preview?: PreviewClient;
     screenshot?: ScreenshotClient;
-    logger?: McpLogger;
+    logger?: ServerLogger;
 };
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
-export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<void>;
-export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, options?: McpRequestOptions) => Promise<void>;
+export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<string | undefined>;
+export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, options?: McpRequestOptions) => Promise<string | undefined>;
 export { createMcpServer };

package/dist/src/modules/mcp/helpers/log.d.ts

@@ -1,8 +1,8 @@
-import { McpLogger } from '@plitzi/sdk-shared';
+import { ServerLogger } from '@plitzi/sdk-shared';
 export interface McpLog {
     toolCall(name: string, args: unknown, ms: number, error?: unknown): void;
     resourceRead(uri: string, ms: number, error?: unknown): void;
 }
-/** Build the request-log sink for one MCP server. Dispatches structured events to the consumer's `logger` when
+/** Build the protocol-log sink for one MCP server. Dispatches structured events to the consumer's `logger` when
  *  provided; otherwise renders to the console when MCP_DEBUG=1; otherwise a no-op. */
-export declare const createMcpLog: (logger?: McpLogger) => McpLog;
+export declare const createMcpLog: (logger?: ServerLogger) => McpLog;

package/dist/src/modules/mcp/resources/renderGuide.d.ts

@@ -1,4 +1,5 @@
+import { McpLog } from '../helpers';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
 export declare const RENDER_TYPES_URI = "plitzi://render/types";
-export declare const registerRenderResources: (server: McpServer) => void;
+export declare const registerRenderResources: (server: McpServer, log: McpLog) => void;

package/dist/src/modules/mcp/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { PreviewClient, ScreenshotClient } from './types';
-import { SSRAdapters, McpLogger } from '@plitzi/sdk-shared';
+import { SSRAdapters, ServerLogger } from '@plitzi/sdk-shared';
 /** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
  *  space fresh through the adapters — schema and style are two documents, read/written independently. Both the
  *  spaceId and the space itself resolve lazily, so the public surface (handshake, tools-list, resources-list,
@@ -17,6 +17,6 @@ export interface McpServerContext {
     screenshot?: ScreenshotClient;
     /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
-    logger?: McpLogger;
+    logger?: ServerLogger;
 }
 export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => McpServer;

package/dist/src/modules/oauth/authorize.d.ts

@@ -0,0 +1,7 @@
+import { OAuthParams } from './params';
+import { OAuthConfig, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** GET /authorize — the entry point a host opens in the user's browser. */
+export declare const handleAuthorizeStart: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams) => Promise<void>;
+/** POST /authorize — both steps of the form land here: the credentials submit, and the grant submit that carries
+ *  the `pending` id proving the credentials step already passed. */
+export declare const handleAuthorizeSubmit: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams) => Promise<void>;

package/dist/src/modules/oauth/consentPage.d.ts

@@ -0,0 +1,7 @@
+import { OAuthConsentView } from '@plitzi/sdk-shared';
+/** The built-in consent screen: a credentials step, then a step to pick what the client gets access to. Replace it
+ *  wholesale via `oauth.renderConsent` — the field names read back here are the contract, not the markup. */
+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/src/modules/oauth/metadata.d.ts

@@ -0,0 +1,17 @@
+import { OAuthConfig, SSRRequest } from '@plitzi/sdk-shared';
+export declare const AUTHORIZE_PATH = "/authorize";
+export declare const TOKEN_PATH = "/token";
+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[];
+/** 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`. */
+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. */
+export declare const authorizationServerMetadata: (config: OAuthConfig, req: SSRRequest) => Record<string, unknown>;

package/dist/src/modules/oauth/oauth.test.d.ts

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

package/dist/src/modules/oauth/params.d.ts

@@ -0,0 +1,5 @@
+/** Query-string or form fields as they arrive from a client: every name is optional, and an absent one is not
+ *  distinguishable from an empty one — both mean "the client did not send this". */
+export type OAuthParams = Record<string, string | undefined>;
+export declare const field: (params: OAuthParams, name: string) => string;
+export declare const optionalField: (params: OAuthParams, name: string) => string | undefined;

package/dist/src/modules/oauth/pkce.d.ts

@@ -0,0 +1,6 @@
+/** An unguessable, URL-safe identifier for the values this layer hands out (codes, refresh tokens, client ids).
+ *  256 bits from the CSPRNG, so they are also unguessable by anyone who collects a few of them. */
+export declare const randomId: () => string;
+/** RFC 7636 S256, the only method this server accepts — `plain` puts the verifier on the wire, and a public
+ *  client on a desktop host has no other proof it is the one that started the flow. */
+export declare const verifyChallenge: (verifier: string, challenge: string) => boolean;