webcake-storefront-mcp 1.0.3 → 1.1.1

package/dist/http.js

@@ -1,13 +1,34 @@
 // Remote MCP over Streamable-HTTP. Each client session carries its own credentials,
 // supplied per-request via headers (x-webcake-jwt / x-webcake-site-id / x-webcake-api-url)
 // or query params (?jwt=&site_id=&api_url=) for clients that can't set custom headers.
+//
+// Also serves: a marketing landing page at /, /privacy, /terms, /favicon.ico,
+// /favicon.svg, /health, and a full OAuth 2.1 flow so the claude.ai connector can
+// authenticate. See src/auth/oauth-server.ts for the OAuth AS implementation.
 import { createServer as createHttpServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "./server.js";
-import { makeApi } from "./config.js";
+import { makeApi, resolveEnv, ENVIRONMENTS, DEFAULT_ENV } from "./config.js";
+import { landingHtml, faviconSvg, ogImageSvg, normalizeLang } from "./web-guide.js";
+import { privacyHtml, termsHtml } from "./legal.js";
+import { registerClient, startAuthorize, completeAuthorize, exchangeToken, resolveAccessToken, revokeToken, authServerMetadata, protectedResourceMetadata, } from "./auth/oauth-server.js";
 const MCP_PATH = "/mcp";
+// OAuth 2.1 endpoints.
+const WELL_KNOWN_PR = "/.well-known/oauth-protected-resource";
+const WELL_KNOWN_AS = "/.well-known/oauth-authorization-server";
+const OAUTH_REGISTER = "/register";
+const OAUTH_AUTHORIZE = "/authorize";
+const OAUTH_CALLBACK = "/oauth/callback";
+const OAUTH_TOKEN = "/token";
+const OAUTH_REVOKE = "/revoke";
+// OAuth enforcement is ON by default: a request with NO credential gets a
+// 401 + WWW-Authenticate so Claude/ChatGPT kick off the OAuth flow.
+// Opt out with WEBCAKE_OAUTH=0 (or false/no/off).
+const OAUTH_ENFORCED = !/^(0|false|no|off)$/i.test(process.env.WEBCAKE_OAUTH ?? "");
+// Social/search crawlers fetch the root with Accept: */* but should still get HTML.
+const BOT_UA = /facebookexternalhit|facebot|twitterbot|linkedinbot|slackbot|slack-imgproxy|telegrambot|whatsapp|discordbot|pinterest|redditbot|googlebot|bingbot|applebot|yandexbot|baiduspider|embedly|quora link preview|outbrain|vkshare|w3c_validator|skypeuripreview|zalo/i;
 const QUERY_TO_HEADER = {
     jwt: "x-webcake-jwt",
     token: "x-webcake-jwt",
@@ -28,8 +49,10 @@ function applyQueryAuth(req) {
     const params = new URLSearchParams((req.url ?? "").slice(q + 1));
     for (const [param, head] of Object.entries(QUERY_TO_HEADER)) {
         const value = params.get(param);
-        if (value && req.headers[head] == null)
+        if (value && req.headers[head] == null) {
             req.headers[head] = value;
+            req.rawHeaders.push(head, value);
+        }
     }
 }
 function apiFromRequest(req) {
@@ -59,23 +82,285 @@ function readBody(req) {
         req.on("error", reject);
     });
 }
-function rpcError(res, status, message) {
+async function readRawBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+function parseBodyParams(raw, contentType) {
+    if (!raw)
+        return {};
+    if (contentType.includes("application/json")) {
+        try {
+            const o = JSON.parse(raw);
+            return o && typeof o === "object" ? o : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    const out = {};
+    for (const [k, v] of new URLSearchParams(raw))
+        out[k] = v;
+    return out;
+}
+function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" });
-    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }));
+    res.end(JSON.stringify(body));
+}
+function rpcError(res, status, message) {
+    sendJson(res, status, { jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+}
+function oauthError(res, status, error, description) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify({ error, error_description: description }));
+}
+function htmlError(res, status, message) {
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
+    res.end(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;padding:40px;max-width:520px;margin:auto"><h2>WebCake Storefront MCP</h2><p>${message}</p></body>`);
+}
+/** The public origin of this server, honouring reverse-proxy headers. */
+function publicBase(req) {
+    const fwdHost = req.headers["x-forwarded-host"];
+    const host = (Array.isArray(fwdHost) ? fwdHost[0] : fwdHost) || req.headers.host || "localhost";
+    const fwdProto = req.headers["x-forwarded-proto"];
+    const isLocal = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(host);
+    const proto = (Array.isArray(fwdProto) ? fwdProto[0] : fwdProto)?.split(",")[0] || (isLocal ? "http" : "https");
+    return `${proto}://${host}`;
+}
+/** The storefront consent page URL — /mcp-storefront on the builder app. */
+function storefrontConsentUrl() {
+    const preset = resolveEnv(process.env.WEBCAKE_ENV) ?? ENVIRONMENTS[DEFAULT_ENV];
+    const appUrl = (process.env.WEBCAKE_APP_URL || preset.appUrl).replace(/\/$/, "");
+    return `${appUrl}/mcp-storefront`;
+}
+/** Extract the Bearer token from the Authorization header, if any. */
+function bearerFrom(req) {
+    const auth = req.headers["authorization"];
+    const v = Array.isArray(auth) ? auth[0] : auth;
+    if (!v || !/^Bearer\s+/i.test(v))
+        return undefined;
+    return v.replace(/^Bearer\s+/i, "").trim() || undefined;
+}
+/**
+ * Handle every OAuth 2.1 endpoint. Returns true when the request was handled.
+ *
+ * KEY ADAPTATION vs. landing-mcp: the credential is a PAIR { jwt, wsid }.
+ * The /oauth/callback receives both `token` (jwt) and `wsid` from the consent
+ * page redirect_uri. Both are stored and later injected as x-webcake-jwt AND
+ * x-webcake-session-id headers onto /mcp requests.
+ */
+async function handleOAuth(req, res, path) {
+    const issuer = publicBase(req);
+    // ---- Metadata ----
+    if (req.method === "GET" && path === WELL_KNOWN_PR) {
+        res.writeHead(200, { "content-type": "application/json", "access-control-allow-origin": "*" });
+        res.end(JSON.stringify(protectedResourceMetadata(`${issuer}${MCP_PATH}`, issuer)));
+        return true;
+    }
+    if (req.method === "GET" && path === WELL_KNOWN_AS) {
+        res.writeHead(200, { "content-type": "application/json", "access-control-allow-origin": "*" });
+        res.end(JSON.stringify(authServerMetadata(issuer)));
+        return true;
+    }
+    // ---- Dynamic Client Registration ----
+    if (path === OAUTH_REGISTER) {
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, { "access-control-allow-origin": "*", "access-control-allow-headers": "*", "access-control-allow-methods": "POST,OPTIONS" });
+            res.end();
+            return true;
+        }
+        if (req.method !== "POST") {
+            oauthError(res, 405, "invalid_request", "Use POST.");
+            return true;
+        }
+        const raw = await readRawBody(req);
+        const body = parseBodyParams(raw, String(req.headers["content-type"] ?? ""));
+        const result = await registerClient(body);
+        if (!result.ok) {
+            oauthError(res, 400, result.error, result.error_description);
+            return true;
+        }
+        res.writeHead(201, { "content-type": "application/json", "access-control-allow-origin": "*", "cache-control": "no-store" });
+        res.end(JSON.stringify({
+            client_id: result.client.client_id,
+            client_id_issued_at: Math.floor(result.client.created_at / 1000),
+            redirect_uris: result.client.redirect_uris,
+            token_endpoint_auth_method: "none",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+        }));
+        return true;
+    }
+    // ---- Authorize: validate + redirect to storefront consent page ----
+    if (req.method === "GET" && path === OAUTH_AUTHORIZE) {
+        const sp = new URL(req.url ?? "/", "http://x").searchParams;
+        const result = await startAuthorize({
+            client_id: sp.get("client_id"),
+            redirect_uri: sp.get("redirect_uri"),
+            response_type: sp.get("response_type"),
+            code_challenge: sp.get("code_challenge"),
+            code_challenge_method: sp.get("code_challenge_method"),
+            state: sp.get("state"),
+            scope: sp.get("scope"),
+        });
+        if (!result.ok) {
+            if (result.redirectable) {
+                const r = new URL(sp.get("redirect_uri"));
+                r.searchParams.set("error", result.error);
+                r.searchParams.set("error_description", result.error_description);
+                const st = sp.get("state");
+                if (st)
+                    r.searchParams.set("state", st);
+                res.writeHead(302, { location: r.toString() });
+                res.end();
+                return true;
+            }
+            htmlError(res, 400, result.error_description);
+            return true;
+        }
+        // Build the consent URL: /mcp-storefront?redirect_uri=<callback>&state=<internalState>
+        // The SPA will redirect back to callback with ?token=<jwt>&wsid=<wsid>&state=<internalState>
+        const callback = `${issuer}${OAUTH_CALLBACK}`;
+        const consentBase = storefrontConsentUrl();
+        const loginUrl = `${consentBase}?redirect_uri=${encodeURIComponent(callback)}&state=${encodeURIComponent(result.internalState)}`;
+        res.writeHead(302, { location: loginUrl });
+        res.end();
+        return true;
+    }
+    // ---- Callback: SPA sent back token (jwt) + wsid + state ----
+    if (req.method === "GET" && path === OAUTH_CALLBACK) {
+        const sp = new URL(req.url ?? "/", "http://x").searchParams;
+        // Accept both 'token' and 'jwt' from the SPA (login.ts uses both aliases).
+        const jwt = sp.get("token") || sp.get("jwt");
+        const wsid = sp.get("wsid") || sp.get("session_id") || "";
+        const done = await completeAuthorize(sp.get("state"), jwt, wsid);
+        if (!done.ok) {
+            htmlError(res, 400, done.error_description);
+            return true;
+        }
+        const r = new URL(done.redirectUri);
+        r.searchParams.set("code", done.code);
+        if (done.state)
+            r.searchParams.set("state", done.state);
+        res.writeHead(302, { location: r.toString() });
+        res.end();
+        return true;
+    }
+    // ---- Token ----
+    if (path === OAUTH_TOKEN) {
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, { "access-control-allow-origin": "*", "access-control-allow-headers": "*", "access-control-allow-methods": "POST,OPTIONS" });
+            res.end();
+            return true;
+        }
+        if (req.method !== "POST") {
+            oauthError(res, 405, "invalid_request", "Use POST.");
+            return true;
+        }
+        const raw = await readRawBody(req);
+        const body = parseBodyParams(raw, String(req.headers["content-type"] ?? ""));
+        const result = await exchangeToken(body);
+        if (!result.ok) {
+            oauthError(res, result.status, result.error, result.error_description);
+            return true;
+        }
+        res.writeHead(200, { "content-type": "application/json", "access-control-allow-origin": "*", "cache-control": "no-store" });
+        res.end(JSON.stringify(result.body));
+        return true;
+    }
+    // ---- Revoke ----
+    if (path === OAUTH_REVOKE) {
+        if (req.method !== "POST") {
+            oauthError(res, 405, "invalid_request", "Use POST.");
+            return true;
+        }
+        const raw = await readRawBody(req);
+        const body = parseBodyParams(raw, String(req.headers["content-type"] ?? ""));
+        revokeToken(body.token);
+        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+        res.end("{}");
+        return true;
+    }
+    return false;
 }
 export async function startHttpServer(port) {
     const transports = new Map();
     const httpServer = createHttpServer(async (req, res) => {
         const path = (req.url ?? "").split("?")[0];
-        if (path === "/health") {
-            res.writeHead(200, { "content-type": "application/json" });
-            res.end(JSON.stringify({ ok: true }));
+        // ---- Favicon / brand icon ----
+        if (req.method === "GET" && (path === "/favicon.ico" || path === "/favicon.svg")) {
+            res.writeHead(200, { "content-type": "image/svg+xml", "cache-control": "public, max-age=86400" });
+            res.end(faviconSvg());
+            return;
+        }
+        // ---- OG social card ----
+        if (req.method === "GET" && path === "/og.svg") {
+            res.writeHead(200, { "content-type": "image/svg+xml", "cache-control": "public, max-age=86400" });
+            res.end(ogImageSvg());
+            return;
+        }
+        // ---- Legal pages ----
+        if (req.method === "GET" && (path === "/privacy" || path === "/privacy-policy")) {
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "public, max-age=3600" });
+            res.end(privacyHtml());
+            return;
+        }
+        if (req.method === "GET" && (path === "/terms" || path === "/tos")) {
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "public, max-age=3600" });
+            res.end(termsHtml());
             return;
         }
+        // ---- Health + landing page ----
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            if (path === "/") {
+                const accept = String(req.headers["accept"] ?? "");
+                const ua = String(req.headers["user-agent"] ?? "");
+                if (accept.includes("text/html") || BOT_UA.test(ua)) {
+                    const lang = normalizeLang(new URL(req.url ?? "/", "http://x").searchParams.get("lang"));
+                    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                    res.end(landingHtml(publicBase(req), lang));
+                    return;
+                }
+            }
+            sendJson(res, 200, { ok: true, server: "webcake-storefront", transport: "streamable-http", endpoint: MCP_PATH });
+            return;
+        }
+        // ---- OAuth 2.1 endpoints (always served) ----
+        if (await handleOAuth(req, res, path))
+            return;
+        // ---- 404 for anything other than /mcp ----
         if (path !== MCP_PATH) {
-            return rpcError(res, 404, `Not found. Send MCP requests to ${MCP_PATH}.`);
+            rpcError(res, 404, `Not found. Send MCP requests to ${MCP_PATH}.`);
+            return;
         }
+        // ---- /mcp handling ----
+        // Accept credentials via query params for clients that can't set headers.
         applyQueryAuth(req);
+        // Resolve an OAuth Bearer access token to { jwt, wsid } and inject both headers
+        // so apiFromRequest picks them up — existing header/query paths remain untouched.
+        const bearer = bearerFrom(req);
+        const oauthCred = await resolveAccessToken(bearer);
+        if (oauthCred) {
+            if (req.headers["x-webcake-jwt"] == null) {
+                req.headers["x-webcake-jwt"] = oauthCred.jwt;
+                req.rawHeaders.push("x-webcake-jwt", oauthCred.jwt);
+            }
+            if (oauthCred.wsid && req.headers["x-webcake-session-id"] == null) {
+                req.headers["x-webcake-session-id"] = oauthCred.wsid;
+                req.rawHeaders.push("x-webcake-session-id", oauthCred.wsid);
+            }
+        }
+        // Enforce OAuth when enabled: a request with no recognised credential gets 401.
+        if (OAUTH_ENFORCED && !oauthCred && req.headers["x-webcake-jwt"] == null) {
+            res.writeHead(401, {
+                "www-authenticate": `Bearer resource_metadata="${publicBase(req)}${WELL_KNOWN_PR}"`,
+                "content-type": "application/json",
+            });
+            res.end(JSON.stringify({ error: "invalid_token", error_description: "Authentication required — connect via OAuth." }));
+            return;
+        }
         const sidHeader = header(req, "mcp-session-id");
         try {
             // Reuse an existing session.
@@ -105,9 +390,10 @@ export async function startHttpServer(port) {
                     await transport.handleRequest(req, res, body);
                     return;
                 }
-                return rpcError(res, 400, "Bad Request: send an initialize request first (no valid mcp-session-id).");
+                rpcError(res, 400, "Bad Request: send an initialize request first (no valid mcp-session-id).");
+                return;
             }
-            return rpcError(res, 400, "Bad Request: missing or unknown mcp-session-id.");
+            rpcError(res, 400, "Bad Request: missing or unknown mcp-session-id.");
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);

package/dist/legal.js

@@ -0,0 +1,127 @@
+/**
+ * Privacy Policy + Terms of Service pages for the WebCake Storefront MCP connector.
+ *
+ * Hosted at /privacy (also /privacy-policy) and /terms (also /tos) so the
+ * Claude Connectors Directory submission can point at stable, self-hosted URLs.
+ * Plain self-contained HTML — no external deps, served by http.ts.
+ */
+const CONTACT_EMAIL = process.env.WEBCAKE_SUPPORT_EMAIL || "vuluu040320@gmail.com";
+const LAST_UPDATED = "2026-06-23";
+function page(title, bodyHtml) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>${title} — WebCake Storefront MCP</title>
+<style>
+  :root{color-scheme:light dark}
+  body{margin:0;font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;line-height:1.65;color:#1e293b;background:#f8fafc}
+  @media(prefers-color-scheme:dark){body{color:#e2e8f0;background:#0f172a}}
+  main{max-width:760px;margin:0 auto;padding:48px 24px 80px}
+  h1{font-size:1.9rem;margin:0 0 4px}
+  h2{font-size:1.2rem;margin:32px 0 8px}
+  .meta{color:#64748b;font-size:.9rem;margin-bottom:28px}
+  a{color:#6d5efc}
+  code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:rgba(127,127,127,.15);padding:1px 5px;border-radius:4px}
+  ul{padding-left:22px}
+  footer{margin-top:48px;padding-top:20px;border-top:1px solid rgba(127,127,127,.25);color:#64748b;font-size:.85rem}
+</style></head>
+<body><main>${bodyHtml}
+<footer>WebCake Storefront MCP &middot; <a href="https://webcake.io">webcake.io</a> &middot; <a href="https://github.com/vuluu2k/webcake-storefront-mcp">source</a> &middot; Contact: <a href="mailto:${CONTACT_EMAIL}">${CONTACT_EMAIL}</a></footer>
+</main></body></html>`;
+}
+export function privacyHtml() {
+    return page("Privacy Policy", `<h1>Privacy Policy</h1>
+<div class="meta">Last updated: ${LAST_UPDATED}</div>
+<p>WebCake Storefront MCP ("the connector") is a Model Context Protocol server that lets an AI assistant
+build and manage storefront pages, products, articles, and orders in your
+<a href="https://webcake.io">WebCake / StoreCake</a> account. This policy explains what data the connector
+handles, why, who receives it, and how long it is kept.</p>
+
+<h2>Categories of personal data we access</h2>
+<ul>
+  <li><strong>Your WebCake identity, JWT, and session ID.</strong> When you connect via OAuth, you log in to
+  WebCake through the browser and the connector receives your bearer JWT and workspace session ID (<code>wsid</code>).
+  These are used <em>solely</em> to call the WebCake / StoreCake backend API on your behalf. They are never
+  shared with the AI assistant or any third party.</li>
+  <li><strong>Storefront content you ask the assistant to create or edit.</strong> Page source, product details,
+  article text, customer look-ups, and order data flow through the connector to your WebCake account.
+  <em>Purpose:</em> to carry out the actions you request.</li>
+  <li><strong>Images.</strong> When you ask the assistant to resize or process images, they are handled transiently
+  in memory and forwarded to the WebCake CDN. No image is retained on the connector after the request completes.</li>
+</ul>
+
+<h2>What we store and for how long</h2>
+<ul>
+  <li><strong>OAuth tokens (in-process memory only).</strong> The connector holds your JWT and session ID in an
+  in-memory token store <strong>only for the lifetime of the server process</strong>. There is no database;
+  tokens are never written to disk by the connector. Access tokens expire automatically after ~1 hour, refresh
+  tokens after ~30 days. A server restart clears all tokens.</li>
+  <li><strong>Local CLI config (stdio mode).</strong> When you run <code>npx webcake-storefront-mcp login</code>,
+  your token and session ID are saved to a local SQLite file on <em>your own machine</em> (at
+  <code>~/.webcake-storefront-mcp.db</code> or similar). This file stays on your device and is not transmitted
+  anywhere by the connector.</li>
+  <li>The connector does <strong>not</strong> run an analytics database, does <strong>not</strong> sell or share
+  data, and does <strong>not</strong> perform tracking or behavioral profiling.</li>
+</ul>
+
+<h2>Categories of recipients</h2>
+<p>Your data is shared only with the services required to fulfil your request:</p>
+<ul>
+  <li><strong>WebCake / StoreCake API</strong> (<code>api.storefront.webcake.io</code>) — stores and serves
+  your storefront pages, products, and orders; governed by WebCake's own terms.</li>
+  <li><strong>WebCake CDN</strong> — hosts images and published page assets that you explicitly create or upload.</li>
+</ul>
+
+<h2>Data we do NOT collect</h2>
+<p>The connector never asks for or stores payment-card data, passwords, health data, government identifiers,
+or MFA/OTP codes. It operates only on the storefront content you explicitly instruct the assistant to
+create — it does <strong>not</strong> read, reconstruct, or infer your conversation history.</p>
+
+<h2>Data retention &amp; deletion</h2>
+<p>OAuth tokens expire automatically or are cleared on server restart. You can revoke access at any time by
+disconnecting the connector in Claude / ChatGPT settings, or by running <code>npx webcake-storefront-mcp logout</code>.
+Storefront content you create lives in your WebCake account and is managed there. To request deletion of
+anything else, contact us below.</p>
+
+<h2>Security</h2>
+<p>All traffic uses HTTPS. The connector implements OAuth 2.1 with PKCE; your raw WebCake token is never
+exposed to the AI assistant — only resolved server-side per request via an opaque OAuth access token.</p>
+
+<h2>Contact</h2>
+<p>Questions or requests: <a href="mailto:${CONTACT_EMAIL}">${CONTACT_EMAIL}</a> or open an issue at
+<a href="https://github.com/vuluu2k/webcake-storefront-mcp/issues">github.com/vuluu2k/webcake-storefront-mcp</a>.</p>`);
+}
+export function termsHtml() {
+    return page("Terms of Service", `<h1>Terms of Service</h1>
+<div class="meta">Last updated: ${LAST_UPDATED}</div>
+<p>By connecting to and using the WebCake Storefront MCP connector ("the service") you agree to these terms.</p>
+
+<h2>What the service does</h2>
+<p>The service exposes tools that let an AI assistant create, update, and manage storefront pages, products,
+articles, customers, and orders in your WebCake / StoreCake account. It acts on your behalf using credentials
+you authorize through the WebCake OAuth login flow.</p>
+
+<h2>Your responsibilities</h2>
+<ul>
+  <li>You must have a valid WebCake / StoreCake account and the necessary permissions for any sites you target.</li>
+  <li>You are responsible for all content you generate and publish through the service, and for complying with
+  WebCake's terms of service and applicable law.</li>
+  <li>Do not use the service to create, distribute, or publish unlawful, infringing, or harmful content.</li>
+  <li>Do not attempt to use the service to access accounts or data you are not authorized to access.</li>
+</ul>
+
+<h2>Availability &amp; changes</h2>
+<p>The service is provided "as is" without warranty of any kind. We may update, suspend, or discontinue it at
+any time and may change these terms; continued use after a change constitutes acceptance of the new terms.</p>
+
+<h2>Limitation of liability</h2>
+<p>To the fullest extent permitted by applicable law, the operators of the connector are not liable for
+indirect, incidental, or consequential damages arising from use of the service. The service relies on
+third-party platforms (WebCake, the AI assistant host) whose own terms also apply.</p>
+
+<h2>Intellectual property</h2>
+<p>The connector is open-source software released under the MIT License. The WebCake trademarks and platform
+are owned by their respective holders.</p>
+
+<h2>Contact</h2>
+<p><a href="mailto:${CONTACT_EMAIL}">${CONTACT_EMAIL}</a> &middot;
+<a href="https://github.com/vuluu2k/webcake-storefront-mcp/issues">GitHub Issues</a></p>`);
+}

package/dist/persistence/postgres.js

@@ -0,0 +1,132 @@
+/**
+ * Lazy, shared Postgres pool used to PERSIST the OAuth 2.1 Authorization Server
+ * state (clients, pending auths, codes, access + refresh tokens) so tokens
+ * survive a `serve` restart and are shared across instances behind a load
+ * balancer — unlike the caches (Redis/disposable), OAuth state is durable.
+ *
+ * Returns null when no DATABASE_URL is configured OR `pg` isn't installed — the
+ * OAuth store then falls back to in-memory maps, so single-instance `serve`,
+ * stdio/`npx`, and the offline smoke gate keep working with ZERO infra.
+ *
+ * `pg` is an OPTIONAL, CJS dependency (see package.json), required via
+ * createRequire under ESM/Node16. The pool connects lazily per query.
+ *
+ * Configure with DATABASE_URL (or WEBCAKE_POSTGRES_URL), e.g.
+ * postgres://user:pw@host:5432/webcake_storefront
+ *
+ * KEY DIFFERENCE vs. landing-mcp: the credential is a PAIR (jwt + wsid), so
+ * oauth_codes / oauth_access_tokens / oauth_refresh_tokens carry two columns
+ * (`jwt text NOT NULL` and `wsid text`) instead of a single `ljwt` column.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let cached; // undefined = not yet resolved
+function redactUrl(u) {
+    try {
+        const x = new URL(u);
+        if (x.password)
+            x.password = "***";
+        return x.toString();
+    }
+    catch {
+        return "postgres";
+    }
+}
+/**
+ * Returns the shared Postgres pool, or null if Postgres isn't configured/available.
+ * Memoized: resolves the pool (or its absence) exactly once per process.
+ */
+export function getPg() {
+    if (cached !== undefined)
+        return cached;
+    const url = process.env.DATABASE_URL || process.env.WEBCAKE_POSTGRES_URL;
+    if (!url)
+        return (cached = null);
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Pool } = require("pg");
+        const pool = new Pool({
+            connectionString: url,
+            max: Number(process.env.WEBCAKE_PG_POOL_MAX) || 5,
+            // Managed Postgres (Supabase, Neon, …) often requires TLS; allow opting in
+            // without verifying the chain via WEBCAKE_PG_SSL=1.
+            ssl: /^(1|true|yes|on)$/i.test(process.env.WEBCAKE_PG_SSL ?? "")
+                ? { rejectUnauthorized: false }
+                : undefined,
+        });
+        pool.on("error", (e) => console.error("[pg] pool error:", e?.message ?? e));
+        console.error(`[pg] OAuth store backend: ${redactUrl(url)}`);
+        cached = pool;
+    }
+    catch (e) {
+        console.error("[pg] unavailable, using in-memory OAuth store:", e?.message ?? e);
+        cached = null;
+    }
+    return cached;
+}
+/**
+ * Create the OAuth tables if absent. Idempotent and memoized to a single
+ * in-flight promise per process, so concurrent callers share one round-trip. On
+ * any failure it logs and resolves false; the caller degrades to in-memory.
+ *
+ * Storefront schema: codes/tokens carry TWO credential columns:
+ *   jwt  text NOT NULL  — the user's WebCake JWT
+ *   wsid text           — the WebCake session/workspace ID (may be empty)
+ */
+let schemaReady;
+export function ensureOAuthSchema(pool) {
+    if (schemaReady)
+        return schemaReady;
+    schemaReady = (async () => {
+        try {
+            await pool.query(`
+        CREATE TABLE IF NOT EXISTS oauth_clients (
+          client_id     text PRIMARY KEY,
+          client_name   text,
+          redirect_uris jsonb NOT NULL,
+          created_at    bigint NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS oauth_pending (
+          state          text PRIMARY KEY,
+          client_id      text NOT NULL,
+          redirect_uri   text NOT NULL,
+          code_challenge text NOT NULL,
+          client_state   text,
+          scope          text,
+          expires_at     bigint NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS oauth_codes (
+          code           text PRIMARY KEY,
+          client_id      text NOT NULL,
+          redirect_uri   text NOT NULL,
+          code_challenge text NOT NULL,
+          scope          text,
+          jwt            text NOT NULL,
+          wsid           text,
+          expires_at     bigint NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS oauth_access_tokens (
+          token      text PRIMARY KEY,
+          jwt        text NOT NULL,
+          wsid       text,
+          scope      text,
+          expires_at bigint NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS oauth_refresh_tokens (
+          token      text PRIMARY KEY,
+          jwt        text NOT NULL,
+          wsid       text,
+          client_id  text NOT NULL,
+          scope      text,
+          expires_at bigint NOT NULL
+        );
+      `);
+            return true;
+        }
+        catch (e) {
+            console.error("[pg] OAuth schema init failed, using in-memory:", e?.message ?? e);
+            return false;
+        }
+    })();
+    return schemaReady;
+}