@solidcommerce/mcp-server 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,74 @@
+# @solidcommerce/mcp-server
+
+> **The Solid Commerce Platform — for AI agents.** Drop a single line into Claude Desktop (or any MCP-aware client) and an LLM can query catalog, orders, listings, inventory, vendors, CRM, and webhooks against your live tenant — read endpoints, repricing, fulfillment, bulk operations, the works — using your existing Solid Commerce API key. Foundation tools auto-track every endpoint in our OpenAPI spec; curated task tools collapse 5-10-call workflows into a single agent action so the LLM doesn't have to plan them itself.
+>
+> **Pick this when:** you want Claude (Desktop or hosted), the OpenAI Responses API, or any MCP client to operate on Solid Commerce data without writing custom integration code, OR you're a Solid Commerce customer building an internal copilot and need the platform's full API surface exposed safely (scoped per-tool, audited per-call, no token gymnastics).
+
+The official Model Context Protocol (MCP) server for the Solid Commerce Platform API. Exposes a hybrid tool set — foundation tools auto-generated from the OpenAPI spec plus curated task-shaped tools — over both stdio (for local clients like Claude Desktop / Claude Code) and **Streamable HTTP over HTTPS** (for hosted `mcp.solidcommerce.com`, the transport required by the Claude UI Connectors Directory). SSE was removed in Phase 0 / E-A1.
+
+See `phase3_solution_plan.md` and `requirements_api_cli_mcp.md` for the wider initiative context.
+
+## Quickstart
+
+```bash
+# Local (stdio, for Claude Desktop)
+npx @solidcommerce/cli mcp install   # idempotent Claude Desktop config snippet
+npx @solidcommerce/cli mcp serve     # boot stdio server
+
+# Or invoke this package directly
+SOLIDCOMMERCE_API_KEY=sk_... npx @solidcommerce/mcp-server
+```
+
+## Auth
+
+Two modes coexist on the same server (Phase 0 / E-A3):
+
+**API key (stdio / service-to-service / Scotty / internal).** Pass your Solid
+Commerce API key via env var:
+
+```
+SOLIDCOMMERCE_API_KEY=sk_live_...
+```
+
+**Per-user OAuth (remote hosts — Claude UI, ChatGPT, Gemini, M365, Grok).** A
+host sends a per-user `Authorization: Bearer <token>` issued by SC.Base.Auth on
+the Streamable HTTP transport. The server introspects the token against
+`/oauth/introspect` (using the `sc-mcp-server` confidential client) to fast-fail
+invalid tokens and extract claims for audit + telemetry, then forwards the token
+to Platform, which independently re-validates it. Configure with:
+
+```
+SC_MCP_OAUTH_ENABLED=true                 # auto-on when the two below are set
+SC_AUTH_INTROSPECT_URL=https://auth.solidcommerce.com/oauth/introspect
+SC_MCP_CLIENT_ID=sc-mcp-server
+SC_MCP_CLIENT_SECRET=...                   # from Key Vault
+```
+
+Resilience: introspection results are cached (bounded TTL under token `exp`) and
+guarded by a circuit breaker. Because Platform is the authority, an Auth outage
+**fails open** — a present bearer is still forwarded (marked degraded in audit) —
+while an explicitly *inactive* token is hard-rejected with `401`. A request with
+no `Authorization` header falls back to the API-key path.
+
+## Tool surface
+
+- **Foundation tools** — auto-generated from `vendor/openapi.snapshot.json`. ~40 selected via heuristic (read-heavy lists + composition-target POSTs). Naming: `<segment>_<resource>_<verb>` (matching the CLI's resource driver).
+- **Task tools** — 10 hand-authored workflow tools (publish_product_to_channels, reprice_listing, fulfill_order, …). Each composes 2-10 SDK calls and reports a clean structured result.
+
+## Audit trail
+
+Every tool invocation tags the underlying SDK call with `X-Audit-Source: mcp` and `X-Audit-Tool-Name: <tool>` headers; Platform's `AuditLogMiddleware` (W3) writes one `audit_log` row per call.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run lint
+npm run test
+npm run build
+```
+
+## License
+
+UNLICENSED — internal Solid Commerce code. Distribution via private Azure Artifacts npm feed (gated until 2026-05-10).

package/bin/solidcommerce-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// =============================================================================
+// bin/solidcommerce-mcp.js
+// Wave: W6 — MCP Server entrypoint shim.
+//
+// Forwards to dist/index.js. The TS source lives at src/index.ts.
+// =============================================================================
+import "../dist/index.js";

package/dist/audit/auditClient.d.ts

@@ -0,0 +1,51 @@
+import type { SolidCommerceClient } from "@solidcommerce/sdk";
+import type { SessionAuthContext } from "../auth/oauth.js";
+export declare const AUDIT_HEADER_SOURCE = "X-Audit-Source";
+export declare const AUDIT_HEADER_TOOL_NAME = "X-Audit-Tool-Name";
+export declare const AUDIT_HEADER_AUTH_MODE = "X-Audit-Auth-Mode";
+export declare const AUDIT_HEADER_INSTALL_ID = "X-Audit-Install-Id";
+/** Set when the bearer was forwarded WITHOUT a successful introspection
+ * (Auth outage / circuit open). Lets Platform audit flag unverified calls. */
+export declare const AUDIT_HEADER_AUTH_DEGRADED = "X-Audit-Auth-Degraded";
+/** Canonical calling surface (E-A4) — powers the per-surface KQL dashboard. */
+export declare const AUDIT_HEADER_HOST_NAME = "X-Audit-Host-Name";
+export declare const AUDIT_SOURCE_VALUE = "mcp";
+export interface CurrentToolNameRef {
+    current: string | null;
+}
+export interface AttachAuditHookOptions {
+    /**
+     * Resolved session auth identity (Phase 0 / E-A3). When present, the hook
+     * tags every outbound call with the auth mode and (if known) the install id
+     * so Platform's audit log can attribute the call to a user/install/surface.
+     * Static for the session, so captured once here rather than threaded per-call.
+     */
+    readonly auth?: SessionAuthContext;
+    /**
+     * Canonical calling surface (Phase 0 / E-A4). Emitted as X-Audit-Host-Name so
+     * Platform telemetry can pivot per-surface. Best-effort (see telemetry/hostName).
+     */
+    readonly hostName?: string;
+}
+export interface AttachAuditHookResult {
+    /** Dispose the hook (mainly for tests). */
+    readonly dispose: () => void;
+    /**
+     * Set the tool name to be attached to the NEXT outbound request(s). The
+     * dispatcher pairs every set with a clear (set name → invoke handler →
+     * clear name) so leakage between calls is impossible even when the SDK
+     * issues parallel sub-requests.
+     */
+    readonly setCurrentToolName: (name: string | null) => void;
+    /** Inspect the current ref — useful in tests; do not mutate externally. */
+    readonly ref: CurrentToolNameRef;
+}
+/**
+ * Register an `onRequest` hook on `client` that injects audit headers.
+ *
+ * Returns helpers the dispatcher (or tests) use to control the per-call tool
+ * name. Returning the ref itself lets unit tests assert isolation without
+ * resorting to Sinon spies.
+ */
+export declare function attachAuditHook(client: SolidCommerceClient, opts?: AttachAuditHookOptions): AttachAuditHookResult;
+//# sourceMappingURL=auditClient.d.ts.map

package/dist/audit/auditClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditClient.d.ts","sourceRoot":"","sources":["../../src/audit/auditClient.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAC1D,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAC5D;8EAC8E;AAC9E,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAC1D,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3D,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,sBAA2B,GAChC,qBAAqB,CAyCvB"}

package/dist/audit/auditClient.js

@@ -0,0 +1,93 @@
+// =============================================================================
+// src/audit/auditClient.ts
+// Wave: W6 — Stream C
+//
+// Wraps the @solidcommerce/sdk transport so every SDK call carries
+//   X-Audit-Source: mcp
+//   X-Audit-Tool-Name: <tool-name>
+//
+// Platform's AuditLogMiddleware (SC.Base.API.Common, extended in W6 Step 6)
+// reads these and persists them to dbo.audit_log.
+//
+// Design notes:
+//
+//  - The audit hook is a `client.use({ onRequest })` registration. We deliberately
+//    do NOT modify the SDK package; the SDK exposes a public hook system for
+//    this exact use case (see options.d.ts → ClientHooks).
+//
+//  - The current tool name is threaded via a closed-over ref-cell (a plain
+//    `{ current: string | null }` object). We rejected AsyncLocalStorage to
+//    keep this portable across server transports (stdio + Streamable HTTP) and to avoid
+//    the extra complexity. The dispatcher (server/dispatcher.ts) sets the ref
+//    *just before* invoking the tool's handler and clears it after — see
+//    `setCurrentToolName` returned from `attachAuditHook`.
+//
+//  - `X-Audit-Source: mcp` is ALWAYS injected. The CLI resource driver (W5)
+//    must not see this header — it ships a different audit hook. Keeping the
+//    hook scoped to *this* client (constructed in src/auth/apiKey.ts) ensures
+//    isolation by construction.
+//
+//  - The hook is non-throwing per the SDK contract (options.d.ts:60). If the
+//    headers are read-only somehow we silently no-op rather than blow up the
+//    request — audit data loss is preferable to losing the user's call.
+// =============================================================================
+export const AUDIT_HEADER_SOURCE = "X-Audit-Source";
+export const AUDIT_HEADER_TOOL_NAME = "X-Audit-Tool-Name";
+// Phase 0 / E-A3 + E-A4: identity + surface attribution on every audited call.
+export const AUDIT_HEADER_AUTH_MODE = "X-Audit-Auth-Mode";
+export const AUDIT_HEADER_INSTALL_ID = "X-Audit-Install-Id";
+/** Set when the bearer was forwarded WITHOUT a successful introspection
+ * (Auth outage / circuit open). Lets Platform audit flag unverified calls. */
+export const AUDIT_HEADER_AUTH_DEGRADED = "X-Audit-Auth-Degraded";
+/** Canonical calling surface (E-A4) — powers the per-surface KQL dashboard. */
+export const AUDIT_HEADER_HOST_NAME = "X-Audit-Host-Name";
+export const AUDIT_SOURCE_VALUE = "mcp";
+/**
+ * Register an `onRequest` hook on `client` that injects audit headers.
+ *
+ * Returns helpers the dispatcher (or tests) use to control the per-call tool
+ * name. Returning the ref itself lets unit tests assert isolation without
+ * resorting to Sinon spies.
+ */
+export function attachAuditHook(client, opts = {}) {
+    const ref = { current: null };
+    const auth = opts.auth;
+    const hostName = opts.hostName;
+    const dispose = client.use({
+        onRequest: ({ request }) => {
+            // The SDK's hook contract documents that request.headers is mutable;
+            // wrap defensively so a frozen header bag doesn't kill the call.
+            try {
+                request.headers.set(AUDIT_HEADER_SOURCE, AUDIT_SOURCE_VALUE);
+                const toolName = ref.current;
+                if (toolName !== null && toolName.length > 0) {
+                    request.headers.set(AUDIT_HEADER_TOOL_NAME, toolName);
+                }
+                if (hostName !== undefined && hostName.length > 0) {
+                    request.headers.set(AUDIT_HEADER_HOST_NAME, hostName);
+                }
+                if (auth) {
+                    request.headers.set(AUDIT_HEADER_AUTH_MODE, auth.mode);
+                    if (auth.installId !== undefined && auth.installId.length > 0) {
+                        request.headers.set(AUDIT_HEADER_INSTALL_ID, auth.installId);
+                    }
+                    if (auth.introspectionDegraded) {
+                        request.headers.set(AUDIT_HEADER_AUTH_DEGRADED, "true");
+                    }
+                }
+            }
+            catch {
+                // Audit data loss > losing the user's call. SDK swallows hook
+                // throws but we don't want to depend on that behavior.
+            }
+        },
+    });
+    return {
+        dispose,
+        setCurrentToolName: (name) => {
+            ref.current = name;
+        },
+        ref,
+    };
+}
+//# sourceMappingURL=auditClient.js.map

package/dist/audit/auditClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditClient.js","sourceRoot":"","sources":["../../src/audit/auditClient.ts"],"names":[],"mappings":"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"}

package/dist/auth/apiKey.d.ts

@@ -0,0 +1,44 @@
+import { SolidCommerceClient } from "@solidcommerce/sdk";
+export declare const DEFAULT_BASE_URL = "https://api.solidcommerce.com";
+export declare const ENV_API_KEY = "SOLIDCOMMERCE_API_KEY";
+export declare const ENV_BASE_URL = "SOLIDCOMMERCE_API_BASE_URL";
+export interface ApiKeySource {
+    readonly apiKey: string;
+}
+/**
+ * Read the API key from env. Throws an actionable error if missing — fail
+ * fast at boot, do NOT defer to the first tool call.
+ */
+export declare function loadApiKeyFromEnv(): ApiKeySource;
+/**
+ * Resolve the API base URL. Caller-provided override beats env beats default.
+ * We trim trailing slashes so that `${baseUrl}/v1/...` paths don't double-slash.
+ */
+export declare function resolveBaseUrl(override?: string): string;
+export interface BuildClientOptions {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    /** Inject for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Build a configured SolidCommerceClient with apiKey auth + base URL.
+ *
+ * Note: audit hooks are NOT attached here. The caller (index.ts) attaches
+ * them via `attachAuditHook(client)` so the ref-cell ownership stays at
+ * the dispatcher level.
+ */
+export declare function buildClient(opts?: BuildClientOptions): SolidCommerceClient;
+export interface BuildBearerClientOptions {
+    readonly baseUrl?: string;
+    /** Inject for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Build a SolidCommerceClient that forwards a per-user OAuth bearer token
+ * (Phase 0 / E-A3). Platform re-validates the token via its JWKS config on
+ * every call, so this client does not itself verify the token. Audit hooks are
+ * NOT attached here — the caller attaches them via `attachAuditHook(client)`.
+ */
+export declare function buildBearerClient(token: string, opts?: BuildBearerClientOptions): SolidCommerceClient;
+//# sourceMappingURL=apiKey.d.ts.map

package/dist/auth/apiKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiKey.d.ts","sourceRoot":"","sources":["../../src/auth/apiKey.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,gBAAgB,kCAAkC,CAAC;AAChE,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,YAAY,+BAA+B,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAUhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,mBAAmB,CAW9E;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CAcrB"}

package/dist/auth/apiKey.js

@@ -0,0 +1,80 @@
+// =============================================================================
+// src/auth/apiKey.ts
+// Wave: W6 — Stream C
+// Phase 0 / E-A3 — added buildBearerClient for per-user OAuth sessions.
+//
+// Resolves SOLIDCOMMERCE_API_KEY from env and builds a SolidCommerceClient.
+// Two auth modes now coexist on the same server:
+//   * apiKey  — service-to-service (stdio / Scotty / internal), env key.
+//   * bearer  — per-user OAuth token forwarded from a remote host (E-A3).
+//
+// Mirrors the W5 CLI sdk.ts factory pattern (auth resolution + base URL +
+// retry config) but simplified — no token refresh / keychain here; bearer
+// tokens are captured per session and Platform re-validates every call.
+// =============================================================================
+import { SolidCommerceClient } from "@solidcommerce/sdk";
+export const DEFAULT_BASE_URL = "https://api.solidcommerce.com";
+export const ENV_API_KEY = "SOLIDCOMMERCE_API_KEY";
+export const ENV_BASE_URL = "SOLIDCOMMERCE_API_BASE_URL";
+/**
+ * Read the API key from env. Throws an actionable error if missing — fail
+ * fast at boot, do NOT defer to the first tool call.
+ */
+export function loadApiKeyFromEnv() {
+    const key = process.env[ENV_API_KEY]?.trim();
+    if (!key || key.length === 0) {
+        throw new Error(`${ENV_API_KEY} env var is required. Get one at ` +
+            "https://app.solidcommerce.com/settings/api-keys, then set it before " +
+            "starting the MCP server (e.g., in your Claude Desktop mcpServers config).");
+    }
+    return { apiKey: key };
+}
+/**
+ * Resolve the API base URL. Caller-provided override beats env beats default.
+ * We trim trailing slashes so that `${baseUrl}/v1/...` paths don't double-slash.
+ */
+export function resolveBaseUrl(override) {
+    const raw = (override ?? process.env[ENV_BASE_URL] ?? DEFAULT_BASE_URL).trim();
+    return raw.replace(/\/+$/, "");
+}
+/**
+ * Build a configured SolidCommerceClient with apiKey auth + base URL.
+ *
+ * Note: audit hooks are NOT attached here. The caller (index.ts) attaches
+ * them via `attachAuditHook(client)` so the ref-cell ownership stays at
+ * the dispatcher level.
+ */
+export function buildClient(opts = {}) {
+    const apiKey = opts.apiKey ?? loadApiKeyFromEnv().apiKey;
+    const baseUrl = resolveBaseUrl(opts.baseUrl);
+    const clientOptions = {
+        baseUrl,
+        auth: { kind: "apiKey", apiKey },
+    };
+    if (opts.fetchImpl) {
+        clientOptions.fetch = opts.fetchImpl;
+    }
+    return new SolidCommerceClient(clientOptions);
+}
+/**
+ * Build a SolidCommerceClient that forwards a per-user OAuth bearer token
+ * (Phase 0 / E-A3). Platform re-validates the token via its JWKS config on
+ * every call, so this client does not itself verify the token. Audit hooks are
+ * NOT attached here — the caller attaches them via `attachAuditHook(client)`.
+ */
+export function buildBearerClient(token, opts = {}) {
+    const trimmed = token.trim();
+    if (trimmed.length === 0) {
+        throw new Error("buildBearerClient: token must be a non-empty string.");
+    }
+    const baseUrl = resolveBaseUrl(opts.baseUrl);
+    const clientOptions = {
+        baseUrl,
+        auth: { kind: "bearer", token: trimmed },
+    };
+    if (opts.fetchImpl) {
+        clientOptions.fetch = opts.fetchImpl;
+    }
+    return new SolidCommerceClient(clientOptions);
+}
+//# sourceMappingURL=apiKey.js.map

package/dist/auth/apiKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiKey.js","sourceRoot":"","sources":["../../src/auth/apiKey.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qBAAqB;AACrB,sBAAsB;AACtB,wEAAwE;AACxE,EAAE;AACF,4EAA4E;AAC5E,iDAAiD;AACjD,yEAAyE;AACzE,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,gFAAgF;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAMzD;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,mCAAmC;YAC/C,sEAAsE;YACtE,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/E,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B,EAAE;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC,MAAM,CAAC;IACzD,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,aAAa,GAAyD;QAC1E,OAAO;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE;KACjC,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAC;AAChD,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,OAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,aAAa,GAAyD;QAC1E,OAAO;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE;KACzC,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAC;AAChD,CAAC"}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,108 @@
+export declare const ENV_OAUTH_ENABLED = "SC_MCP_OAUTH_ENABLED";
+export declare const ENV_INTROSPECT_URL = "SC_AUTH_INTROSPECT_URL";
+export declare const ENV_MCP_CLIENT_ID = "SC_MCP_CLIENT_ID";
+export declare const ENV_MCP_CLIENT_SECRET = "SC_MCP_CLIENT_SECRET";
+export interface OAuthConfig {
+    /** When false, the server is apiKey-only and ignores bearer headers. */
+    readonly enabled: boolean;
+    readonly introspectUrl: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    /** Per-introspection-call network timeout. */
+    readonly timeoutMs: number;
+    /** Max lifetime for a cached ACTIVE result (capped under token `exp`). */
+    readonly positiveTtlMs: number;
+    /** Lifetime for a cached INACTIVE result (short — revocation re-issue). */
+    readonly negativeTtlMs: number;
+    /** Clock skew subtracted from token `exp` when computing positive TTL. */
+    readonly skewMs: number;
+    /** Consecutive failures before the circuit opens. */
+    readonly circuitThreshold: number;
+    /** How long the circuit stays open before a probe is allowed. */
+    readonly circuitCooldownMs: number;
+    /** Hard ceiling on cache entries (bounded memory). */
+    readonly maxCacheEntries: number;
+}
+/** Default MCP confidential client id — matches OpenIddictSeeder.McpServerClientId. */
+export declare const DEFAULT_MCP_CLIENT_ID = "sc-mcp-server";
+/**
+ * Load OAuth config from env. `enabled` defaults to ON when both an introspect
+ * URL and a client secret are present, so a correctly-provisioned deployment
+ * "just works"; an operator can force it on/off with SC_MCP_OAUTH_ENABLED.
+ */
+export declare function loadOAuthConfigFromEnv(env?: NodeJS.ProcessEnv): OAuthConfig;
+export type AuthMode = "oauth" | "apiKey";
+export interface SessionAuthContext {
+    readonly mode: AuthMode;
+    /** Bearer token to forward to Platform (oauth mode only). */
+    readonly token?: string;
+    readonly companyId?: string;
+    readonly installId?: string;
+    readonly subject?: string;
+    readonly scopes: ReadonlyArray<string>;
+    /** Token `exp` (epoch seconds), when known. */
+    readonly expiresAtEpoch?: number;
+    /** True when forwarded unverified (Auth outage). Platform is authority. */
+    readonly introspectionDegraded: boolean;
+}
+/** Resolution outcome: either an accepted session context, or a rejection that
+ *  the transport turns into a 401 (we never silently downgrade a bad bearer). */
+export type AuthResolution = {
+    readonly ok: true;
+    readonly context: SessionAuthContext;
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly error: string;
+};
+type IntrospectOutcome = {
+    readonly kind: "active";
+    readonly claims: IntrospectionClaims;
+} | {
+    readonly kind: "inactive";
+} | {
+    readonly kind: "degraded";
+    readonly reason: string;
+};
+export interface IntrospectionClaims {
+    readonly companyId?: string;
+    readonly installId?: string;
+    readonly subject?: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly expiresAtEpoch?: number;
+}
+export interface Introspector {
+    introspect(token: string): Promise<IntrospectOutcome>;
+    /** Test/diagnostics: current circuit state. */
+    readonly isCircuitOpen: () => boolean;
+}
+export interface IntrospectorDeps {
+    /** Injectable for tests. Defaults to global fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /** Injectable clock (ms epoch). Defaults to Date.now. */
+    readonly now?: () => number;
+}
+/**
+ * Build an introspector. Holds the cache + circuit state for the process; one
+ * instance is shared across all sessions (cache hits make repeated initialize
+ * calls for the same token cheap).
+ */
+export declare function createIntrospector(config: OAuthConfig, deps?: IntrospectorDeps): Introspector;
+/** Extract a bearer token, or undefined if the header is absent / not Bearer. */
+export declare function parseBearer(authorizationHeader: string | undefined): string | undefined;
+export interface AuthResolverDeps {
+    readonly config: OAuthConfig;
+    readonly introspector: Introspector;
+    /** Whether an env API key is available for the no-bearer fallback. */
+    readonly apiKeyAvailable: boolean;
+}
+export interface SessionAuthResolver {
+    resolve(authorizationHeader: string | undefined): Promise<AuthResolution>;
+}
+/**
+ * Build the resolver used by the Streamable HTTP transport at `initialize`.
+ * See the resilience matrix in this file's header for the full decision table.
+ */
+export declare function createSessionAuthResolver(deps: AuthResolverDeps): SessionAuthResolver;
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"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"}