@exposify/supabase 0.3.7 → 0.3.8

package/dist/index.cjs

@@ -29,10 +29,11 @@ __export(index_exports, {
   fetchOpenApi: () => fetchOpenApi,
   introspectTables: () => introspectTables,
   loadManifest: () => loadManifest,
-  rpcArgSchema: () => rpcArgSchema
+  rpcArgSchema: () => rpcArgSchema,
+  supabaseAuth: () => supabaseAuth
 });
 module.exports = __toCommonJS(index_exports);
-var import_core3 = require("@exposify/core");
+var import_core5 = require("@exposify/core");
 
 // src/kb.ts
 var import_core = require("@exposify/core");
@@ -108,12 +109,20 @@ function warnOnce(message) {
   }
 }
 function resolveSupabaseConfig(options = {}) {
+  if (options.oauth) {
+    if (options.docsAuth === "public") {
+      throw new Error('docsAuth: "public" cannot be combined with oauth (the whole MCP endpoint requires a token)');
+    }
+    if (options.auth || options.authRequired) {
+      throw new Error("oauth cannot be combined with auth/authRequired (oauth already requires a valid token on every request)");
+    }
+  }
   return {
     writes: parseWrites(options.writes),
     rpc: options.rpc ?? [],
     functions: options.functions ?? {},
     docs: options.docs ?? ["docs/**/*.md"],
-    docsAuth: options.docsAuth ?? "public",
+    docsAuth: options.docsAuth ?? (options.oauth ? "required" : "public"),
     maxRows: options.maxRows ?? 100,
     rateLimit: options.rateLimit,
     rateWindowMs: options.rateWindowMs
@@ -635,6 +644,96 @@ async function toResult(run) {
   }
 }
 
+// src/oauth.ts
+var import_core3 = require("@exposify/core");
+var PRM_SUFFIX = "/.well-known/oauth-protected-resource";
+function supabaseAuth(overrides = {}) {
+  return (supabaseUrl) => {
+    const base = supabaseUrl.replace(/\/+$/, "");
+    return {
+      issuer: `${base}/auth/v1`,
+      jwksUri: `${base}/auth/v1/.well-known/jwks.json`,
+      audience: "authenticated",
+      ...overrides
+    };
+  };
+}
+function functionNameFromMainModule() {
+  const mainModule = globalThis.Deno?.mainModule;
+  if (!mainModule) return void 0;
+  try {
+    const parts = new URL(mainModule).pathname.split("/").filter(Boolean);
+    return parts.length >= 2 ? parts[parts.length - 2] : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createSupabaseOAuthGate(oauth, supabaseUrl, fetchImpl) {
+  if (typeof oauth === "function" && !supabaseUrl) {
+    throw new Error("oauth: SUPABASE_URL is not set. In a deployed function this is automatic; for local dev pass { supabaseUrl }.");
+  }
+  const opts = typeof oauth === "function" ? oauth(supabaseUrl) : oauth;
+  let resource = opts.resource;
+  if (!resource) {
+    const name = functionNameFromMainModule();
+    if (!supabaseUrl || !name) {
+      throw new Error("oauth.resource could not be derived (needs SUPABASE_URL and Deno.mainModule); pass oauth.resource explicitly.");
+    }
+    resource = `${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${name}`;
+  }
+  const { metadataUrl, ...oauthOptions } = opts;
+  const cfg = (0, import_core3.resolveOAuthOptions)({ ...oauthOptions, resource });
+  if (metadataUrl !== void 0) {
+    try {
+      new URL(metadataUrl);
+    } catch {
+      throw new Error(`oauth.metadataUrl must be an absolute URL, got ${JSON.stringify(metadataUrl)}`);
+    }
+  }
+  return (0, import_core3.createOAuthGate)(cfg, { metadataUrl: metadataUrl ?? `${cfg.resource}${PRM_SUFFIX}`, fetchImpl });
+}
+
+// src/startup.ts
+var import_core4 = require("@exposify/core");
+var LOG_PREFIX = "[exposify-supabase]";
+var INTROSPECTION_FIX = "check that SUPABASE_SERVICE_ROLE_KEY is available to the function and the exposify_meta migration is applied (`supabase db push`); the reason is logged above. To survive this, bundle a manifest with `exposify-supabase generate`";
+function supabaseToolsPhrase(ladder, cfg, hasDocs) {
+  const query = ladder.tables.length;
+  let write = 0;
+  for (const table of ladder.tables) write += cfg.writes.get(table.name)?.size ?? 0;
+  const rpc = cfg.rpc.length;
+  const fn = Object.keys(cfg.functions).length;
+  const parts = [`${query} query`];
+  if (write) parts.push(`${write} write`);
+  if (rpc) parts.push(`${rpc} rpc`);
+  if (fn) parts.push(`${fn} function${fn === 1 ? "" : "s"}`);
+  if (hasDocs) parts.push("search_docs");
+  const total = query + write + rpc + fn + (hasDocs ? 1 : 0);
+  return `${total} tool${total === 1 ? "" : "s"} (${parts.join(", ")})`;
+}
+function logColdStart(opts) {
+  const { ladder, cfg, docs, endpoint, auth, logReady } = opts;
+  if (ladder.mode === "functions-only") {
+    console.error(
+      (0, import_core4.formatFailed)(
+        LOG_PREFIX,
+        "couldn't read the database schema and no bundled manifest exists, so only registered functions and docs are exposed",
+        INTROSPECTION_FIX
+      )
+    );
+    return;
+  }
+  if (logReady) {
+    const details = ladder.mode === "manifest" ? ["from the bundled manifest"] : [];
+    console.log((0, import_core4.formatReady)(LOG_PREFIX, { endpoint, tools: supabaseToolsPhrase(ladder, cfg, docs > 0), details, docs, auth }));
+  }
+  if (ladder.mode === "manifest") {
+    console.warn(
+      (0, import_core4.formatWarning)(LOG_PREFIX, "live schema introspection failed; tools come from the bundled manifest and may be out of date", INTROSPECTION_FIX)
+    );
+  }
+}
+
 // src/index.ts
 function denoEnv() {
   return globalThis.Deno?.env;
@@ -646,13 +745,38 @@ function aiReady(options = {}) {
   const supabaseUrl = options.supabaseUrl ?? env?.get("SUPABASE_URL");
   const anonKey = options.anonKey ?? env?.get("SUPABASE_ANON_KEY") ?? "";
   const serviceRoleKey = options.serviceRoleKey ?? env?.get("SUPABASE_SERVICE_ROLE_KEY") ?? "";
+  const gate = options.oauth ? createSupabaseOAuthGate(options.oauth, supabaseUrl, fetchImpl) : null;
+  const logReady = (0, import_core5.startupLogEnabled)(options.startupLog);
+  const functionName = functionNameFromMainModule();
+  const endpoint = gate?.metadata.resource ?? (supabaseUrl && functionName ? `${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${functionName}` : "this function");
+  const authLabel = gate ? `oauth (${String(gate.metadata.authorization_servers[0])})` : options.auth ? "custom resolver" : "passthrough (caller's JWT)";
+  if (!supabaseUrl) {
+    console.error(
+      (0, import_core5.formatFailed)(LOG_PREFIX, "SUPABASE_URL is not set", "deployed functions get it automatically; for local dev pass { supabaseUrl }")
+    );
+  } else if (gate && logReady) {
+    void gate.probe().then((problem) => {
+      if (!problem) return;
+      console.warn(
+        (0, import_core5.formatWarning)(
+          LOG_PREFIX,
+          `can't verify access tokens from oauth.issuer ${String(gate.metadata.authorization_servers[0])}: ${problem}`,
+          "check the issuer (supabaseAuth() needs the project's OAuth server enabled and asymmetric JWT signing keys); until then MCP clients get 503"
+        )
+      );
+    });
+  }
+  let coldStartLogged = false;
   let kbPromise = null;
+  let docCount = 0;
   const getKb = () => {
     kbPromise ??= (async () => {
       const mainModule = globalThis.Deno?.mainModule;
       if (!mainModule) return import_core.KnowledgeBase.build([]);
       try {
-        return import_core.KnowledgeBase.build(await loadDocsFromDeno(cfg.docs, new URL(mainModule)));
+        const docs = await loadDocsFromDeno(cfg.docs, new URL(mainModule));
+        docCount = docs.length;
+        return import_core.KnowledgeBase.build(docs);
       } catch {
         return import_core.KnowledgeBase.build([]);
       }
@@ -675,7 +799,7 @@ function aiReady(options = {}) {
     return ladderPromise;
   };
   const resolvedAuth = /* @__PURE__ */ new WeakMap();
-  const core = (0, import_core3.createWebMcpHandler)(
+  const core = (0, import_core5.createWebMcpHandler)(
     {
       getServer: async (req) => {
         if (!supabaseUrl) {
@@ -687,6 +811,14 @@ function aiReady(options = {}) {
         const incoming = req.headers;
         const headers = buildPostgrestHeaders(resolvedAuth.get(req) ?? incoming, anonKey);
         const ladder = await getLadder(postgrestUrl);
+        const kb = await getKb();
+        if (!coldStartLogged) {
+          coldStartLogged = true;
+          try {
+            logColdStart({ ladder, cfg, docs: docCount, endpoint, auth: authLabel, logReady });
+          } catch {
+          }
+        }
         const client = createPostgrestClient(postgrestUrl, headers, fetchImpl);
         const invokeFunction = async (name, body) => {
           const res = await fetchImpl(`${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${name}`, {
@@ -703,7 +835,7 @@ function aiReady(options = {}) {
           cfg,
           client,
           openapi: ladder.openapi,
-          kb: await getKb(),
+          kb,
           incoming,
           invokeFunction,
           warnings: ladder.warnings
@@ -712,12 +844,19 @@ function aiReady(options = {}) {
     },
     { rateLimit: cfg.rateLimit, rateWindowMs: cfg.rateWindowMs }
   );
+  if (gate) {
+    return async (req) => {
+      if (new URL(req.url).pathname.endsWith(PRM_SUFFIX)) return gate.metadataResponse(req.method);
+      const result = await gate.check(req.headers);
+      return result.ok ? core(req) : result.response;
+    };
+  }
   const auth = options.auth;
   if (!auth) return core;
   return async (req) => {
     let resolved;
     try {
-      resolved = await auth(req.headers);
+      resolved = await auth(req.headers, {});
     } catch (err) {
       console.error("exposify-supabase: auth resolver failed", err);
       return Response.json({ error: "internal MCP server error" }, { status: 503 });
@@ -740,5 +879,6 @@ function aiReady(options = {}) {
   fetchOpenApi,
   introspectTables,
   loadManifest,
-  rpcArgSchema
+  rpcArgSchema,
+  supabaseAuth
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AuthResolver, WebMcpHandler } from '@exposify/core';
+import { OAuthOptions, AuthResolver, WebMcpHandler } from '@exposify/core';
 
 type ColumnType = "string" | "number" | "integer" | "boolean" | "object" | "array";
 interface ColumnSchema {
@@ -45,6 +45,23 @@ interface JsonSchemaObject {
     properties?: Record<string, JsonSchemaProperty>;
     required?: string[];
 }
+/**
+ * `OAuthOptions` with `resource` optional: it defaults to this function's own
+ * URL, `${SUPABASE_URL}/functions/v1/<function name>`.
+ */
+type SupabaseOAuthOptions = Omit<OAuthOptions, "resource"> & {
+    resource?: string;
+    /**
+     * Where the `401` challenge says the Protected Resource Metadata lives.
+     * Default: `${resource}/.well-known/oauth-protected-resource`, under the
+     * function's own URL. Set it when a proxy you control serves the function
+     * on your own domain and forwards the RFC 9728 root-level well-known URI
+     * (e.g. `https://mcp.acme.com/.well-known/oauth-protected-resource/mcp`)
+     * to the function; the function answers any path ending in
+     * `/.well-known/oauth-protected-resource`.
+     */
+    metadataUrl?: string;
+};
 interface AgentifySupabaseOptions {
     /** `"<table>.insert"` / `"<table>.update"` / `"<table>.delete"` / `"<table>.*"`. */
     writes?: string[];
@@ -54,7 +71,25 @@ interface AgentifySupabaseOptions {
     functions?: Record<string, FunctionToolConfig>;
     /** Doc globs bundled in the function directory. Default: `["docs/**\/*.md"]`. */
     docs?: string[];
+    /** Default `"public"`, or `"required"` when `oauth` is set (which can't be combined with `"public"`). */
     docsAuth?: "public" | "required";
+    /**
+     * Require an OAuth access token on the whole endpoint, so MCP clients can
+     * "click Connect and log in": a tokenless request gets a `401` pointing at
+     * Protected Resource Metadata served under this function's own path. Use
+     * `supabaseAuth()` for Supabase Auth's OAuth 2.1 server, or pass any
+     * spec-compliant AS (a function form receives the resolved `SUPABASE_URL`).
+     * The validated token is forwarded to PostgREST as-is, so RLS runs as the
+     * signed-in user. Can't be combined with `auth`/`authRequired`; deploy with
+     * `verify_jwt = false` so the gateway lets the first tokenless request
+     * through to answer it.
+     */
+    oauth?: SupabaseOAuthOptions | ((supabaseUrl: string) => SupabaseOAuthOptions);
+    /**
+     * The cold-start "MCP ready" line and the oauth issuer check. Default: on,
+     * except under `NODE_ENV=test`. Failures are logged regardless.
+     */
+    startupLog?: boolean;
     /** Row cap applied to every `query_<table>` call regardless of caller-supplied `limit`. Default 100. */
     maxRows?: number;
     /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
@@ -96,6 +131,20 @@ interface AgentifySupabaseOptions {
     rateWindowMs?: number;
 }
 
+/**
+ * Supabase Auth's OAuth 2.1 server as the authorization server. Per
+ * Supabase's docs its access tokens are ordinary project JWTs: `iss` is
+ * `${SUPABASE_URL}/auth/v1`, keys are at `/auth/v1/.well-known/jwks.json`,
+ * and `aud` is always `"authenticated"` -- it can't bind tokens to this
+ * function's URL, hence the `audience` override (any of the project's user
+ * JWTs is accepted, which is exactly what RLS already trusts). Needs, in the
+ * project: the OAuth 2.1 server enabled (beta as of 2026-10) with dynamic
+ * client registration on, an authorization path pointing at a consent page
+ * the app hosts, and asymmetric JWT signing keys (legacy HS256 projects have
+ * no JWKS to verify against).
+ */
+declare function supabaseAuth(overrides?: Partial<SupabaseOAuthOptions>): (supabaseUrl: string) => SupabaseOAuthOptions;
+
 /** Subset of PostgREST's generated OpenAPI (Swagger 2.0) document that we read. */
 interface PostgrestOpenApiDoc {
     definitions?: Record<string, PostgrestTableDefinition>;
@@ -205,4 +254,4 @@ declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl:
  */
 declare function aiReady(options?: AgentifySupabaseOptions): WebMcpHandler;
 
-export { type AgentifySupabaseOptions, type ExposifyManifest, MANIFEST_VERSION, MissingExposifyMetaError, type PostgrestOpenApiDoc, aiReady, buildManifest, columnsFromOpenApi, fetchExposifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema };
+export { type AgentifySupabaseOptions, type ExposifyManifest, MANIFEST_VERSION, MissingExposifyMetaError, type PostgrestOpenApiDoc, type SupabaseOAuthOptions, aiReady, buildManifest, columnsFromOpenApi, fetchExposifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema, supabaseAuth };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AuthResolver, WebMcpHandler } from '@exposify/core';
+import { OAuthOptions, AuthResolver, WebMcpHandler } from '@exposify/core';
 
 type ColumnType = "string" | "number" | "integer" | "boolean" | "object" | "array";
 interface ColumnSchema {
@@ -45,6 +45,23 @@ interface JsonSchemaObject {
     properties?: Record<string, JsonSchemaProperty>;
     required?: string[];
 }
+/**
+ * `OAuthOptions` with `resource` optional: it defaults to this function's own
+ * URL, `${SUPABASE_URL}/functions/v1/<function name>`.
+ */
+type SupabaseOAuthOptions = Omit<OAuthOptions, "resource"> & {
+    resource?: string;
+    /**
+     * Where the `401` challenge says the Protected Resource Metadata lives.
+     * Default: `${resource}/.well-known/oauth-protected-resource`, under the
+     * function's own URL. Set it when a proxy you control serves the function
+     * on your own domain and forwards the RFC 9728 root-level well-known URI
+     * (e.g. `https://mcp.acme.com/.well-known/oauth-protected-resource/mcp`)
+     * to the function; the function answers any path ending in
+     * `/.well-known/oauth-protected-resource`.
+     */
+    metadataUrl?: string;
+};
 interface AgentifySupabaseOptions {
     /** `"<table>.insert"` / `"<table>.update"` / `"<table>.delete"` / `"<table>.*"`. */
     writes?: string[];
@@ -54,7 +71,25 @@ interface AgentifySupabaseOptions {
     functions?: Record<string, FunctionToolConfig>;
     /** Doc globs bundled in the function directory. Default: `["docs/**\/*.md"]`. */
     docs?: string[];
+    /** Default `"public"`, or `"required"` when `oauth` is set (which can't be combined with `"public"`). */
     docsAuth?: "public" | "required";
+    /**
+     * Require an OAuth access token on the whole endpoint, so MCP clients can
+     * "click Connect and log in": a tokenless request gets a `401` pointing at
+     * Protected Resource Metadata served under this function's own path. Use
+     * `supabaseAuth()` for Supabase Auth's OAuth 2.1 server, or pass any
+     * spec-compliant AS (a function form receives the resolved `SUPABASE_URL`).
+     * The validated token is forwarded to PostgREST as-is, so RLS runs as the
+     * signed-in user. Can't be combined with `auth`/`authRequired`; deploy with
+     * `verify_jwt = false` so the gateway lets the first tokenless request
+     * through to answer it.
+     */
+    oauth?: SupabaseOAuthOptions | ((supabaseUrl: string) => SupabaseOAuthOptions);
+    /**
+     * The cold-start "MCP ready" line and the oauth issuer check. Default: on,
+     * except under `NODE_ENV=test`. Failures are logged regardless.
+     */
+    startupLog?: boolean;
     /** Row cap applied to every `query_<table>` call regardless of caller-supplied `limit`. Default 100. */
     maxRows?: number;
     /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
@@ -96,6 +131,20 @@ interface AgentifySupabaseOptions {
     rateWindowMs?: number;
 }
 
+/**
+ * Supabase Auth's OAuth 2.1 server as the authorization server. Per
+ * Supabase's docs its access tokens are ordinary project JWTs: `iss` is
+ * `${SUPABASE_URL}/auth/v1`, keys are at `/auth/v1/.well-known/jwks.json`,
+ * and `aud` is always `"authenticated"` -- it can't bind tokens to this
+ * function's URL, hence the `audience` override (any of the project's user
+ * JWTs is accepted, which is exactly what RLS already trusts). Needs, in the
+ * project: the OAuth 2.1 server enabled (beta as of 2026-10) with dynamic
+ * client registration on, an authorization path pointing at a consent page
+ * the app hosts, and asymmetric JWT signing keys (legacy HS256 projects have
+ * no JWKS to verify against).
+ */
+declare function supabaseAuth(overrides?: Partial<SupabaseOAuthOptions>): (supabaseUrl: string) => SupabaseOAuthOptions;
+
 /** Subset of PostgREST's generated OpenAPI (Swagger 2.0) document that we read. */
 interface PostgrestOpenApiDoc {
     definitions?: Record<string, PostgrestTableDefinition>;
@@ -205,4 +254,4 @@ declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl:
  */
 declare function aiReady(options?: AgentifySupabaseOptions): WebMcpHandler;
 
-export { type AgentifySupabaseOptions, type ExposifyManifest, MANIFEST_VERSION, MissingExposifyMetaError, type PostgrestOpenApiDoc, aiReady, buildManifest, columnsFromOpenApi, fetchExposifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema };
+export { type AgentifySupabaseOptions, type ExposifyManifest, MANIFEST_VERSION, MissingExposifyMetaError, type PostgrestOpenApiDoc, type SupabaseOAuthOptions, aiReady, buildManifest, columnsFromOpenApi, fetchExposifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema, supabaseAuth };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { createWebMcpHandler } from "@exposify/core";
+import { createWebMcpHandler, formatFailed as formatFailed2, formatWarning as formatWarning2, startupLogEnabled } from "@exposify/core";
 
 // src/kb.ts
 import { KnowledgeBase } from "@exposify/core";
@@ -75,12 +75,20 @@ function warnOnce(message) {
   }
 }
 function resolveSupabaseConfig(options = {}) {
+  if (options.oauth) {
+    if (options.docsAuth === "public") {
+      throw new Error('docsAuth: "public" cannot be combined with oauth (the whole MCP endpoint requires a token)');
+    }
+    if (options.auth || options.authRequired) {
+      throw new Error("oauth cannot be combined with auth/authRequired (oauth already requires a valid token on every request)");
+    }
+  }
   return {
     writes: parseWrites(options.writes),
     rpc: options.rpc ?? [],
     functions: options.functions ?? {},
     docs: options.docs ?? ["docs/**/*.md"],
-    docsAuth: options.docsAuth ?? "public",
+    docsAuth: options.docsAuth ?? (options.oauth ? "required" : "public"),
     maxRows: options.maxRows ?? 100,
     rateLimit: options.rateLimit,
     rateWindowMs: options.rateWindowMs
@@ -605,6 +613,96 @@ async function toResult(run) {
   }
 }
 
+// src/oauth.ts
+import { createOAuthGate, resolveOAuthOptions } from "@exposify/core";
+var PRM_SUFFIX = "/.well-known/oauth-protected-resource";
+function supabaseAuth(overrides = {}) {
+  return (supabaseUrl) => {
+    const base = supabaseUrl.replace(/\/+$/, "");
+    return {
+      issuer: `${base}/auth/v1`,
+      jwksUri: `${base}/auth/v1/.well-known/jwks.json`,
+      audience: "authenticated",
+      ...overrides
+    };
+  };
+}
+function functionNameFromMainModule() {
+  const mainModule = globalThis.Deno?.mainModule;
+  if (!mainModule) return void 0;
+  try {
+    const parts = new URL(mainModule).pathname.split("/").filter(Boolean);
+    return parts.length >= 2 ? parts[parts.length - 2] : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createSupabaseOAuthGate(oauth, supabaseUrl, fetchImpl) {
+  if (typeof oauth === "function" && !supabaseUrl) {
+    throw new Error("oauth: SUPABASE_URL is not set. In a deployed function this is automatic; for local dev pass { supabaseUrl }.");
+  }
+  const opts = typeof oauth === "function" ? oauth(supabaseUrl) : oauth;
+  let resource = opts.resource;
+  if (!resource) {
+    const name = functionNameFromMainModule();
+    if (!supabaseUrl || !name) {
+      throw new Error("oauth.resource could not be derived (needs SUPABASE_URL and Deno.mainModule); pass oauth.resource explicitly.");
+    }
+    resource = `${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${name}`;
+  }
+  const { metadataUrl, ...oauthOptions } = opts;
+  const cfg = resolveOAuthOptions({ ...oauthOptions, resource });
+  if (metadataUrl !== void 0) {
+    try {
+      new URL(metadataUrl);
+    } catch {
+      throw new Error(`oauth.metadataUrl must be an absolute URL, got ${JSON.stringify(metadataUrl)}`);
+    }
+  }
+  return createOAuthGate(cfg, { metadataUrl: metadataUrl ?? `${cfg.resource}${PRM_SUFFIX}`, fetchImpl });
+}
+
+// src/startup.ts
+import { formatFailed, formatReady, formatWarning } from "@exposify/core";
+var LOG_PREFIX = "[exposify-supabase]";
+var INTROSPECTION_FIX = "check that SUPABASE_SERVICE_ROLE_KEY is available to the function and the exposify_meta migration is applied (`supabase db push`); the reason is logged above. To survive this, bundle a manifest with `exposify-supabase generate`";
+function supabaseToolsPhrase(ladder, cfg, hasDocs) {
+  const query = ladder.tables.length;
+  let write = 0;
+  for (const table of ladder.tables) write += cfg.writes.get(table.name)?.size ?? 0;
+  const rpc = cfg.rpc.length;
+  const fn = Object.keys(cfg.functions).length;
+  const parts = [`${query} query`];
+  if (write) parts.push(`${write} write`);
+  if (rpc) parts.push(`${rpc} rpc`);
+  if (fn) parts.push(`${fn} function${fn === 1 ? "" : "s"}`);
+  if (hasDocs) parts.push("search_docs");
+  const total = query + write + rpc + fn + (hasDocs ? 1 : 0);
+  return `${total} tool${total === 1 ? "" : "s"} (${parts.join(", ")})`;
+}
+function logColdStart(opts) {
+  const { ladder, cfg, docs, endpoint, auth, logReady } = opts;
+  if (ladder.mode === "functions-only") {
+    console.error(
+      formatFailed(
+        LOG_PREFIX,
+        "couldn't read the database schema and no bundled manifest exists, so only registered functions and docs are exposed",
+        INTROSPECTION_FIX
+      )
+    );
+    return;
+  }
+  if (logReady) {
+    const details = ladder.mode === "manifest" ? ["from the bundled manifest"] : [];
+    console.log(formatReady(LOG_PREFIX, { endpoint, tools: supabaseToolsPhrase(ladder, cfg, docs > 0), details, docs, auth }));
+  }
+  if (ladder.mode === "manifest") {
+    console.warn(
+      formatWarning(LOG_PREFIX, "live schema introspection failed; tools come from the bundled manifest and may be out of date", INTROSPECTION_FIX)
+    );
+  }
+}
+
 // src/index.ts
 function denoEnv() {
   return globalThis.Deno?.env;
@@ -616,13 +714,38 @@ function aiReady(options = {}) {
   const supabaseUrl = options.supabaseUrl ?? env?.get("SUPABASE_URL");
   const anonKey = options.anonKey ?? env?.get("SUPABASE_ANON_KEY") ?? "";
   const serviceRoleKey = options.serviceRoleKey ?? env?.get("SUPABASE_SERVICE_ROLE_KEY") ?? "";
+  const gate = options.oauth ? createSupabaseOAuthGate(options.oauth, supabaseUrl, fetchImpl) : null;
+  const logReady = startupLogEnabled(options.startupLog);
+  const functionName = functionNameFromMainModule();
+  const endpoint = gate?.metadata.resource ?? (supabaseUrl && functionName ? `${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${functionName}` : "this function");
+  const authLabel = gate ? `oauth (${String(gate.metadata.authorization_servers[0])})` : options.auth ? "custom resolver" : "passthrough (caller's JWT)";
+  if (!supabaseUrl) {
+    console.error(
+      formatFailed2(LOG_PREFIX, "SUPABASE_URL is not set", "deployed functions get it automatically; for local dev pass { supabaseUrl }")
+    );
+  } else if (gate && logReady) {
+    void gate.probe().then((problem) => {
+      if (!problem) return;
+      console.warn(
+        formatWarning2(
+          LOG_PREFIX,
+          `can't verify access tokens from oauth.issuer ${String(gate.metadata.authorization_servers[0])}: ${problem}`,
+          "check the issuer (supabaseAuth() needs the project's OAuth server enabled and asymmetric JWT signing keys); until then MCP clients get 503"
+        )
+      );
+    });
+  }
+  let coldStartLogged = false;
   let kbPromise = null;
+  let docCount = 0;
   const getKb = () => {
     kbPromise ??= (async () => {
       const mainModule = globalThis.Deno?.mainModule;
       if (!mainModule) return KnowledgeBase.build([]);
       try {
-        return KnowledgeBase.build(await loadDocsFromDeno(cfg.docs, new URL(mainModule)));
+        const docs = await loadDocsFromDeno(cfg.docs, new URL(mainModule));
+        docCount = docs.length;
+        return KnowledgeBase.build(docs);
       } catch {
         return KnowledgeBase.build([]);
       }
@@ -657,6 +780,14 @@ function aiReady(options = {}) {
         const incoming = req.headers;
         const headers = buildPostgrestHeaders(resolvedAuth.get(req) ?? incoming, anonKey);
         const ladder = await getLadder(postgrestUrl);
+        const kb = await getKb();
+        if (!coldStartLogged) {
+          coldStartLogged = true;
+          try {
+            logColdStart({ ladder, cfg, docs: docCount, endpoint, auth: authLabel, logReady });
+          } catch {
+          }
+        }
         const client = createPostgrestClient(postgrestUrl, headers, fetchImpl);
         const invokeFunction = async (name, body) => {
           const res = await fetchImpl(`${supabaseUrl.replace(/\/+$/, "")}/functions/v1/${name}`, {
@@ -673,7 +804,7 @@ function aiReady(options = {}) {
           cfg,
           client,
           openapi: ladder.openapi,
-          kb: await getKb(),
+          kb,
           incoming,
           invokeFunction,
           warnings: ladder.warnings
@@ -682,12 +813,19 @@ function aiReady(options = {}) {
     },
     { rateLimit: cfg.rateLimit, rateWindowMs: cfg.rateWindowMs }
   );
+  if (gate) {
+    return async (req) => {
+      if (new URL(req.url).pathname.endsWith(PRM_SUFFIX)) return gate.metadataResponse(req.method);
+      const result = await gate.check(req.headers);
+      return result.ok ? core(req) : result.response;
+    };
+  }
   const auth = options.auth;
   if (!auth) return core;
   return async (req) => {
     let resolved;
     try {
-      resolved = await auth(req.headers);
+      resolved = await auth(req.headers, {});
     } catch (err) {
       console.error("exposify-supabase: auth resolver failed", err);
       return Response.json({ error: "internal MCP server error" }, { status: 503 });
@@ -709,5 +847,6 @@ export {
   fetchOpenApi,
   introspectTables,
   loadManifest,
-  rpcArgSchema
+  rpcArgSchema,
+  supabaseAuth
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exposify/supabase",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -27,12 +27,13 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@exposify/core": "0.3.11",
+    "@exposify/core": "0.3.12",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "jose": "^6.1.3",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"