webcake-storefront-mcp 1.1.0 → 1.1.1

package/dist/auth/oauth-server.js

@@ -8,29 +8,47 @@
  * the authorization code and carried through to the access token so the HTTP
  * layer can inject BOTH x-webcake-jwt AND x-webcake-session-id headers.
  *
- * Store: in-memory only (no Postgres dependency in the storefront MCP). For a
- * multi-instance deploy, replace with a shared store behind the same interface.
+ * STORE: Postgres when DATABASE_URL is set (tokens survive a `serve` restart and
+ * are shared across instances behind a load balancer), else in-memory maps
+ * (single-instance `serve`, stdio/`npx`, offline tests). Both implement the same
+ * async `OAuthStore` interface; the rest of this module is backend-agnostic.
+ *
+ * CACHE: Redis (when REDIS_URL is set) caches access_token → {jwt,wsid} so
+ * /mcp requests avoid a Postgres round-trip on every call. Postgres remains the
+ * source of truth; a Redis miss just falls through to Postgres. On Redis
+ * absence / error the lookup goes directly to the store.
+ *
+ * All exported state functions are async — callers (src/http.ts) already await them.
+ * All exported function names and signatures are IDENTICAL to the previous version
+ * so http.ts requires no changes.
  */
 import { randomBytes, createHash } from "node:crypto";
-// ---- TTLs ------------------------------------------------------------------
+import { getPg, ensureOAuthSchema } from "../persistence/postgres.js";
+import { getRedis } from "../persistence/redis.js";
+// ---- TTLs (override via env where useful) ----------------------------------
 const TEN_MIN = 10 * 60 * 1000;
 const ACCESS_TTL = Number(process.env.WEBCAKE_OAUTH_ACCESS_TTL_MS) || 60 * 60 * 1000; // 1h
 const REFRESH_TTL = Number(process.env.WEBCAKE_OAUTH_REFRESH_TTL_MS) || 30 * 24 * 60 * 60 * 1000; // 30d
 const CODE_TTL = TEN_MIN;
 const PENDING_TTL = TEN_MIN;
+// Redis key prefix + TTL for the access-token cache (slightly shorter than ACCESS_TTL
+// so stale cache entries never outlive the canonical Postgres row).
+const REDIS_TOKEN_PREFIX = "wc:at:";
+const REDIS_TOKEN_TTL_MS = ACCESS_TTL - 60_000; // 1 min earlier than token expiry
 function now() {
     return Date.now();
 }
 function token(bytes = 32) {
     return randomBytes(bytes).toString("base64url");
 }
-// ---- In-memory store -------------------------------------------------------
+// ---- In-memory store (default; no DATABASE_URL) ----------------------------
 class MemoryStore {
     clients = new Map();
     pending = new Map();
     codes = new Map();
     access = new Map();
     refresh = new Map();
+    /** Lazy sweep of anything expired — cheap, called on the hot paths. */
     sweep() {
         const t = now();
         for (const [k, v] of this.pending)
@@ -46,24 +64,24 @@ class MemoryStore {
             if (v.expiresAt < t)
                 this.refresh.delete(k);
     }
-    putClient(c) { this.clients.set(c.client_id, c); }
-    getClient(id) { return this.clients.get(id); }
-    putPending(state, p) { this.sweep(); this.pending.set(state, p); }
-    takePending(state) {
+    async putClient(c) { this.clients.set(c.client_id, c); }
+    async getClient(id) { return this.clients.get(id); }
+    async putPending(state, p) { this.sweep(); this.pending.set(state, p); }
+    async takePending(state) {
         this.sweep();
         const p = this.pending.get(state);
         this.pending.delete(state);
         return p && p.expiresAt >= now() ? p : undefined;
     }
-    putCode(code, c) { this.codes.set(code, c); }
-    takeCode(code) {
+    async putCode(code, c) { this.codes.set(code, c); }
+    async takeCode(code) {
         this.sweep();
         const c = this.codes.get(code);
         this.codes.delete(code);
         return c && c.expiresAt >= now() ? c : undefined;
     }
-    putAccess(t, a) { this.access.set(t, a); }
-    getAccess(t) {
+    async putAccess(t, a) { this.access.set(t, a); }
+    async getAccess(t) {
         const a = this.access.get(t);
         if (a && a.expiresAt < now()) {
             this.access.delete(t);
@@ -71,23 +89,170 @@ class MemoryStore {
         }
         return a;
     }
-    putRefresh(t, r) { this.refresh.set(t, r); }
-    takeRefresh(t) {
+    async putRefresh(t, r) { this.refresh.set(t, r); }
+    async takeRefresh(t) {
         this.sweep();
         const r = this.refresh.get(t);
         this.refresh.delete(t);
         return r && r.expiresAt >= now() ? r : undefined;
     }
-    revoke(t) { this.access.delete(t); this.refresh.delete(t); }
+    async revoke(t) { this.access.delete(t); this.refresh.delete(t); }
+}
+// ---- Postgres store (when DATABASE_URL is set) -----------------------------
+class PgStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async putClient(c) {
+        await this.pool.query(`INSERT INTO oauth_clients (client_id, client_name, redirect_uris, created_at)
+       VALUES ($1,$2,$3,$4)
+       ON CONFLICT (client_id) DO UPDATE SET client_name=$2, redirect_uris=$3`, [c.client_id, c.client_name ?? null, JSON.stringify(c.redirect_uris), c.created_at]);
+    }
+    async getClient(id) {
+        const { rows } = await this.pool.query(`SELECT client_id, client_name, redirect_uris, created_at FROM oauth_clients WHERE client_id=$1`, [id]);
+        const r = rows[0];
+        if (!r)
+            return undefined;
+        return {
+            client_id: r.client_id,
+            client_name: r.client_name ?? undefined,
+            redirect_uris: Array.isArray(r.redirect_uris)
+                ? r.redirect_uris
+                : JSON.parse(r.redirect_uris),
+            created_at: Number(r.created_at),
+        };
+    }
+    async putPending(state, p) {
+        await this.pool.query(`INSERT INTO oauth_pending (state, client_id, redirect_uri, code_challenge, client_state, scope, expires_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7)`, [state, p.client_id, p.redirect_uri, p.code_challenge, p.state ?? null, p.scope ?? null, p.expiresAt]);
+    }
+    async takePending(state) {
+        const { rows } = await this.pool.query(`DELETE FROM oauth_pending WHERE state=$1
+       RETURNING client_id, redirect_uri, code_challenge, client_state, scope, expires_at`, [state]);
+        const r = rows[0];
+        if (!r || Number(r.expires_at) < now())
+            return undefined;
+        return {
+            client_id: r.client_id,
+            redirect_uri: r.redirect_uri,
+            code_challenge: r.code_challenge,
+            state: r.client_state ?? undefined,
+            scope: r.scope ?? undefined,
+            expiresAt: Number(r.expires_at),
+        };
+    }
+    async putCode(code, c) {
+        await this.pool.query(`INSERT INTO oauth_codes (code, client_id, redirect_uri, code_challenge, scope, jwt, wsid, expires_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8)`, [code, c.client_id, c.redirect_uri, c.code_challenge, c.scope ?? null, c.cred.jwt, c.cred.wsid, c.expiresAt]);
+    }
+    async takeCode(code) {
+        const { rows } = await this.pool.query(`DELETE FROM oauth_codes WHERE code=$1
+       RETURNING client_id, redirect_uri, code_challenge, scope, jwt, wsid, expires_at`, [code]);
+        const r = rows[0];
+        if (!r || Number(r.expires_at) < now())
+            return undefined;
+        return {
+            client_id: r.client_id,
+            redirect_uri: r.redirect_uri,
+            code_challenge: r.code_challenge,
+            scope: r.scope ?? undefined,
+            cred: { jwt: r.jwt, wsid: r.wsid ?? "" },
+            expiresAt: Number(r.expires_at),
+        };
+    }
+    async putAccess(t, a) {
+        await this.pool.query(`INSERT INTO oauth_access_tokens (token, jwt, wsid, scope, expires_at) VALUES ($1,$2,$3,$4,$5)`, [t, a.cred.jwt, a.cred.wsid, a.scope ?? null, a.expiresAt]);
+    }
+    async getAccess(t) {
+        const { rows } = await this.pool.query(`SELECT jwt, wsid, scope, expires_at FROM oauth_access_tokens WHERE token=$1`, [t]);
+        const r = rows[0];
+        if (!r)
+            return undefined;
+        if (Number(r.expires_at) < now()) {
+            await this.pool.query(`DELETE FROM oauth_access_tokens WHERE token=$1`, [t]);
+            return undefined;
+        }
+        return {
+            cred: { jwt: r.jwt, wsid: r.wsid ?? "" },
+            scope: r.scope ?? undefined,
+            expiresAt: Number(r.expires_at),
+        };
+    }
+    async putRefresh(t, r) {
+        await this.pool.query(`INSERT INTO oauth_refresh_tokens (token, jwt, wsid, client_id, scope, expires_at) VALUES ($1,$2,$3,$4,$5,$6)`, [t, r.cred.jwt, r.cred.wsid, r.client_id, r.scope ?? null, r.expiresAt]);
+    }
+    async takeRefresh(t) {
+        const { rows } = await this.pool.query(`DELETE FROM oauth_refresh_tokens WHERE token=$1
+       RETURNING jwt, wsid, client_id, scope, expires_at`, [t]);
+        const r = rows[0];
+        if (!r || Number(r.expires_at) < now())
+            return undefined;
+        return {
+            cred: { jwt: r.jwt, wsid: r.wsid ?? "" },
+            client_id: r.client_id,
+            scope: r.scope ?? undefined,
+            expiresAt: Number(r.expires_at),
+        };
+    }
+    async revoke(t) {
+        await this.pool.query(`DELETE FROM oauth_access_tokens WHERE token=$1`, [t]);
+        await this.pool.query(`DELETE FROM oauth_refresh_tokens WHERE token=$1`, [t]);
+    }
+}
+// ---- Backend selection (memoized) ------------------------------------------
+const memoryStore = new MemoryStore();
+let storePromise;
+/** Resolve the active store ONCE: Postgres if configured + schema ready, else memory. */
+function getStore() {
+    if (storePromise)
+        return storePromise;
+    storePromise = (async () => {
+        const pool = getPg();
+        if (pool && (await ensureOAuthSchema(pool)))
+            return new PgStore(pool);
+        return memoryStore;
+    })().catch((e) => {
+        console.error("[oauth] store init failed, using in-memory:", e?.message ?? e);
+        return memoryStore;
+    });
+    return storePromise;
+}
+// ---- Redis cache helpers (access-token only) --------------------------------
+/** Write {jwt,wsid} to Redis with the access-token TTL. Fire-and-forget. */
+function redisCachePut(redis, tok, cred) {
+    const val = JSON.stringify(cred);
+    redis.set(REDIS_TOKEN_PREFIX + tok, val, "PX", REDIS_TOKEN_TTL_MS).catch((e) => {
+        console.error("[redis] cache put error:", e?.message ?? e);
+    });
+}
+/** Read {jwt,wsid} from Redis. Returns null on miss or error. */
+async function redisCacheGet(redis, tok) {
+    try {
+        const raw = await redis.get(REDIS_TOKEN_PREFIX + tok);
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Evict an access-token key from Redis. Fire-and-forget. */
+function redisCacheDel(redis, tok) {
+    redis.del(REDIS_TOKEN_PREFIX + tok).catch((e) => {
+        console.error("[redis] cache del error:", e?.message ?? e);
+    });
 }
-const store = new MemoryStore();
 // ---- PKCE ------------------------------------------------------------------
+/** base64url( SHA256(verifier) ) — the S256 transform. */
 export function s256(verifier) {
     return createHash("sha256").update(verifier).digest("base64url");
 }
 export function verifyPkce(verifier, challenge) {
     if (!verifier || !challenge)
         return false;
+    // Constant-time-ish compare on equal-length base64url strings.
     const a = s256(verifier);
     if (a.length !== challenge.length)
         return false;
@@ -96,7 +261,7 @@ export function verifyPkce(verifier, challenge) {
         diff |= a.charCodeAt(i) ^ challenge.charCodeAt(i);
     return diff === 0;
 }
-export function registerClient(body) {
+export async function registerClient(body) {
     const uris = Array.isArray(body?.redirect_uris)
         ? body.redirect_uris.filter((u) => typeof u === "string" && /^https?:\/\//i.test(u))
         : [];
@@ -109,16 +274,17 @@ export function registerClient(body) {
         redirect_uris: uris,
         created_at: now(),
     };
-    store.putClient(client);
+    (await getStore()).putClient(client).catch((e) => console.error("[oauth] putClient:", e?.message ?? e));
     return { ok: true, client };
 }
-export function getClient(clientId) {
+export async function getClient(clientId) {
     if (!clientId)
         return undefined;
-    return store.getClient(clientId);
+    return (await getStore()).getClient(clientId);
 }
-export function startAuthorize(p) {
-    const client = p.client_id ? store.getClient(p.client_id) : undefined;
+export async function startAuthorize(p) {
+    const store = await getStore();
+    const client = p.client_id ? await store.getClient(p.client_id) : undefined;
     if (!client) {
         return { ok: false, error: "invalid_client", error_description: "Unknown client_id. Register first via /register.", redirectable: false };
     }
@@ -132,7 +298,7 @@ export function startAuthorize(p) {
         return { ok: false, error: "invalid_request", error_description: "PKCE with code_challenge_method=S256 is required.", redirectable: true };
     }
     const internalState = token(24);
-    store.putPending(internalState, {
+    await store.putPending(internalState, {
         client_id: client.client_id,
         redirect_uri: p.redirect_uri,
         code_challenge: p.code_challenge,
@@ -146,8 +312,9 @@ export function startAuthorize(p) {
  * The consent page (/mcp-storefront) bounced back with the user's jwt + wsid and our
  * internalState. Mint a one-time authorization code bound to that credential pair.
  */
-export function completeAuthorize(internalState, jwt, wsid) {
-    const p = internalState ? store.takePending(internalState) : undefined;
+export async function completeAuthorize(internalState, jwt, wsid) {
+    const store = await getStore();
+    const p = internalState ? await store.takePending(internalState) : undefined;
     if (!p) {
         return { ok: false, error: "invalid_request", error_description: "Authorization session expired or unknown — restart the connection." };
     }
@@ -155,7 +322,7 @@ export function completeAuthorize(internalState, jwt, wsid) {
         return { ok: false, error: "access_denied", error_description: "No WebCake token returned from login." };
     }
     const code = token(32);
-    store.putCode(code, {
+    await store.putCode(code, {
         client_id: p.client_id,
         redirect_uri: p.redirect_uri,
         code_challenge: p.code_challenge,
@@ -165,16 +332,21 @@ export function completeAuthorize(internalState, jwt, wsid) {
     });
     return { ok: true, redirectUri: p.redirect_uri, code, state: p.state };
 }
-function issueTokens(cred, client_id, scope) {
+async function issueTokens(store, cred, client_id, scope) {
     const access = token(32);
     const refresh = token(32);
-    store.putAccess(access, { cred, scope, expiresAt: now() + ACCESS_TTL });
-    store.putRefresh(refresh, { cred, client_id, scope, expiresAt: now() + REFRESH_TTL });
+    await store.putAccess(access, { cred, scope, expiresAt: now() + ACCESS_TTL });
+    await store.putRefresh(refresh, { cred, client_id, scope, expiresAt: now() + REFRESH_TTL });
+    // Warm the Redis cache immediately after issuing so the first /mcp request is a cache hit.
+    const redis = getRedis();
+    if (redis)
+        redisCachePut(redis, access, cred);
     return { access_token: access, token_type: "Bearer", expires_in: Math.floor(ACCESS_TTL / 1000), refresh_token: refresh, scope };
 }
-export function exchangeToken(p) {
+export async function exchangeToken(p) {
+    const store = await getStore();
     if (p.grant_type === "authorization_code") {
-        const c = p.code ? store.takeCode(p.code) : undefined;
+        const c = p.code ? await store.takeCode(p.code) : undefined;
         if (!c) {
             return { ok: false, status: 400, error: "invalid_grant", error_description: "Unknown or expired authorization code." };
         }
@@ -187,29 +359,53 @@ export function exchangeToken(p) {
         if (!p.code_verifier || !verifyPkce(p.code_verifier, c.code_challenge)) {
             return { ok: false, status: 400, error: "invalid_grant", error_description: "PKCE verification failed." };
         }
-        return { ok: true, body: issueTokens(c.cred, c.client_id, c.scope) };
+        return { ok: true, body: await issueTokens(store, c.cred, c.client_id, c.scope) };
     }
     if (p.grant_type === "refresh_token") {
-        const r = p.refresh_token ? store.takeRefresh(p.refresh_token) : undefined;
+        const r = p.refresh_token ? await store.takeRefresh(p.refresh_token) : undefined;
         if (!r) {
             return { ok: false, status: 400, error: "invalid_grant", error_description: "Unknown or expired refresh token." };
         }
-        return { ok: true, body: issueTokens(r.cred, r.client_id, r.scope) };
+        return { ok: true, body: await issueTokens(store, r.cred, r.client_id, r.scope) };
     }
     return { ok: false, status: 400, error: "unsupported_grant_type", error_description: "grant_type must be authorization_code or refresh_token." };
 }
 // ---- Resource-server side: resolve a Bearer access token to the cred pair --
-/** Returns the { jwt, wsid } for a valid, unexpired access token, else undefined. */
-export function resolveAccessToken(accessToken) {
+/**
+ * Returns the { jwt, wsid } for a valid, unexpired access token, else undefined.
+ *
+ * Hot path — hit on every /mcp request. Resolution order:
+ *   1. Redis cache (sub-millisecond, no Postgres round-trip)
+ *   2. Postgres / in-memory store (source of truth, backfills Redis on hit)
+ */
+export async function resolveAccessToken(accessToken) {
     if (!accessToken)
         return undefined;
-    return store.getAccess(accessToken)?.cred;
+    // 1. Try Redis cache first.
+    const redis = getRedis();
+    if (redis) {
+        const cached = await redisCacheGet(redis, accessToken);
+        if (cached)
+            return cached;
+    }
+    // 2. Fall through to the store (Postgres or memory).
+    const a = await (await getStore()).getAccess(accessToken);
+    if (!a)
+        return undefined;
+    // Backfill the Redis cache for next time.
+    if (redis)
+        redisCachePut(redis, accessToken, a.cred);
+    return a.cred;
 }
 /** Revoke an access or refresh token (best-effort; for /revoke). */
-export function revokeToken(t) {
+export async function revokeToken(t) {
     if (!t)
         return;
-    store.revoke(t);
+    // Evict from Redis cache before hitting the store so the slot is gone immediately.
+    const redis = getRedis();
+    if (redis)
+        redisCacheDel(redis, t);
+    await (await getStore()).revoke(t);
 }
 // ---- Metadata documents (RFC 8414 / RFC 9728) ------------------------------
 export function authServerMetadata(issuer) {

package/dist/http.js

@@ -11,7 +11,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "./server.js";
 import { makeApi, resolveEnv, ENVIRONMENTS, DEFAULT_ENV } from "./config.js";
-import { landingHtml, faviconSvg } from "./web-guide.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";
@@ -177,7 +177,7 @@ async function handleOAuth(req, res, path) {
         }
         const raw = await readRawBody(req);
         const body = parseBodyParams(raw, String(req.headers["content-type"] ?? ""));
-        const result = registerClient(body);
+        const result = await registerClient(body);
         if (!result.ok) {
             oauthError(res, 400, result.error, result.error_description);
             return true;
@@ -196,7 +196,7 @@ async function handleOAuth(req, res, path) {
     // ---- 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 = startAuthorize({
+        const result = await startAuthorize({
             client_id: sp.get("client_id"),
             redirect_uri: sp.get("redirect_uri"),
             response_type: sp.get("response_type"),
@@ -235,7 +235,7 @@ async function handleOAuth(req, res, path) {
         // 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 = completeAuthorize(sp.get("state"), jwt, wsid);
+        const done = await completeAuthorize(sp.get("state"), jwt, wsid);
         if (!done.ok) {
             htmlError(res, 400, done.error_description);
             return true;
@@ -261,7 +261,7 @@ async function handleOAuth(req, res, path) {
         }
         const raw = await readRawBody(req);
         const body = parseBodyParams(raw, String(req.headers["content-type"] ?? ""));
-        const result = exchangeToken(body);
+        const result = await exchangeToken(body);
         if (!result.ok) {
             oauthError(res, result.status, result.error, result.error_description);
             return true;
@@ -295,6 +295,12 @@ export async function startHttpServer(port) {
             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" });
@@ -312,8 +318,9 @@ export async function startHttpServer(port) {
                 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)));
+                    res.end(landingHtml(publicBase(req), lang));
                     return;
                 }
             }
@@ -334,7 +341,7 @@ export async function startHttpServer(port) {
         // 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 = resolveAccessToken(bearer);
+        const oauthCred = await resolveAccessToken(bearer);
         if (oauthCred) {
             if (req.headers["x-webcake-jwt"] == null) {
                 req.headers["x-webcake-jwt"] = oauthCred.jwt;

package/dist/legal.js

@@ -18,7 +18,7 @@ function page(title, bodyHtml) {
   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:#108B67}
+  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}

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;
+}