@solidcommerce/mcp-server 2.0.0-alpha.0

package/dist/auth/oauth.js

@@ -0,0 +1,300 @@
+// =============================================================================
+// src/auth/oauth.ts
+// Phase 0 / Item E-A3 — Per-user OAuth for the MCP Server.
+//
+// Remote hosts (Claude UI, ChatGPT, Gemini, M365 Copilot, Grok) send a per-user
+// `Authorization: Bearer <token>` issued by SC.Base.Auth. This module:
+//
+//   1. Parses the bearer token from the inbound header.
+//   2. Introspects it against SC.Base.Auth `/oauth/introspect` (RFC 7662)
+//      using the MCP confidential client (sc-mcp-server) — to FAST-FAIL invalid
+//      tokens and to extract claims (company_id, scope, install_id) for audit,
+//      per-surface telemetry (E-A4) and per-install rate-limit (E-A5).
+//   3. Resolves a SessionAuthContext the per-session server factory uses to
+//      build a bearer-auth SDK client.
+//
+// Resilience / HA design — the load-bearing decision:
+//   The bearer token is ALSO independently validated by Platform (it has the
+//   JWKS / Authority config). So our introspection is an OPTIMISATION, not the
+//   sole gate. That lets introspection FAIL-OPEN under an Auth outage:
+//
+//     * Auth reachable, token active   → verified oauth context.
+//     * Auth reachable, token inactive → HARD REJECT (401). An explicitly bad
+//       token must never fall back to the env API key (privilege escalation).
+//     * Auth unreachable / circuit open → DEGRADED oauth context: forward the
+//       token to Platform, which is the authority. Availability preserved.
+//     * No Authorization header        → apiKey context (stdio / Scotty /
+//       internal). Never introspected.
+//
+// Defensive layers: per-call timeout, positive+negative response cache keyed by
+// a SHA-256 of the token (never the raw token), and a circuit breaker so a down
+// Auth server is not hammered on every session.
+// =============================================================================
+import { createHash } from "node:crypto";
+// -----------------------------------------------------------------------------
+// Config
+// -----------------------------------------------------------------------------
+export const ENV_OAUTH_ENABLED = "SC_MCP_OAUTH_ENABLED";
+export const ENV_INTROSPECT_URL = "SC_AUTH_INTROSPECT_URL";
+export const ENV_MCP_CLIENT_ID = "SC_MCP_CLIENT_ID";
+export const ENV_MCP_CLIENT_SECRET = "SC_MCP_CLIENT_SECRET";
+const DEFAULTS = {
+    timeoutMs: 3_000,
+    // Cap a cached ACTIVE result at 60s. JWTs are stateless — Platform validates
+    // signature + `exp` via JWKS but does NOT check mid-life revocation, so THIS
+    // cache is the revocation-enforcement point for the fast path. 60s matches the
+    // documented revocation SLA (docs/runbooks/token-revocation.md, PRD §7 NFR).
+    positiveTtlMs: 60_000,
+    negativeTtlMs: 10_000,
+    skewMs: 60_000,
+    circuitThreshold: 5,
+    circuitCooldownMs: 30_000,
+    maxCacheEntries: 5_000,
+};
+/** Default MCP confidential client id — matches OpenIddictSeeder.McpServerClientId. */
+export 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 function loadOAuthConfigFromEnv(env = process.env) {
+    const introspectUrl = (env[ENV_INTROSPECT_URL] ?? "").trim();
+    const clientId = (env[ENV_MCP_CLIENT_ID] ?? DEFAULT_MCP_CLIENT_ID).trim();
+    const clientSecret = (env[ENV_MCP_CLIENT_SECRET] ?? "").trim();
+    const explicit = env[ENV_OAUTH_ENABLED]?.trim().toLowerCase();
+    const enabled = explicit === "true"
+        ? true
+        : explicit === "false"
+            ? false
+            : introspectUrl.length > 0 && clientSecret.length > 0;
+    return {
+        enabled,
+        introspectUrl,
+        clientId,
+        clientSecret,
+        ...DEFAULTS,
+    };
+}
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function parseClaims(body) {
+    const scopes = typeof body.scope === "string" && body.scope.length > 0
+        ? body.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    const companyId = body.company_id === undefined || body.company_id === null
+        ? undefined
+        : String(body.company_id);
+    return {
+        ...(companyId !== undefined ? { companyId } : {}),
+        ...(body.install_id ? { installId: body.install_id } : {}),
+        ...(body.sub ? { subject: body.sub } : {}),
+        ...(typeof body.exp === "number" ? { expiresAtEpoch: body.exp } : {}),
+        scopes,
+    };
+}
+/**
+ * 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 function createIntrospector(config, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const now = deps.now ?? Date.now;
+    // Bounded, insertion-ordered cache (Map preserves insertion order → cheap LRU
+    // eviction by deleting the oldest key).
+    const cache = new Map();
+    // Circuit breaker.
+    let consecutiveFailures = 0;
+    let openUntilMs = 0;
+    const isCircuitOpen = () => now() < openUntilMs;
+    const recordSuccess = () => {
+        consecutiveFailures = 0;
+        openUntilMs = 0;
+    };
+    const recordFailure = () => {
+        consecutiveFailures += 1;
+        if (consecutiveFailures >= config.circuitThreshold) {
+            const wasOpen = now() < openUntilMs;
+            openUntilMs = now() + config.circuitCooldownMs;
+            if (!wasOpen) {
+                // Log only the closed→open transition (not every request) so a
+                // misconfigured client secret / Auth outage is loud but not noisy.
+                console.error(`[mcp-server] OAuth introspection circuit OPEN after ` +
+                    `${consecutiveFailures} consecutive failures; failing open ` +
+                    `(forwarding bearer tokens to Platform, which re-validates) for ` +
+                    `${config.circuitCooldownMs}ms.`);
+            }
+        }
+    };
+    const cacheGet = (key) => {
+        const entry = cache.get(key);
+        if (!entry)
+            return undefined;
+        if (now() >= entry.expiresAtMs) {
+            cache.delete(key);
+            return undefined;
+        }
+        return entry.outcome;
+    };
+    const cacheSet = (key, outcome, ttlMs) => {
+        if (ttlMs <= 0)
+            return;
+        // Evict oldest if at capacity.
+        if (cache.size >= config.maxCacheEntries) {
+            const oldest = cache.keys().next().value;
+            if (oldest !== undefined)
+                cache.delete(oldest);
+        }
+        cache.set(key, { outcome, expiresAtMs: now() + ttlMs });
+    };
+    const positiveTtl = (claims) => {
+        if (claims.expiresAtEpoch === undefined)
+            return config.positiveTtlMs;
+        const untilExpMs = claims.expiresAtEpoch * 1000 - now() - config.skewMs;
+        return Math.max(0, Math.min(config.positiveTtlMs, untilExpMs));
+    };
+    const callIntrospectionEndpoint = async (token) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+        try {
+            const basic = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+            const res = await fetchImpl(config.introspectUrl, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/x-www-form-urlencoded",
+                    accept: "application/json",
+                    authorization: `Basic ${basic}`,
+                },
+                body: new URLSearchParams({
+                    token,
+                    token_type_hint: "access_token",
+                }).toString(),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                // 5xx / 401 from the introspection endpoint itself = our problem, not
+                // the user's. Degrade (Platform is authority), count toward the circuit.
+                recordFailure();
+                return { kind: "degraded", reason: `introspection HTTP ${res.status}` };
+            }
+            const body = (await res.json());
+            recordSuccess();
+            if (body.active === true) {
+                return { kind: "active", claims: parseClaims(body) };
+            }
+            return { kind: "inactive" };
+        }
+        catch (err) {
+            // Network error / timeout / abort → degrade + circuit.
+            recordFailure();
+            const reason = err instanceof Error ? err.message : String(err);
+            return { kind: "degraded", reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const introspect = async (token) => {
+        const key = sha256Hex(token);
+        const cached = cacheGet(key);
+        if (cached)
+            return cached;
+        // Circuit open → skip the network entirely, fail-open as degraded.
+        if (isCircuitOpen()) {
+            return { kind: "degraded", reason: "circuit open" };
+        }
+        const outcome = await callIntrospectionEndpoint(token);
+        // Cache active (TTL bounded by exp) and inactive (short TTL). Degraded is
+        // NOT cached — we want to retry as soon as the circuit allows.
+        if (outcome.kind === "active") {
+            cacheSet(key, outcome, positiveTtl(outcome.claims));
+        }
+        else if (outcome.kind === "inactive") {
+            cacheSet(key, outcome, config.negativeTtlMs);
+        }
+        return outcome;
+    };
+    return { introspect, isCircuitOpen };
+}
+// -----------------------------------------------------------------------------
+// Session auth resolver — maps an inbound Authorization header to a resolution
+// -----------------------------------------------------------------------------
+const BEARER_RE = /^Bearer\s+(.+)$/i;
+/** Extract a bearer token, or undefined if the header is absent / not Bearer. */
+export function parseBearer(authorizationHeader) {
+    if (!authorizationHeader)
+        return undefined;
+    const m = BEARER_RE.exec(authorizationHeader.trim());
+    const token = m?.[1]?.trim();
+    return token && token.length > 0 ? token : undefined;
+}
+/**
+ * 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 function createSessionAuthResolver(deps) {
+    const { config, introspector, apiKeyAvailable } = deps;
+    const apiKeyContext = () => ({
+        mode: "apiKey",
+        scopes: [],
+        introspectionDegraded: false,
+    });
+    const resolve = async (authorizationHeader) => {
+        const token = parseBearer(authorizationHeader);
+        // No bearer → service-to-service / stdio path.
+        if (!token) {
+            if (apiKeyAvailable)
+                return { ok: true, context: apiKeyContext() };
+            return { ok: false, status: 401, error: "No credentials: provide a Bearer token or API key." };
+        }
+        // Bearer present but OAuth disabled by config: we can't introspect, but the
+        // token may still be valid to Platform. Forward it, degraded, rather than
+        // silently using the env key.
+        if (!config.enabled) {
+            return {
+                ok: true,
+                context: {
+                    mode: "oauth",
+                    token,
+                    scopes: [],
+                    introspectionDegraded: true,
+                },
+            };
+        }
+        const outcome = await introspector.introspect(token);
+        if (outcome.kind === "active") {
+            const c = outcome.claims;
+            return {
+                ok: true,
+                context: {
+                    mode: "oauth",
+                    token,
+                    ...(c.companyId !== undefined ? { companyId: c.companyId } : {}),
+                    ...(c.installId !== undefined ? { installId: c.installId } : {}),
+                    ...(c.subject !== undefined ? { subject: c.subject } : {}),
+                    ...(c.expiresAtEpoch !== undefined ? { expiresAtEpoch: c.expiresAtEpoch } : {}),
+                    scopes: c.scopes,
+                    introspectionDegraded: false,
+                },
+            };
+        }
+        if (outcome.kind === "inactive") {
+            // HARD reject — never fall back to the env key for a bad bearer.
+            return { ok: false, status: 401, error: "Token is inactive or expired." };
+        }
+        // Degraded: Auth unreachable / circuit open. Forward to Platform (authority).
+        return {
+            ok: true,
+            context: {
+                mode: "oauth",
+                token,
+                scopes: [],
+                introspectionDegraded: true,
+            },
+        };
+    };
+    return { resolve };
+}
+//# sourceMappingURL=oauth.js.map

package/dist/auth/oauth.js.map

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

package/dist/generator/fromOpenApi.d.ts

@@ -0,0 +1,54 @@
+import { type HttpMethodLc } from "./scopeInference.js";
+export type Tier = "tier1" | "tier2" | "tier3";
+export interface FoundationTool {
+    /** Stable MCP tool name, e.g. `catalog_products_list`. */
+    readonly name: string;
+    /** One-sentence description (from operation.description / .summary). */
+    readonly description: string;
+    /** Single canonical scope string (inferred or from x-required-scope*). */
+    readonly required_scope: string;
+    /** Source code for the Zod input schema (top-level z.object({...})). */
+    readonly inputSchemaSource: string;
+    /** HTTP method, uppercase — matches openapi-fetch's GET/POST/... method names. */
+    readonly httpMethod: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** Original OpenAPI path template (with {param} placeholders). */
+    readonly path: string;
+    /** Synthesized identifier (since W4 snapshot does not populate operationId). */
+    readonly operationId: string;
+    /** Which heuristic tier picked this tool — emitted as a code comment. */
+    readonly tier: Tier;
+    /** True if the operation declares a requestBody. */
+    readonly hasBody: boolean;
+    /** Path parameter names, declared order — drives runtime arg packing. */
+    readonly pathParamNames: ReadonlyArray<string>;
+    /** Query parameter names. */
+    readonly queryParamNames: ReadonlyArray<string>;
+}
+/** Hard cap from the wave brief — keeps us under Claude's tool token budget. */
+export declare const MAX_FOUNDATION_TOOLS = 40;
+/**
+ * Synthesize a stable MCP tool name from a (path, method) operation.
+ * Why we don't use operationId: the W4 frozen snapshot omits operationId
+ * everywhere — sampled 238/238 ops in vendor/openapi.snapshot.json.
+ */
+export declare function synthesizeToolName(path: string, method: HttpMethodLc): string;
+export interface GenerateOptions {
+    /** Override the snapshot path (tests). */
+    readonly snapshotPath?: string;
+    /** Override the heuristic cap (tests). */
+    readonly maxTools?: number;
+}
+/**
+ * Pure entry: read snapshot, run heuristic, return FoundationTool[].
+ * Does NOT touch the filesystem under src/tools/foundation/.
+ */
+export declare function generate(options?: GenerateOptions): FoundationTool[];
+/**
+ * Write tool files + index to disk. Idempotent: clears the output directory
+ * first so stale tools from previous runs don't linger.
+ *
+ * Returns the list of FoundationTool produced, identical to what `generate()`
+ * would have returned for the same options.
+ */
+export declare function regenerate(options?: GenerateOptions): FoundationTool[];
+//# sourceMappingURL=fromOpenApi.d.ts.map

package/dist/generator/fromOpenApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromOpenApi.d.ts","sourceRoot":"","sources":["../../src/generator/fromOpenApi.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAM9E,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjE,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C,6BAA6B;IAC7B,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACjD;AAgED,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAmCvC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAY7E;AAiED,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,EAAE,CAsDxE;AA+LD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,EAAE,CAa1E"}