@plitzi/sdk-shared 0.32.10 → 0.32.12

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @plitzi/sdk-shared
 
+## 0.32.12
+
+### Patch Changes
+
+- v0.32.12
+- Updated dependencies
+  - @plitzi/nexus@0.32.12
+
+## 0.32.11
+
+### Patch Changes
+
+- v0.32.11
+- Updated dependencies
+  - @plitzi/nexus@0.32.11
+
 ## 0.32.10
 
 ### Patch Changes

package/dist/types/ServerTypes.d.ts

@@ -193,27 +193,61 @@ export type SSRRscConfig = {
     /** Server-side cache TTL for RSC responses in milliseconds. Defaults to 30 000. Set to 0 to disable. */
     cacheTtlMs?: number;
 };
-/** A structured log event the MCP server emits for each tool call and resource read, so a CONSUMER can render its
- *  own request log (dev tooling, a dashboard, structured logging). Wire a sink via `SSRServerConfig.mcpLogger`;
- *  without one the server prints to the console only when `MCP_DEBUG=1`. */
-export type McpLogEvent = {
-    /** 'tool' for a plitzi_* tool call, 'resource' for a plitzi:// resource read. */
-    kind: 'tool' | 'resource';
-    /** The tool name (e.g. 'plitzi_apply') or the resource URI that was read. */
-    name: string;
-    /** Wall-clock duration of the handler, in milliseconds. */
+/** What every log event carries, whatever layer it came from. */
+type ServerLogEventBase = {
+    /** Wall-clock duration of the work the event describes, in milliseconds. */
     durationMs: number;
-    /** Whether the handler completed without throwing. */
+    /** False when the work threw or answered an error status. */
     ok: boolean;
-    /** The error message when `ok` is false. */
+    /** The error message when `ok` is false — never the request payload. */
     error?: string;
-    /** A compact, truncated JSON summary of the tool arguments (tool events only). */
-    argsSummary?: string;
     /** ISO-8601 timestamp of when the event was emitted. */
     timestamp: string;
 };
-/** A sink the consumer provides to receive every MCP {@link McpLogEvent} (see `SSRServerConfig.mcpLogger`). */
-export type McpLogger = (event: McpLogEvent) => void;
+/** One HTTP request served by ANY Plitzi server — SSR pages, RSC, plugin assets, the preview endpoint, MCP —
+ *  emitted by the dispatcher once the request is answered, including the ones that failed or were rejected. */
+export type ServerRequestLogEvent = ServerLogEventBase & {
+    kind: 'request';
+    /** Which server answered — the dispatcher label, e.g. 'SSR' or 'MCP'. */
+    server: string;
+    method: string;
+    /** Request path with query VALUES stripped and only the keys kept, e.g. '/search?q&page'. */
+    path: string;
+    /** The operation inside the request, when the answering stage names one — e.g. the MCP JSON-RPC method. */
+    operation?: string;
+    /** The HTTP status the server answered with. */
+    status: number;
+    /** The client the request came from, resolved through the proxies the deployment sits behind. Empty when no
+     *  address could be determined. It IS personal data — see the note on {@link ServerLogEvent}. */
+    clientIp?: string;
+};
+/** One plitzi_* tool call inside an MCP request. Reported separately from the request because a failing tool
+ *  still answers HTTP 200 — the failure lives in the JSON-RPC payload, so only this event exposes it. */
+export type McpToolLogEvent = ServerLogEventBase & {
+    kind: 'tool';
+    /** The tool name, e.g. 'plitzi_apply'. */
+    name: string;
+    /** A compact SHAPE summary of the arguments — keys, value types and array lengths, never values. Set
+     *  `MCP_LOG_ARGS=1` to dump the real arguments instead; they may carry user content, so it stays opt-in. */
+    argsSummary?: string;
+};
+/** One plitzi:// resource read inside an MCP request, named by the URI the request asked for. */
+export type McpResourceLogEvent = ServerLogEventBase & {
+    kind: 'resource';
+    /** The resource URI that was read, e.g. 'plitzi://element/hero_1'. */
+    name: string;
+};
+/** Everything a Plitzi server reports about the work it does, as ONE stream: the HTTP requests it answers, plus
+ *  the MCP tool calls and resource reads that happen inside them. Wire a single sink via `SSRServerConfig.logger`
+ *  and switch on `kind` — a consumer can render it, ship it to a dashboard or drop the kinds it does not want.
+ *
+ *  Payload-free by construction: no headers, cookies, tokens nor request body ever reach an event, query values
+ *  are stripped from paths and tool arguments are reduced to their shape. Two fields are NOT anonymous and a
+ *  consumer shipping these events must handle them accordingly: `clientIp` on a request event, and the request
+ *  path, which is kept verbatim because it is what makes the log usable. */
+export type ServerLogEvent = ServerRequestLogEvent | McpToolLogEvent | McpResourceLogEvent;
+/** The sink a consumer provides to receive every {@link ServerLogEvent} (see `SSRServerConfig.logger`). */
+export type ServerLogger = (event: ServerLogEvent) => void;
 export type SSRServerConfig = {
     port?: number;
     host?: string;
@@ -257,10 +291,10 @@ export type SSRServerConfig = {
         enabled?: boolean;
         path?: string;
     };
-    /** Receives a structured {@link McpLogEvent} for every MCP tool call and resource read, so the consumer can
-     *  render its own request log (e.g. in dev mode). Without it, the MCP server logs to the console only when
-     *  `MCP_DEBUG=1`. */
-    mcpLogger?: McpLogger;
+    /** Receives a {@link ServerLogEvent} for every HTTP request this server answers — whatever stage answered it
+     *  and whatever the outcome — plus every MCP tool call and resource read inside those requests. Without it the
+     *  server reports nothing per request (the MCP events still reach the console when `MCP_DEBUG=1`). */
+    logger?: ServerLogger;
     adapters: SSRAdapters;
     /** Draft-preview endpoint for the MCP visual-preview tools (the RENDERER side). Off unless `enabled`. */
     preview?: SSRPreviewConfig;
@@ -300,6 +334,8 @@ export type SSRServerConfig = {
     };
     /** Cache-buster appended as ?v=<assetVersion> to all default SDK asset URLs (jsPath, cssPath, react vendor). Compute from file mtime or package version at startup. */
     assetVersion?: string;
+    /** OAuth 2.1 authorization for the MCP server. Omit to keep the server anonymous — see {@link OAuthConfig}. */
+    oauth?: OAuthConfig;
 };
 export type ServerServices = {
     ssr?: boolean;
@@ -333,6 +369,96 @@ export type SSRServer = {
     readonly cache: CacheManager | null;
     readonly plugins: PluginRegistry;
 };
+/** A key/value store with per-entry expiry, backing the OAuth layer's short-lived protocol state (registered
+ *  clients, authorization codes, refresh grants). Values are opaque strings the SDK serialises itself. A
+ *  multi-replica deployment MUST inject a shared implementation — a code minted on one replica is redeemed on
+ *  whichever replica the token request lands on. */
+export type OAuthStore = {
+    put: (key: string, value: string, ttlSeconds: number) => void | Promise<void>;
+    get: (key: string) => (string | undefined) | Promise<string | undefined>;
+    drop: (key: string) => void | Promise<void>;
+};
+/** Someone who got through {@link OAuthAdapters.authenticate}. `id` is what the other adapters key off; `label`
+ *  is shown back on the consent screen so the user can see who they are about to grant access as. */
+export type OAuthUser = {
+    id: string;
+    label: string;
+};
+/** One thing the user may grant the client access to — a Plitzi space, or whatever else a deployment scopes its
+ *  tokens by. `value` is the opaque handle the SDK round-trips back to {@link OAuthAdapters.issueToken}; only the
+ *  consumer interprets it. A deployment whose public surface is useful on its own (plitzi_render needs no space)
+ *  can offer a target that grants nothing, so the user is never forced to pick one. */
+export type OAuthGrantTarget = {
+    value: string;
+    label: string;
+    description?: string;
+};
+/** What the OAuth layer cannot resolve on its own: who the user is, what they may grant, and the bearer to mint
+ *  for them. The SDK owns the protocol (discovery, registration, PKCE, code exchange); the consumer owns identity
+ *  and issues a token its own `adapters.getSpaceId` will accept back. */
+export type OAuthAdapters = {
+    /** Verify the credentials typed into the consent screen. Return undefined to re-show the form with an error —
+     *  never throw for a wrong password. */
+    authenticate: (credentials: {
+        username: string;
+        password: string;
+    }) => Promise<OAuthUser | undefined>;
+    /** What this user may grant access to. An empty list ends the flow with `access_denied`. */
+    grantTargets: (user: OAuthUser) => Promise<OAuthGrantTarget[]>;
+    /** Mint the bearer the client will send on every MCP request. Return undefined to deny the grant. */
+    issueToken: (user: OAuthUser, target: OAuthGrantTarget) => Promise<{
+        token: string;
+        expiresInSeconds?: number;
+    } | undefined>;
+    store: OAuthStore;
+};
+/** What the built-in consent screen shows around the form. Ignored when `renderConsent` replaces the page. */
+export type OAuthBranding = {
+    /** Shown as the heading, e.g. 'Plitzi'. Defaults to 'Plitzi'. */
+    productName?: string;
+    /** Absolute or same-origin URL of a logo to show above the heading. */
+    logoUrl?: string;
+    /** Extra CSS appended to the page's own, for a deployment that wants its own look without replacing the page. */
+    css?: string;
+};
+/** Everything the consent screen needs to render itself, for a deployment that replaces the built-in page. Return
+ *  a full HTML document; the SDK serves it as-is and reads the same form fields back. */
+export type OAuthConsentView = {
+    /** 'credentials' asks for username + password; 'target' asks which space to grant, after a successful login. */
+    step: 'credentials' | 'target';
+    /** Where the form must POST to (the authorize endpoint). */
+    action: string;
+    /** Hidden fields the form MUST round-trip verbatim, or the flow cannot be resumed. */
+    hidden: Record<string, string>;
+    /** Offered on the 'target' step only. */
+    targets: OAuthGrantTarget[];
+    /** Who logged in, on the 'target' step. */
+    user?: OAuthUser;
+    /** A message to show the user, e.g. after a failed login. */
+    error?: string;
+    branding: OAuthBranding;
+};
+/** OAuth 2.1 authorization for the MCP server (RFC 9728 discovery + RFC 7591 dynamic client registration +
+ *  authorization code with PKCE). ENTIRELY OPTIONAL: without this config no endpoint is mounted, discovery keeps
+ *  answering 404 and the server stays anonymous, which is a working setup — the public surface (handshake, tool
+ *  and resource listing, the guide, plitzi_render) never needed a token. Configure it only to let a remote host
+ *  that cannot send custom headers — Claude Desktop, ChatGPT — obtain a space-scoped one. */
+export type OAuthConfig = {
+    adapters: OAuthAdapters;
+    /** The issuer/resource identifier published in the metadata documents. Defaults to the origin the request came
+     *  in on, which is correct whenever the server owns its sub-domain; set it when a proxy rewrites the host. */
+    issuer?: string;
+    /** Scope names advertised and echoed back on the token. Defaults to ['plitzi']. */
+    scopes?: string[];
+    /** How long an authorization code stays redeemable, in seconds. Default 60 — codes are one-shot and redeemed
+     *  immediately. */
+    codeTtlSeconds?: number;
+    /** How long a refresh grant lives, in seconds. Default 30 days. Set 0 to issue no refresh tokens. */
+    refreshTtlSeconds?: number;
+    branding?: OAuthBranding;
+    /** Replaces the built-in consent screen — return a full HTML document for the given step. */
+    renderConsent?: (view: OAuthConsentView) => string | Promise<string>;
+};
 /** A short-TTL, one-shot store for unsaved draft offline-data behind a preview token. The SDK ships an
  *  in-memory default (fine for a single replica); a multi-replica deployment injects a shared (e.g. Redis)
  *  implementation so a preview URL resolves on whichever replica the browser lands on. `take` consumes the
@@ -353,3 +479,4 @@ export type SSRPreviewConfig = {
     /** Token time-to-live in milliseconds. Default 60000. */
     ttlMs?: number;
 };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-shared",
-  "version": "0.32.10",
+  "version": "0.32.12",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -1184,9 +1184,6 @@
     "./types/SegmentTypes": {
       "types": "./dist/types/SegmentTypes.d.ts"
     },
-    "./types/ServerTypes": {
-      "types": "./dist/types/ServerTypes.d.ts"
-    },
     "./types/SpaceTypes": {
       "types": "./dist/types/SpaceTypes.d.ts"
     },
@@ -1233,7 +1230,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@plitzi/nexus": "0.32.10",
+    "@plitzi/nexus": "0.32.12",
     "@plitzi/plitzi-ui": "^1.6.18",
     "date-fns": "^4.4.0",
     "date-fns-tz": "^3.2.0",