@exposify/express 0.3.7 → 0.3.9

package/dist/index.js

@@ -6,19 +6,40 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/index.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import {
-  resolveOptions
+  countTools,
+  createBrokerGate,
+  createOAuthGate,
+  describeAuth,
+  formatFailed,
+  formatReady,
+  formatWarning,
+  fieldKind,
+  handleLoginPage,
+  hostedResolverInfo,
+  loginResultFromResponse,
+  publicRequestUrl,
+  reportAppLogin,
+  resolveOptions,
+  routeToolsPhrase,
+  startupLogEnabled
 } from "@exposify/core";
 import {
   createNodeMcpHandler,
+  loadDocsFromFs as loadDocsFromFs2,
   loadOrBuildKb
 } from "@exposify/core/node";
 
 // src/surface.ts
-import { readFile } from "fs/promises";
-import { join } from "path";
-import { inject } from "light-my-request";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2 } from "path";
+import { AsyncLocalStorage } from "async_hooks";
+import { randomBytes, timingSafeEqual } from "crypto";
+import {
+  createServer,
+  request as httpRequest
+} from "http";
 import { loadDocsFromFs } from "@exposify/core/node";
 
 // src/introspect.ts
@@ -42,6 +63,7 @@ function installMountRecorder(routerCtor) {
     const wrapper = function(...args) {
       try {
         recordUse(this, args);
+        recordTaggedOwner(this, args);
       } catch {
       }
       return originalUse.apply(this, args);
@@ -51,6 +73,21 @@ function installMountRecorder(routerCtor) {
   } catch {
   }
 }
+var MOUNT_OWNER_TAG = /* @__PURE__ */ Symbol.for("exposify.express.recordMountOwner");
+var taggedOwners = /* @__PURE__ */ new WeakMap();
+function recordTaggedOwner(parent, args) {
+  const stack = [...args];
+  while (stack.length > 0) {
+    const arg = stack.pop();
+    if (Array.isArray(arg)) stack.push(...arg);
+    else if (typeof arg === "function" && arg[MOUNT_OWNER_TAG]) {
+      if (!taggedOwners.has(arg)) taggedOwners.set(arg, parent);
+    }
+  }
+}
+function getMountOwner(fn) {
+  return taggedOwners.get(fn);
+}
 function getRecordedMounts(handle) {
   if (typeof handle !== "function") return void 0;
   return recordedMounts.get(handle);
@@ -115,6 +152,7 @@ function flattenHandlers(items) {
 }
 
 // src/introspect.ts
+var routeHandlers = /* @__PURE__ */ new WeakMap();
 function routesFromExpress(app, opts) {
   const router = routerOf(app);
   const out = [];
@@ -167,13 +205,15 @@ function walk(stack, prefix, owner, out, walked, unresolved) {
         const marker = handlers.map(getMarker).find(Boolean);
         for (const [method, enabled] of Object.entries(layer.route.methods)) {
           if (!enabled || method === "_all") continue;
-          out.push({
+          const route = {
             method: method.toUpperCase(),
             path,
             params: extractParams(path),
             marker,
             description: marker?.kind === "described" ? marker.description : void 0
-          });
+          };
+          routeHandlers.set(route, handlers);
+          out.push(route);
         }
         continue;
       }
@@ -258,59 +298,305 @@ function ownerAndStackOf(handle) {
   return void 0;
 }
 
+// src/descriptions.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { DESCRIPTIONS_FILE, parseDescriptions } from "@exposify/core";
+import { applyDescriptions } from "@exposify/core";
+async function loadDescriptions(cwd, option, warn) {
+  if (option === false) return /* @__PURE__ */ new Map();
+  const path = join(cwd, option ?? DESCRIPTIONS_FILE);
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    if (option !== void 0) warn(`descriptions file not found: ${path}`);
+    return /* @__PURE__ */ new Map();
+  }
+  const parsed = parseDescriptions(text);
+  if (typeof parsed === "string") {
+    warn(`ignoring ${path}: ${parsed}`);
+    return /* @__PURE__ */ new Map();
+  }
+  return new Map(Object.entries(parsed.descriptions).map(([key, entry]) => [key, entry.text.trim()]));
+}
+async function loadOpenApi(cwd, option, warn) {
+  if (option === void 0) return void 0;
+  if (typeof option === "object") return option;
+  const path = join(cwd, option);
+  if (/\.ya?ml$/i.test(path)) {
+    warn(`openapi: YAML isn't supported (${path}); pass the parsed document object or a .json file`);
+    return void 0;
+  }
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (err) {
+    warn(`openapi: couldn't read ${path}: ${err.message}`);
+    return void 0;
+  }
+}
+
 // src/surface.ts
+import { applyOpenApi } from "@exposify/core";
+var warnOnce = (m) => console.warn(`[agentready] warning: ${m}`);
+var NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+var IDENTITY_HEADERS = ["host", "forwarded", "x-forwarded-for", "x-forwarded-proto", "x-forwarded-host", "x-forwarded-port"];
+var DISPATCH_HEADER = "x-exposify-dispatch";
+var callerStore = new AsyncLocalStorage();
+function callerOf(req) {
+  const headers = {};
+  for (const name of IDENTITY_HEADERS) {
+    const value = req.headers[name];
+    if (typeof value === "string") headers[name] = value;
+    else if (Array.isArray(value)) headers[name] = value.join(", ");
+  }
+  const socket = req.socket;
+  return {
+    remoteAddress: socket.remoteAddress,
+    remoteFamily: socket.remoteFamily,
+    encrypted: socket.encrypted === true,
+    headers
+  };
+}
+function runAsCaller(caller, fn) {
+  return callerStore.run(caller, fn);
+}
 async function buildExpressSurface(app, cfg, cwd, opts) {
   const info = await readPackageInfo(cwd);
-  const appish = app;
-  if (!appish.request || !appish.response) {
-    console.warn(
-      "[agentready] express request/response prototypes not found; light-my-request corruption guard inactive"
-    );
-  }
-  const reqProto = appish.request ? Object.getPrototypeOf(appish.request) : void 0;
-  const resProto = appish.response ? Object.getPrototypeOf(appish.response) : void 0;
-  const pristineReqProto = reqProto ? Object.getPrototypeOf(reqProto) : void 0;
-  const pristineResProto = resProto ? Object.getPrototypeOf(resProto) : void 0;
   return {
     info,
-    routes: routesFromExpress(app, opts),
+    // Text precedence: describe() in code > exposify.descriptions.json (reviewed) > OpenAPI > derived.
+    routes: applyDescriptions(
+      applyOpenApi(routesFromExpress(app, opts), await loadOpenApi(cwd, opts?.openapi, warnOnce)),
+      await loadDescriptions(cwd, opts?.descriptions, warnOnce)
+    ),
     docs: await loadDocsFromFs(cfg.docs, cwd),
-    async dispatch(req) {
-      const url = new URL(req.url);
-      try {
-        const res = await inject(app, {
-          method: req.method,
-          url: url.pathname + url.search,
-          headers: Object.fromEntries(req.headers.entries()),
-          payload: req.body ? await req.text() : void 0
-        });
-        return new Response(res.body, {
-          status: res.statusCode,
-          headers: res.headers
-        });
-      } finally {
-        if (pristineReqProto && reqProto) Object.setPrototypeOf(reqProto, pristineReqProto);
-        if (pristineResProto && resProto) Object.setPrototypeOf(resProto, pristineResProto);
-      }
+    dispatch: appDispatcher(app)
+  };
+}
+var dispatchers = /* @__PURE__ */ new WeakMap();
+function appDispatcher(app) {
+  const known = dispatchers.get(app);
+  if (known) return known;
+  const loopback = lazyLoopback(app);
+  const dispatch = async (req) => {
+    const url = new URL(req.url);
+    const payload = req.body ? Buffer.from(await req.arrayBuffer()) : void 0;
+    const caller = callerStore.getStore();
+    const headers = {
+      ...caller?.headers ?? {},
+      ...Object.fromEntries(req.headers.entries())
+    };
+    if (payload) headers["content-length"] = String(payload.length);
+    const { port, tag, release } = await loopback(caller);
+    headers[DISPATCH_HEADER] = tag;
+    const res = await new Promise((resolve, reject) => {
+      const outgoing = httpRequest(
+        { host: "127.0.0.1", port, method: req.method, path: url.pathname + url.search, headers, agent: false },
+        resolve
+      );
+      outgoing.on("error", reject);
+      outgoing.end(payload);
+    }).catch((err) => {
+      release();
+      throw err;
+    });
+    const chunks = [];
+    for await (const chunk of res) chunks.push(chunk);
+    const responseHeaders = new Headers();
+    for (const [name, value] of Object.entries(res.headers)) {
+      if (Array.isArray(value)) for (const v of value) responseHeaders.append(name, v);
+      else if (value !== void 0) responseHeaders.set(name, value);
     }
+    const status = res.statusCode ?? 502;
+    return new Response(NULL_BODY_STATUSES.has(status) ? null : Buffer.concat(chunks), {
+      status,
+      headers: responseHeaders
+    });
+  };
+  dispatchers.set(app, dispatch);
+  return dispatch;
+}
+function lazyLoopback(app) {
+  const secret = randomBytes(32);
+  const pending = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  let port = null;
+  const listener = (req, res) => {
+    const raw = req.headers[DISPATCH_HEADER];
+    delete req.headers[DISPATCH_HEADER];
+    for (let i = req.rawHeaders.length - 2; i >= 0; i -= 2) {
+      if (req.rawHeaders[i].toLowerCase() === DISPATCH_HEADER) req.rawHeaders.splice(i, 2);
+    }
+    const [key, id] = typeof raw === "string" ? raw.split(".") : [];
+    const presented = Buffer.from(key ?? "", "hex");
+    if (!id || presented.length !== secret.length || !timingSafeEqual(presented, secret) || !pending.has(id)) {
+      res.writeHead(403).end();
+      return;
+    }
+    const caller = pending.get(id);
+    pending.delete(id);
+    if (caller) {
+      const socket = req.socket;
+      Object.defineProperty(socket, "remoteAddress", { value: caller.remoteAddress, configurable: true });
+      Object.defineProperty(socket, "remoteFamily", { value: caller.remoteFamily, configurable: true });
+      if (caller.encrypted) Object.defineProperty(socket, "encrypted", { value: true, configurable: true });
+    }
+    app(req, res);
+  };
+  return async (caller) => {
+    port ??= new Promise((resolve, reject) => {
+      const server = createServer(listener);
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        server.unref();
+        resolve(server.address().port);
+      });
+    }).catch((err) => {
+      port = null;
+      throw err;
+    });
+    const resolved = await port;
+    const id = String(nextId++);
+    pending.set(id, caller);
+    return { port: resolved, tag: `${secret.toString("hex")}.${id}`, release: () => pending.delete(id) };
   };
 }
 async function readPackageInfo(cwd) {
   try {
-    const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(await readFile2(join2(cwd, "package.json"), "utf8"));
     return { name: pkg.name ?? "app", version: pkg.version ?? "0.0.0" };
   } catch {
     return { name: "app", version: "0.0.0" };
   }
 }
 
+// src/login.ts
+import { LOGIN_NAME, NOT_A_LOGIN, loginFields } from "@exposify/core";
+var SESSION_CODE = /\bres\.cookie\(|\.session\b|\.login\(|\blogIn\(|set-cookie|setHeader\(\s*["']set-cookie|\bjwt\.sign\(|new\s+SignJWT|\bsign\(|createSession|issueToken|generateToken/i;
+function bodyFieldsOf(source) {
+  const names = /* @__PURE__ */ new Set();
+  for (const m of source.matchAll(/\b\w+\.body\.([A-Za-z_$][\w$]*)/g)) names.add(m[1]);
+  for (const m of source.matchAll(/\b\w+\.body\[\s*["'`]([^"'`]+)["'`]\s*\]/g)) names.add(m[1]);
+  for (const m of source.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=\s*\w+\.body\b/g)) {
+    for (const part of m[1].split(",")) {
+      const name = part.split(/[:=]/)[0].trim().replace(/^\.\.\./, "");
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+  return [...names];
+}
+function sourceOf(fn) {
+  try {
+    return typeof fn === "function" ? Function.prototype.toString.call(fn) : "";
+  } catch {
+    return "";
+  }
+}
+function parsesJson(app) {
+  const stack = (app?._router ?? app?.router)?.stack;
+  if (!Array.isArray(stack)) return null;
+  const names = stack.map((l) => l.name ?? "");
+  if (names.includes("jsonParser")) return true;
+  if (names.includes("urlencodedParser")) return false;
+  return null;
+}
+function findExpressLogin(app, mounts) {
+  let routes;
+  try {
+    routes = routesFromExpress(app, { mounts });
+  } catch {
+    return null;
+  }
+  const candidates = [];
+  for (const route of routes) {
+    if (route.method !== "POST" || route.params.length > 0 || NOT_A_LOGIN.test(route.path)) continue;
+    const handlers = routeHandlers.get(route) ?? [];
+    const own = sourceOf(handlers.at(-1));
+    const all = handlers.map(sourceOf).join("\n");
+    const fields = loginFields(bodyFieldsOf(own));
+    if (!fields) continue;
+    const named = LOGIN_NAME.test(route.path);
+    if (!named && !SESSION_CODE.test(all)) continue;
+    candidates.push({ login: { path: route.path, fields, body: parsesJson(app) === false ? "form" : "json" }, named });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => Number(b.named) - Number(a.named) || a.login.fields.length - b.login.fields.length);
+  return { login: candidates[0].login, others: candidates.slice(1).map((c) => `POST ${c.login.path}`) };
+}
+
 // src/index.ts
-import { exposed, hidden, describe } from "@exposify/core";
+import {
+  exposed,
+  hidden,
+  describe,
+  completeMcpLogin,
+  createHostedAuthResolver,
+  hostedBroker
+} from "@exposify/core";
+var AIREADY_OPTIONS_TAG = /* @__PURE__ */ Symbol.for("exposify.express.aiReadyOptions");
 var MCP_PATH = "/mcp";
+var PRM_ROOT = "/.well-known/oauth-protected-resource";
+var LOG_PREFIX = "[agentready]";
+function toolsSummary(routes, docs, cfg) {
+  const counts = countTools(routes, cfg);
+  const details = counts.hiddenWrites > 0 ? [`${counts.hiddenWrites} write route${counts.hiddenWrites === 1 ? "" : "s"} hidden (opt in with exposed())`] : [];
+  if (cfg.expose === "*") details.unshift('all write routes exposed (expose: "*")');
+  return { tools: routeToolsPhrase(counts, docs), details, empty: counts.reads + counts.writes === 0 };
+}
+var NO_TOOLS_FIX = "register app.use(aiReady()) before your routers, list routers mounted earlier in the `mounts` option, or check whether routes are added later (e.g. after an await) -- those appear on the first /mcp request";
+function prmPaths(resource) {
+  const resourcePath = new URL(resource).pathname;
+  return /* @__PURE__ */ new Set([PRM_ROOT, `${PRM_ROOT}${MCP_PATH}`, resourcePath === "/" ? PRM_ROOT : `${PRM_ROOT}${resourcePath}`]);
+}
+async function sendWebResponse(res, response) {
+  const body = response.body ? await response.text() : void 0;
+  res.writeHead(response.status, Object.fromEntries(response.headers)).end(body);
+}
 function aiReady(options = {}) {
   const cfg = resolveOptions(options);
+  const gate = cfg.oauth ? createOAuthGate(cfg.oauth) : null;
+  const metadataPaths = cfg.oauth ? prmPaths(cfg.oauth.resource) : /* @__PURE__ */ new Set();
+  const brokerGate = !gate && cfg.docsAuth === "required" ? createBrokerGate(cfg.auth) : null;
+  const resourceOf = (req, path, mcpPath) => {
+    const original = String(req.originalUrl ?? req.url).split("?")[0];
+    const prefix = original.endsWith(path) ? original.slice(0, original.length - path.length) : "";
+    const local = `${req.protocol ?? "http"}://${req.headers.host ?? "localhost"}${prefix}${mcpPath}`;
+    return brokerGate.resourceFor(publicRequestUrl(local, headersOf(req)));
+  };
   const cwd = options.cwd ?? process.cwd();
   const mounts = options.mounts;
+  const brokerInfo = hostedResolverInfo(cfg.auth);
+  let loginFound = null;
+  const loginOf = (app) => {
+    if (!brokerInfo || options.login === false) return null;
+    if (!loginFound) {
+      const given = options.login;
+      const value = given ? { path: given.path, fields: given.fields.map((name) => ({ name, kind: fieldKind(name) })), body: given.body ?? "json" } : findExpressLogin(app, mounts)?.login ?? null;
+      loginFound = { value };
+      if (value) {
+        cfg.signedOutPaths = [value.path];
+        if (logReady) console.log(`${LOG_PREFIX} AI assistants sign in with your app's own login (POST ${value.path}) at ${MCP_PATH}/login`);
+      }
+    }
+    return loginFound.value;
+  };
+  const appLoginFor = (req, login) => ({
+    label: `POST ${login.path}`,
+    fields: login.fields,
+    signedOutPaths: [login.path],
+    attempt: (values) => {
+      const body = login.body === "form" ? new URLSearchParams(values).toString() : JSON.stringify(values);
+      const request = new Request(`http://app.internal${login.path}`, {
+        method: "POST",
+        headers: { "content-type": login.body === "form" ? "application/x-www-form-urlencoded" : "application/json", ...req.headers["user-agent"] ? { "user-agent": String(req.headers["user-agent"]) } : {} },
+        body
+      });
+      return runAsCaller(callerOf(req), () => appDispatcher(req.app)(request)).then(loginResultFromResponse);
+    }
+  });
+  const descriptions = options.descriptions;
+  const openapi = options.openapi;
   try {
     installMountRecorder();
   } catch {
@@ -318,45 +604,208 @@ function aiReady(options = {}) {
   let handlerPromise = null;
   let disabled = false;
   let warned = false;
-  return (req, res, next) => {
+  const logReady = startupLogEnabled(options.startupLog);
+  const auth = describeAuth(cfg.auth, cfg.oauth);
+  let reported = null;
+  const logSurface = (routes, docs, note) => {
+    const summary = toolsSummary(routes, docs, cfg);
+    const key = [summary.tools, ...summary.details, docs].join("|");
+    if (key === reported) return;
+    const first = reported === null;
+    reported = key;
+    if (summary.empty) {
+      console.warn(formatWarning(LOG_PREFIX, `MCP is up at ${MCP_PATH} but exposes no route tools`, NO_TOOLS_FIX));
+      return;
+    }
+    if (!logReady) return;
+    const details = [...summary.details, ...note && !first ? [note] : []];
+    console.log(formatReady(LOG_PREFIX, { endpoint: MCP_PATH, tools: summary.tools, details, docs, auth }));
+  };
+  const middleware = (req, res, next) => {
     const path = req.path ?? req.url.split("?")[0];
+    if (brokerInfo && (path === `${MCP_PATH}/login` || path === `${MCP_PATH}/login/`)) {
+      const login = loginOf(req.app);
+      if (!login) return next();
+      void serveLoginPage(req, res, login).catch((err) => {
+        console.warn("[agentready] sign-in form failed:", err);
+        if (!res.headersSent) res.writeHead(503).end("sign-in is unavailable");
+      });
+      return;
+    }
+    if (gate && metadataPaths.has(path)) {
+      void sendWebResponse(res, gate.metadataResponse(req.method));
+      return;
+    }
+    if (brokerGate && (path === PRM_ROOT || path === `${PRM_ROOT}${MCP_PATH}`)) {
+      const resource = resourceOf(req, path, MCP_PATH);
+      void reportAppLogin(cfg.auth, resource, loginOf(req.app)).then(() => sendWebResponse(res, brokerGate.metadataResponse(req.method, resource)));
+      return;
+    }
     if (path !== MCP_PATH && !path.startsWith(`${MCP_PATH}/`)) return next();
     if (disabled) {
       res.writeHead(503).end("agentready is disabled due to an internal error");
       return;
     }
-    handlerPromise ??= initialize(req.app, cfg, cwd, mounts);
-    handlerPromise.then((handler) => handler(req, res)).catch((err) => {
+    const authorized = gate ? gate.check(headersOf(req)).then(async (result) => {
+      if (result.ok) return { claims: result.claims };
+      await sendWebResponse(res, result.response);
+      return null;
+    }, (err) => {
+      console.warn("[agentready] oauth gate failed:", err);
+      if (!res.headersSent) res.writeHead(503).end("authorization check failed");
+      return null;
+    }) : brokerGate ? reportAppLogin(cfg.auth, resourceOf(req, path, MCP_PATH), loginOf(req.app)).then(() => brokerGate.check(headersOf(req), resourceOf(req, path, MCP_PATH))).then(async (result) => {
+      if (result.ok) return {};
+      await sendWebResponse(res, result.response);
+      return null;
+    }, (err) => {
+      console.warn("[agentready] broker check failed:", err);
+      if (!res.headersSent) res.writeHead(503).end("authorization check failed");
+      return null;
+    }) : Promise.resolve({});
+    authorized.then((authContext) => {
+      if (!authContext) return;
+      handlerPromise ??= initialize(
+        req.app,
+        cfg,
+        cwd,
+        mounts,
+        { descriptions, openapi },
+        (surface) => logSurface(surface.routes, surface.docs.length, "updated: routes registered after startup")
+      );
+      return handlerPromise.then(
+        (handler) => (
+          // Tool calls made while handling this request reach the app with
+          // this caller's address and forwarding headers (see surface.ts).
+          runAsCaller(callerOf(req), () => handler(req, res, authContext))
+        )
+      );
+    }).catch((err) => {
       disabled = true;
       handlerPromise = null;
       if (!warned) {
         warned = true;
-        console.warn("[agentready] disabled after internal error:", err);
+        console.error(
+          formatFailed(
+            LOG_PREFIX,
+            errorMessage(err),
+            `${MCP_PATH} now answers 503 until the process restarts (your own routes are unaffected); full error below`
+          ),
+          err
+        );
       }
       if (!res.headersSent) res.writeHead(503).end("agentready failed to initialize");
     });
   };
+  async function serveLoginPage(req, res, login) {
+    const original = String(req.originalUrl ?? req.url);
+    const local = `${req.protocol ?? "http"}://${req.headers.host ?? "localhost"}${original}`;
+    const url = new URL(publicRequestUrl(local, headersOf(req)));
+    url.search = new URL(local).search;
+    let body;
+    if (req.method === "POST") {
+      if (req.body && typeof req.body === "object" && Object.keys(req.body).length > 0) body = new URLSearchParams(req.body).toString();
+      else if (typeof req.body === "string") body = req.body;
+      else {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+          size += chunk.length;
+          if (size > 16 * 1024) break;
+          chunks.push(chunk);
+        }
+        body = Buffer.concat(chunks).toString("utf8");
+      }
+    }
+    const request = new Request(url, { method: req.method, headers: headersOf(req), ...body !== void 0 ? { body } : {} });
+    const forwarded = String(req.headers["x-forwarded-for"] ?? "").split(",")[0]?.trim();
+    const ip = forwarded || req.socket?.remoteAddress;
+    const response = await handleLoginPage(request, appLoginFor(req, login), brokerInfo, {
+      path: url.pathname,
+      secure: url.protocol === "https:",
+      origin: url.origin,
+      ...ip ? { ip } : {}
+    });
+    await sendWebResponse(res, response);
+  }
+  middleware[MOUNT_OWNER_TAG] = true;
+  middleware[AIREADY_OPTIONS_TAG] = options;
+  setImmediate(() => {
+    void startupCheck().catch(() => {
+    });
+  });
+  async function startupCheck() {
+    const owner = getMountOwner(middleware);
+    if (!owner) {
+      return;
+    }
+    const probe = gate ? gate.probe() : Promise.resolve(null);
+    try {
+      const routes = routesFromExpress({ _router: owner }, { mounts });
+      const docs = await loadDocsFromFs2(cfg.docs, cwd);
+      logSurface(routes, docs.length);
+    } catch (err) {
+      console.error(
+        formatFailed(
+          LOG_PREFIX,
+          errorMessage(err),
+          `your app keeps serving its own routes; ${MCP_PATH} will retry on its first request and answer 503 if it fails again`
+        ),
+        err
+      );
+    }
+    const problem = await probe;
+    if (problem && cfg.oauth) {
+      console.warn(
+        formatWarning(
+          LOG_PREFIX,
+          `can't verify access tokens from oauth.issuer ${cfg.oauth.issuer}: ${problem}`,
+          "make oauth.issuer match the tokens' `iss` exactly (trailing slash included) and check it's reachable from this server; until then MCP clients get 503"
+        )
+      );
+    }
+  }
+  return middleware;
 }
-async function initialize(app, cfg, cwd, mounts) {
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function headersOf(req) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") headers.set(name, value);
+    else if (Array.isArray(value)) headers.set(name, value.join(", "));
+  }
+  return headers;
+}
+async function initialize(app, cfg, cwd, mounts, extras, onReady) {
   let surface = null;
   let kbPromise = null;
   const getSurface = async () => {
-    surface ??= await buildExpressSurface(app, cfg, cwd, { mounts });
+    surface ??= await buildExpressSurface(app, cfg, cwd, { mounts, ...extras });
     return surface;
   };
   const getKb = async () => {
     const s = await getSurface();
-    kbPromise ??= loadOrBuildKb(s.docs, join2(cwd, ".exposify"));
+    kbPromise ??= loadOrBuildKb(s.docs, join3(cwd, ".exposify"));
     return kbPromise;
   };
-  await getSurface();
+  const built = await getSurface();
   await getKb();
+  try {
+    onReady(built);
+  } catch {
+  }
   return createNodeMcpHandler({ getSurface, getKb, cfg });
 }
 export {
+  AIREADY_OPTIONS_TAG,
   aiReady,
+  completeMcpLogin,
+  createHostedAuthResolver,
   describe,
   exposed,
   hidden,
+  hostedBroker,
   routesFromExpress
 };