@plitzi/sdk-server 0.33.1 → 0.34.0

package/dist/core/oauth/metadata.js

@@ -0,0 +1,71 @@
+import { requestOrigin } from "@plitzi/sdk-server/kernel";
+//#region src/core/oauth/metadata.ts
+var AUTHORIZE_PATH = "/authorize";
+var TOKEN_PATH = "/token";
+var REVOKE_PATH = "/revoke";
+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;
+var canonicalPath = (path) => path.replace(/\/+$/, "");
+/** 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. */
+var resourceMetadataUrl = (config, req) => `${issuerOf(config, req)}${PROTECTED_RESOURCE_PATH}${canonicalPath(req.path)}`;
+/** 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. */
+var protectedResourceMetadata = (config, req) => {
+	const issuer = issuerOf(config, req);
+	return {
+		resource: `${issuer}${canonicalPath(req.path.slice(37)) || "/"}`,
+		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. `offline_access` is advertised whenever refresh grants are issued,
+*  which is the signal a host looks for before asking for one. */
+var authorizationServerMetadata = (config, req) => {
+	const issuer = issuerOf(config, req);
+	const refreshes = config.refreshTtlSeconds !== 0;
+	const grantTypes = refreshes ? ["authorization_code", "refresh_token"] : ["authorization_code"];
+	const scopes = refreshes ? [...scopesOf(config), "offline_access"] : scopesOf(config);
+	return {
+		issuer,
+		authorization_endpoint: `${issuer}${AUTHORIZE_PATH}`,
+		token_endpoint: `${issuer}${TOKEN_PATH}`,
+		registration_endpoint: `${issuer}${REGISTER_PATH}`,
+		revocation_endpoint: `${issuer}${REVOKE_PATH}`,
+		response_types_supported: ["code"],
+		grant_types_supported: grantTypes,
+		code_challenge_methods_supported: ["S256"],
+		token_endpoint_auth_methods_supported: ["none"],
+		scopes_supported: scopes
+	};
+};
+//#endregion
+export { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, REVOKE_PATH, TOKEN_PATH, authorizationServerMetadata, issuerOf, protectedResourceMetadata, resourceMetadataUrl, scopesOf };

package/dist/core/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/core/oauth/params.js

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

package/dist/core/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;

package/dist/core/oauth/pkce.js

@@ -0,0 +1,15 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/core/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/core/oauth/records.d.ts

@@ -0,0 +1,72 @@
+import { OAuthGrantTarget, OAuthStore, OAuthUser } from '@plitzi/sdk-shared';
+/** A client that registered itself through RFC 7591. Public clients only — a desktop host cannot keep a secret,
+ *  so the token endpoint authenticates the exchange with PKCE instead. */
+export type ClientRecord = {
+    clientId: string;
+    clientName: string;
+    redirectUris: string[];
+    /** When this registration was first handed out, so re-registering the same client keeps reporting its real age. */
+    issuedAt: number;
+};
+/** The authorization request, parked while the user logs in. `challenge` binds the eventual code to the client
+ *  that started the flow. */
+export type PendingRecord = {
+    clientId: string;
+    redirectUri: string;
+    challenge: string;
+    state?: string;
+    scope?: string;
+    user: OAuthUser;
+};
+/** A code, redeemable once, for the token it already resolves to. Minting the bearer at consent time (rather than
+ *  at redemption) means a failure the user could act on — no space, revoked access — surfaces on the consent
+ *  screen instead of as an opaque `invalid_grant` inside the host. */
+export type CodeRecord = {
+    clientId: string;
+    redirectUri: string;
+    challenge: string;
+    token: string;
+    expiresInSeconds?: number;
+    scope?: string;
+    user: OAuthUser;
+    target: OAuthGrantTarget;
+};
+/** A refresh grant: everything needed to mint a fresh bearer without asking the user again. */
+export type RefreshRecord = {
+    clientId: string;
+    scope?: string;
+    user: OAuthUser;
+    target: OAuthGrantTarget;
+};
+/** A bearer this server handed out. The token a client holds is an opaque handle minted here, and this record is
+ *  what it stands for — including `credential`, the thing the deployment's own adapters understand, which never
+ *  leaves the server: a platform token is usually good against more than the MCP endpoint, and a remote host has
+ *  no business holding one. The record expires with the bearer, which is what turns an expired one into the 401 a
+ *  host answers by refreshing; dropping it early revokes the bearer outright. */
+export type AccessRecord = {
+    /** What {@link OAuthAdapters.issueToken} returned — swapped back onto the request once the bearer checks out.
+     *  Absent only in a record written before the bearer and the credential were separate things, where the bearer
+     *  WAS the credential: a live connector must survive that upgrade, so the reader falls back to the token itself. */
+    credential?: string;
+    clientId: string;
+    user: OAuthUser;
+    target: OAuthGrantTarget;
+};
+export declare const putClient: (store: OAuthStore, client: ClientRecord) => Promise<void>;
+export declare const getClient: (store: OAuthStore, clientId: string) => Promise<ClientRecord | undefined>;
+/** The id already handed out for an identical registration. Keyed by what the client asked to be registered AS,
+ *  so the same request always resolves to the same client — see handleRegister for why that matters. */
+export declare const getClientByFingerprint: (store: OAuthStore, fingerprint: string) => Promise<ClientRecord | undefined>;
+export declare const putClientFingerprint: (store: OAuthStore, fingerprint: string, clientId: string) => Promise<void>;
+export declare const putPending: (store: OAuthStore, id: string, pending: PendingRecord) => Promise<void>;
+export declare const getPending: (store: OAuthStore, id: string) => Promise<PendingRecord | undefined>;
+export declare const dropPending: (store: OAuthStore, id: string) => Promise<void>;
+export declare const putCode: (store: OAuthStore, code: string, record: CodeRecord, ttlSeconds: number) => Promise<void>;
+export declare const getCode: (store: OAuthStore, code: string) => Promise<CodeRecord | undefined>;
+export declare const dropCode: (store: OAuthStore, code: string) => Promise<void>;
+export declare const putRefresh: (store: OAuthStore, token: string, record: RefreshRecord, ttlSeconds: number) => Promise<void>;
+export declare const getRefresh: (store: OAuthStore, token: string) => Promise<RefreshRecord | undefined>;
+export declare const dropRefresh: (store: OAuthStore, token: string) => Promise<void>;
+export declare const dropAccess: (store: OAuthStore, token: string) => Promise<void>;
+export declare const putAccess: (store: OAuthStore, token: string, record: AccessRecord, ttlSeconds: number) => Promise<void>;
+export declare const getAccess: (store: OAuthStore, token: string) => Promise<AccessRecord | undefined>;

package/dist/core/oauth/records.js

@@ -0,0 +1,49 @@
+//#region src/core/oauth/records.ts
+var CLIENT_TTL_SECONDS = 7776e3;
+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);
+/** The id already handed out for an identical registration. Keyed by what the client asked to be registered AS,
+*  so the same request always resolves to the same client — see handleRegister for why that matters. */
+var getClientByFingerprint = async (store, fingerprint) => {
+	const clientId = await store.get(keyOf("clientfp", fingerprint));
+	return clientId ? getClient(store, clientId) : void 0;
+};
+var putClientFingerprint = async (store, fingerprint, clientId) => {
+	await store.put(keyOf("clientfp", fingerprint), clientId, CLIENT_TTL_SECONDS);
+};
+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));
+};
+var dropAccess = async (store, token) => {
+	await store.drop(keyOf("access", token));
+};
+var putAccess = (store, token, record, ttlSeconds) => writeJson(store, "access", token, record, ttlSeconds);
+var getAccess = (store, token) => readJson(store, "access", token);
+//#endregion
+export { dropAccess, dropCode, dropPending, dropRefresh, getAccess, getClient, getClientByFingerprint, getCode, getPending, getRefresh, putAccess, putClient, putClientFingerprint, putCode, putPending, putRefresh };

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

@@ -0,0 +1,5 @@
+import { OAuthConfig, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** 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. */
+export declare const handleRegister: (config: OAuthConfig, res: SSRResponseHelpers, body: unknown) => Promise<void>;

package/dist/core/oauth/register.js

@@ -0,0 +1,55 @@
+import { randomId } from "./pkce.js";
+import { getClientByFingerprint, putClient, putClientFingerprint } from "./records.js";
+import { sendErrorJson, sendJson } from "./respond.js";
+import { createHash } from "node:crypto";
+//#region src/core/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") : [];
+var nowSeconds = () => Math.floor(Date.now() / 1e3);
+var fingerprintOf = (clientName, redirectUris) => createHash("sha256").update(JSON.stringify([clientName, [...redirectUris].sort()])).digest("base64url");
+/** 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 { store } = config.adapters;
+	const fingerprint = fingerprintOf(clientName, redirectUris);
+	const client = await getClientByFingerprint(store, fingerprint) ?? {
+		clientId: randomId(),
+		clientName,
+		redirectUris,
+		issuedAt: nowSeconds()
+	};
+	await putClient(store, client);
+	await putClientFingerprint(store, fingerprint, client.clientId);
+	sendJson(res, 201, {
+		client_id: client.clientId,
+		client_id_issued_at: client.issuedAt,
+		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/core/oauth/respond.d.ts

@@ -0,0 +1,21 @@
+import { SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** The error codes RFC 6749 defines for the responses this server produces. */
+export type OAuthErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'unsupported_response_type' | 'invalid_scope' | 'access_denied' | 'server_error';
+export declare const sendJson: (res: SSRResponseHelpers, status: number, body: unknown) => void;
+export declare const sendHtml: (res: SSRResponseHelpers, status: number, html: string) => void;
+export declare const sendErrorJson: (res: SSRResponseHelpers, status: number, error: OAuthErrorCode, description: string) => void;
+/** 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. */
+export declare const sendErrorPage: (res: SSRResponseHelpers, title: string, detail: string) => void;
+/** 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. */
+export declare const redirectWithError: (res: SSRResponseHelpers, redirectUri: string, error: OAuthErrorCode, description: string, state?: string) => void;
+/**
+ * Send the browser somewhere else entirely, carrying where to come back to.
+ *
+ * Used for the hand-off to the sign-in screen. The destination is passed as `redirect` — the same param the auth
+ * space reads — and it is the WHOLE authorization request, so resuming is an ordinary navigation and this server
+ * keeps no session of its own for a flow that is one page long.
+ */
+export declare const redirectToSignIn: (res: SSRResponseHelpers, signInUrl: string, returnTo: string) => void;
+export declare const redirectWithCode: (res: SSRResponseHelpers, redirectUri: string, code: string, state?: string) => void;

package/dist/core/oauth/respond.js

@@ -0,0 +1,59 @@
+import { renderErrorPage } from "./consentPage.js";
+//#region src/core/oauth/respond.ts
+var sendJson = (res, status, body) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json");
+	res.setHeader("Cache-Control", "no-store, no-transform");
+	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, no-transform");
+	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, no-transform");
+	res.end();
+};
+/**
+* Send the browser somewhere else entirely, carrying where to come back to.
+*
+* Used for the hand-off to the sign-in screen. The destination is passed as `redirect` — the same param the auth
+* space reads — and it is the WHOLE authorization request, so resuming is an ordinary navigation and this server
+* keeps no session of its own for a flow that is one page long.
+*/
+var redirectToSignIn = (res, signInUrl, returnTo) => {
+	const url = new URL(signInUrl);
+	url.searchParams.set("redirect", returnTo);
+	res.setStatus(302);
+	res.setHeader("Location", url.toString());
+	res.setHeader("Cache-Control", "no-store, no-transform");
+	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, no-transform");
+	res.end();
+};
+//#endregion
+export { redirectToSignIn, redirectWithCode, redirectWithError, sendErrorJson, sendErrorPage, sendHtml, sendJson };

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

@@ -0,0 +1,14 @@
+import { OAuthParams } from './params';
+import { OAuthConfig, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * POST /revoke — RFC 7009. Ends a grant, which is what signing out of a native client has to do.
+ *
+ * Without it, signing out ends the SESSION and leaves the refresh token that can mint another one: the app has
+ * deleted its copy, but a leaked one stays good until its TTL. The endpoint answers 200 whatever happens, as the
+ * RFC requires — a client cannot be told whether a token it presented was real, and a sign-out that reports a
+ * failure is one people ignore.
+ */
+export declare const handleRevoke: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams) => Promise<void>;
+/** 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. */
+export declare const handleToken: (config: OAuthConfig, res: SSRResponseHelpers, params: OAuthParams) => Promise<void>;

package/dist/core/oauth/token.js

@@ -0,0 +1,130 @@
+import { scopesOf } from "./metadata.js";
+import { field, optionalField } from "./params.js";
+import { randomId, verifyChallenge } from "./pkce.js";
+import { dropAccess, dropCode, dropRefresh, getCode, getRefresh, putAccess, putRefresh } from "./records.js";
+import { sendErrorJson, sendJson } from "./respond.js";
+//#region src/core/oauth/token.ts
+var DEFAULT_REFRESH_TTL_SECONDS = 2592e3;
+var DEFAULT_ACCESS_TTL_SECONDS = 2592e3;
+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, credential, expiresInSeconds, grant) => {
+	const ttl = refreshTtlOf(config);
+	/**
+	* What the client actually receives, and the two answers are a real policy choice.
+	*
+	* By default it is a HANDLE to the grant, not the credential behind it: what `issueToken` minted is usually good
+	* against more of the platform than this endpoint, so it stays on this side of the boundary and the resource
+	* side swaps it back. That is right for a connector holding a space token.
+	*
+	* `directTokens` gives the client the credential itself, for the case where the credential is exactly what the
+	* client should hold — a native app granted the person's own SESSION. There the handle buys nothing and costs:
+	* a second thing to revoke, and a store read on every request to an API that already knows how to read a
+	* session. Either way an access record is written, because it is also what lets the resource side recognise a
+	* bearer this server issued.
+	*/
+	const bearer = config.directTokens ? credential : randomId();
+	await putAccess(config.adapters.store, bearer, {
+		credential,
+		clientId: grant.clientId,
+		user: grant.user,
+		target: grant.target
+	}, Math.max(expiresInSeconds ?? DEFAULT_ACCESS_TTL_SECONDS, 1));
+	const body = {
+		access_token: bearer,
+		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 /revoke — RFC 7009. Ends a grant, which is what signing out of a native client has to do.
+*
+* Without it, signing out ends the SESSION and leaves the refresh token that can mint another one: the app has
+* deleted its copy, but a leaked one stays good until its TTL. The endpoint answers 200 whatever happens, as the
+* RFC requires — a client cannot be told whether a token it presented was real, and a sign-out that reports a
+* failure is one people ignore.
+*/
+var handleRevoke = async (config, res, params) => {
+	const token = optionalField(params, "token");
+	if (token) {
+		await dropRefresh(config.adapters.store, token);
+		await dropAccess(config.adapters.store, token);
+	}
+	res.setStatus(200);
+	res.end();
+};
+/** 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 { handleRevoke, handleToken };

package/dist/core/previewToken.d.ts

@@ -1 +1,21 @@
+import { SSRRequest } from '@plitzi/sdk-shared';
 export declare const PREVIEW_TOKEN_PARAM = "__pt";
+/**
+ * Where a REUSABLE draft token is remembered for the rest of the visit.
+ *
+ * The query param alone previews one URL, which is all a screenshot ever needed. A person iterating does more than
+ * look at one URL: they follow a link, the SDK asks `/_rsc` for fresh data, they press back. Every one of those is a
+ * request without the param, and answering the saved space to a browser that is looking at a draft is the kind of
+ * confusion that gets reported as "the preview randomly reverts".
+ *
+ * `HttpOnly` because nothing in the page has any use for it, and `SameSite=Lax` so another site cannot cause a draft
+ * to be resolved in a visitor's browser. It is set only for a token the store minted as reusable.
+ */
+export declare const PREVIEW_COOKIE = "plitzi_draft";
+/**
+ * The draft this request is looking at, whichever way it says so.
+ *
+ * The query param wins: it is how a session is STARTED, and re-minting while an older one is still in the cookie has
+ * to answer the new draft or the loop shows stale work.
+ */
+export declare const readDraftToken: (req: SSRRequest) => string | undefined;

package/dist/core/previewToken.js

@@ -1,4 +1,32 @@
 //#region src/core/previewToken.ts
 var PREVIEW_TOKEN_PARAM = "__pt";
+/**
+* Where a REUSABLE draft token is remembered for the rest of the visit.
+*
+* The query param alone previews one URL, which is all a screenshot ever needed. A person iterating does more than
+* look at one URL: they follow a link, the SDK asks `/_rsc` for fresh data, they press back. Every one of those is a
+* request without the param, and answering the saved space to a browser that is looking at a draft is the kind of
+* confusion that gets reported as "the preview randomly reverts".
+*
+* `HttpOnly` because nothing in the page has any use for it, and `SameSite=Lax` so another site cannot cause a draft
+* to be resolved in a visitor's browser. It is set only for a token the store minted as reusable.
+*/
+var PREVIEW_COOKIE = "plitzi_draft";
+var cookieValue = (header, name) => {
+	if (!header) return;
+	for (const part of header.split(";")) {
+		const separator = part.indexOf("=");
+		if (separator > 0 && part.slice(0, separator).trim() === name) return decodeURIComponent(part.slice(separator + 1).trim());
+	}
+};
+/**
+* The draft this request is looking at, whichever way it says so.
+*
+* The query param wins: it is how a session is STARTED, and re-minting while an older one is still in the cookie has
+* to answer the new draft or the loop shows stale work.
+*/
+var readDraftToken = (req) => {
+	return req.query["__pt"] || cookieValue(req.headers.cookie, "plitzi_draft");
+};
 //#endregion
-export { PREVIEW_TOKEN_PARAM };
+export { PREVIEW_COOKIE, PREVIEW_TOKEN_PARAM, readDraftToken };

package/dist/core/server/pageServer.js

@@ -1,3 +1,4 @@
+import { actionsModuleFor } from "../../modules/actions/moduleFor.js";
 import { createHttpServer } from "./baseServer.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildCacheManager } from "../../helpers/cache/cacheManager.js";
@@ -30,6 +31,7 @@ var createPageServer = (config, services, extensions) => {
 			invalidatePluginComponentCache();
 		}
 	};
+	const actions = actionsModuleFor(config);
 	const stages = buildPagePipeline(services, extensions);
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
@@ -41,7 +43,8 @@ var createPageServer = (config, services, extensions) => {
 			port,
 			renderFn,
 			caches,
-			pluginManager
+			pluginManager,
+			actions
 		});
 		return makeHandler("SSR", buildContext, stages, config.compression);
 	};

package/dist/core/services/action.d.ts

@@ -1,9 +1,11 @@
 import { SSRContext, Stage } from '../http/types';
 /**
- * Write endpoint for server-driven providers. RSC is read-only, so this is the only path a page has to mutate a
- * connected backend — and it answers POST on its own path alone, never falling through to SSR.
+ * The action endpoint: server-driven provider writes, and server actions.
  *
- * Inert unless the consumer supplied the connector lookups: without them there is no manifest to authorize a
- * write against, and guessing would be the whole vulnerability.
+ * Two addressing modes on one path, because both are "the browser asks the server to change something, naming it
+ * rather than addressing it". An element-addressed body reaches a connector's declared write; an action-addressed
+ * one runs a stored flow. Each mode is inert unless its own half of the config is present, so a deployment that
+ * configures neither has no endpoint at all — and guessing what an unconfigured one should do would be the whole
+ * vulnerability.
  */
 export declare const actionStage: Stage<SSRContext>;