@plitzi/sdk-server 0.32.12 → 0.32.13

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @plitzi/sdk-server
 
+## 0.32.13
+
+### Patch Changes
+
+- v0.32.13
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.13
+  - @plitzi/sdk-schema@0.32.13
+  - @plitzi/sdk-shared@0.32.13
+
 ## 0.32.12
 
 ### Patch Changes

package/dist/core/services/oauth.js

@@ -1,7 +1,9 @@
 import { readRawBody } from "../requestParser.js";
 import { authorizationServerMetadata, protectedResourceMetadata } from "../../modules/oauth/metadata.js";
+import { getAccess } from "../../modules/oauth/records.js";
 import { sendErrorJson, sendJson } from "../../modules/oauth/respond.js";
 import { handleAuthorizeStart, handleAuthorizeSubmit } from "../../modules/oauth/authorize.js";
+import { bearerOf, sendChallenge } from "../../modules/oauth/challenge.js";
 import { handleRegister } from "../../modules/oauth/register.js";
 import { handleToken } from "../../modules/oauth/token.js";
 //#region src/core/services/oauth.ts
@@ -67,5 +69,37 @@ var oauthStage = async (ctx) => {
 	sendErrorJson(res, 405, "invalid_request", `${method} is not allowed on ${path}.`);
 	return true;
 };
+/** Fail-closed on purpose: a credential this server cannot check right now — an unreachable store, an adapter that
+*  threw — is not one it may act on, and 401 is the answer a host can do something about (re-authorize) where a
+*  500 leaves it stuck. */
+var verified = async (check) => {
+	try {
+		return await check();
+	} catch {
+		return false;
+	}
+};
+var isAuthorized = async (oauth, ctx, token) => {
+	if (await verified(async () => await getAccess(oauth.adapters.store, token) !== void 0)) return true;
+	const { adapters } = ctx.config;
+	return verified(async () => await adapters.getSpaceId?.(ctx.req) !== void 0);
+};
+/** 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 oauthGuardStage = async (ctx) => {
+	const { oauth } = ctx.config;
+	if (!oauth || ctx.req.method !== "POST") return false;
+	const token = bearerOf(ctx.req);
+	if (token && await isAuthorized(oauth, ctx, token)) return false;
+	sendChallenge(oauth, ctx.req, ctx.res, token ? "The access token is invalid, expired or revoked." : "Authorization is required to use this server.");
+	return true;
+};
 //#endregion
-export { oauthStage };
+export { oauthGuardStage, oauthStage };

package/dist/core/services/registry.js

@@ -1,5 +1,5 @@
 import { mcpOnlyStage, mcpStage } from "./mcp.js";
-import { oauthStage } from "./oauth.js";
+import { oauthGuardStage, oauthStage } from "./oauth.js";
 import { previewStage } from "./preview.js";
 import { rscStage } from "./rsc.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
@@ -30,6 +30,7 @@ var buildMCPPipeline = () => [
 	healthStage,
 	configStaticStage,
 	oauthStage,
+	oauthGuardStage,
 	mcpOnlyStage
 ];
 //#endregion

package/dist/modules/mcp/server.js

@@ -43,7 +43,7 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.12"
+		version: "0.32.13"
 	}, { instructions: serverInstructions });
 	registerResources(server, getSpace, MCP_ENV, log);
 	registerApps(server);

package/dist/modules/oauth/challenge.js

@@ -0,0 +1,33 @@
+import { resourceMetadataUrl, scopesOf } from "./metadata.js";
+import { sendJson } from "./respond.js";
+//#region src/modules/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/modules/oauth/metadata.js

@@ -11,22 +11,35 @@ var DEFAULT_SCOPES = ["plitzi"];
 *  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`. */
+*  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. */
 var protectedResourceMetadata = (config, req) => {
 	const issuer = issuerOf(config, req);
 	return {
-		resource: issuer,
+		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. */
+*  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 grantTypes = config.refreshTtlSeconds === 0 ? ["authorization_code"] : ["authorization_code", "refresh_token"];
+	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}`,
@@ -36,8 +49,8 @@ var authorizationServerMetadata = (config, req) => {
 		grant_types_supported: grantTypes,
 		code_challenge_methods_supported: ["S256"],
 		token_endpoint_auth_methods_supported: ["none"],
-		scopes_supported: scopesOf(config)
+		scopes_supported: scopes
 	};
 };
 //#endregion
-export { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, issuerOf, protectedResourceMetadata, scopesOf };
+export { AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, PROTECTED_RESOURCE_PATH, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, issuerOf, protectedResourceMetadata, resourceMetadataUrl, scopesOf };

package/dist/modules/oauth/records.js

@@ -31,5 +31,7 @@ var getRefresh = (store, token) => readJson(store, "refresh", token);
 var dropRefresh = async (store, token) => {
 	await store.drop(keyOf("refresh", token));
 };
+var putAccess = (store, token, record, ttlSeconds) => writeJson(store, "access", token, record, ttlSeconds);
+var getAccess = (store, token) => readJson(store, "access", token);
 //#endregion
-export { dropCode, dropPending, dropRefresh, getClient, getCode, getPending, getRefresh, putClient, putCode, putPending, putRefresh };
+export { dropCode, dropPending, dropRefresh, getAccess, getClient, getCode, getPending, getRefresh, putAccess, putClient, putCode, putPending, putRefresh };

package/dist/modules/oauth/token.js

@@ -1,10 +1,11 @@
 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 { dropCode, dropRefresh, getCode, getRefresh, putAccess, 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 DEFAULT_ACCESS_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
@@ -16,6 +17,11 @@ var sendTokens = async (config, res, token, expiresInSeconds, grant) => {
 		token_type: "Bearer",
 		scope: scopeOf(config, grant.scope)
 	};
+	await putAccess(config.adapters.store, token, {
+		clientId: grant.clientId,
+		user: grant.user,
+		target: grant.target
+	}, Math.max(expiresInSeconds ?? DEFAULT_ACCESS_TTL_SECONDS, 1));
 	if (expiresInSeconds !== void 0) body["expires_in"] = expiresInSeconds;
 	if (ttl > 0) {
 		const refreshToken = randomId();

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

@@ -6,3 +6,13 @@ import { Stage } from '../http/types';
  *  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;
+/** 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. */
+export declare const oauthGuardStage: Stage;

package/dist/src/modules/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/src/modules/oauth/metadata.d.ts

@@ -9,9 +9,19 @@ export declare const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorizati
  *  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`. */
+ *  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. */
 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. */
+ *  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>;

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

@@ -36,6 +36,15 @@ export type RefreshRecord = {
     user: OAuthUser;
     target: OAuthGrantTarget;
 };
+/** A bearer this server handed out, kept so the resource side can tell one it issued from a string a client made
+ *  up: the grant that carries no space mints an opaque token that resolves to nothing, and without a record there
+ *  is nothing to check it against. The record expires with the token, which is what turns an expired bearer into
+ *  the 401 a host answers by refreshing; dropping it early revokes the token. */
+export type AccessRecord = {
+    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>;
 export declare const putPending: (store: OAuthStore, id: string, pending: PendingRecord) => Promise<void>;
@@ -47,3 +56,5 @@ 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 putAccess: (store: OAuthStore, token: string, record: AccessRecord, ttlSeconds: number) => Promise<void>;
+export declare const getAccess: (store: OAuthStore, token: string) => Promise<AccessRecord | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.12",
+  "version": "0.32.13",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -29,9 +29,9 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@plitzi/plitzi-sdk": "0.32.12",
-    "@plitzi/sdk-schema": "0.32.12",
-    "@plitzi/sdk-shared": "0.32.12",
+    "@plitzi/plitzi-sdk": "0.32.13",
+    "@plitzi/sdk-schema": "0.32.13",
+    "@plitzi/sdk-shared": "0.32.13",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"