@exposify/express 0.3.8 → 0.3.9

package/dist/index.cjs

@@ -20,21 +20,27 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AIREADY_OPTIONS_TAG: () => AIREADY_OPTIONS_TAG,
   aiReady: () => aiReady,
-  describe: () => import_core3.describe,
-  exposed: () => import_core3.exposed,
-  hidden: () => import_core3.hidden,
+  completeMcpLogin: () => import_core7.completeMcpLogin,
+  createHostedAuthResolver: () => import_core7.createHostedAuthResolver,
+  describe: () => import_core7.describe,
+  exposed: () => import_core7.exposed,
+  hidden: () => import_core7.hidden,
+  hostedBroker: () => import_core7.hostedBroker,
   routesFromExpress: () => routesFromExpress
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_path2 = require("path");
-var import_core2 = require("@exposify/core");
+var import_node_path3 = require("path");
+var import_core6 = require("@exposify/core");
 var import_node2 = require("@exposify/core/node");
 
 // src/surface.ts
-var import_promises = require("fs/promises");
-var import_node_path = require("path");
-var import_light_my_request = require("light-my-request");
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+var import_node_async_hooks = require("async_hooks");
+var import_node_crypto = require("crypto");
+var import_node_http = require("http");
 var import_node = require("@exposify/core/node");
 
 // src/introspect.ts
@@ -148,6 +154,7 @@ function flattenHandlers(items) {
 }
 
 // src/introspect.ts
+var routeHandlers = /* @__PURE__ */ new WeakMap();
 function routesFromExpress(app, opts) {
   const router = routerOf(app);
   const out = [];
@@ -200,13 +207,15 @@ function walk(stack, prefix, owner, out, walked, unresolved) {
         const marker = handlers.map(import_core.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;
       }
@@ -291,61 +300,244 @@ function ownerAndStackOf(handle) {
   return void 0;
 }
 
+// src/descriptions.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_core2 = require("@exposify/core");
+var import_core3 = require("@exposify/core");
+async function loadDescriptions(cwd, option, warn) {
+  if (option === false) return /* @__PURE__ */ new Map();
+  const path = (0, import_node_path.join)(cwd, option ?? import_core2.DESCRIPTIONS_FILE);
+  let text;
+  try {
+    text = await (0, import_promises.readFile)(path, "utf8");
+  } catch {
+    if (option !== void 0) warn(`descriptions file not found: ${path}`);
+    return /* @__PURE__ */ new Map();
+  }
+  const parsed = (0, import_core2.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 = (0, import_node_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 (0, import_promises.readFile)(path, "utf8"));
+  } catch (err) {
+    warn(`openapi: couldn't read ${path}: ${err.message}`);
+    return void 0;
+  }
+}
+
 // src/surface.ts
+var import_core4 = require("@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 import_node_async_hooks.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: (0, import_core3.applyDescriptions)(
+      (0, import_core4.applyOpenApi)(routesFromExpress(app, opts), await loadOpenApi(cwd, opts?.openapi, warnOnce)),
+      await loadDescriptions(cwd, opts?.descriptions, warnOnce)
+    ),
     docs: await (0, import_node.loadDocsFromFs)(cfg.docs, cwd),
-    async dispatch(req) {
-      const url = new URL(req.url);
-      try {
-        const res = await (0, import_light_my_request.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 = (0, import_node_http.request)(
+        { 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 = (0, import_node_crypto.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 || !(0, import_node_crypto.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 = (0, import_node_http.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 (0, import_promises.readFile)((0, import_node_path.join)(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(await (0, import_promises2.readFile)((0, import_node_path2.join)(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
+var import_core5 = require("@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 || import_core5.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 = (0, import_core5.loginFields)(bodyFieldsOf(own));
+    if (!fields) continue;
+    const named = import_core5.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
-var import_core3 = require("@exposify/core");
+var import_core7 = require("@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 = (0, import_core2.countTools)(routes, cfg);
+  const counts = (0, import_core6.countTools)(routes, cfg);
   const details = counts.hiddenWrites > 0 ? [`${counts.hiddenWrites} write route${counts.hiddenWrites === 1 ? "" : "s"} hidden (opt in with exposed())`] : [];
-  return { tools: (0, import_core2.routeToolsPhrase)(counts, docs), details, empty: counts.reads + counts.writes === 0 };
+  if (cfg.expose === "*") details.unshift('all write routes exposed (expose: "*")');
+  return { tools: (0, import_core6.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) {
@@ -357,11 +549,49 @@ async function sendWebResponse(res, response) {
   res.writeHead(response.status, Object.fromEntries(response.headers)).end(body);
 }
 function aiReady(options = {}) {
-  const cfg = (0, import_core2.resolveOptions)(options);
-  const gate = cfg.oauth ? (0, import_core2.createOAuthGate)(cfg.oauth) : null;
+  const cfg = (0, import_core6.resolveOptions)(options);
+  const gate = cfg.oauth ? (0, import_core6.createOAuthGate)(cfg.oauth) : null;
   const metadataPaths = cfg.oauth ? prmPaths(cfg.oauth.resource) : /* @__PURE__ */ new Set();
+  const brokerGate = !gate && cfg.docsAuth === "required" ? (0, import_core6.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((0, import_core6.publicRequestUrl)(local, headersOf(req)));
+  };
   const cwd = options.cwd ?? process.cwd();
   const mounts = options.mounts;
+  const brokerInfo = (0, import_core6.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: (0, import_core6.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(import_core6.loginResultFromResponse);
+    }
+  });
+  const descriptions = options.descriptions;
+  const openapi = options.openapi;
   try {
     installMountRecorder();
   } catch {
@@ -369,8 +599,8 @@ function aiReady(options = {}) {
   let handlerPromise = null;
   let disabled = false;
   let warned = false;
-  const logReady = (0, import_core2.startupLogEnabled)(options.startupLog);
-  const auth = (0, import_core2.describeAuth)(cfg.auth, cfg.oauth);
+  const logReady = (0, import_core6.startupLogEnabled)(options.startupLog);
+  const auth = (0, import_core6.describeAuth)(cfg.auth, cfg.oauth);
   let reported = null;
   const logSurface = (routes, docs, note) => {
     const summary = toolsSummary(routes, docs, cfg);
@@ -379,19 +609,33 @@ function aiReady(options = {}) {
     const first = reported === null;
     reported = key;
     if (summary.empty) {
-      console.warn((0, import_core2.formatWarning)(LOG_PREFIX, `MCP is up at ${MCP_PATH} but exposes no route tools`, NO_TOOLS_FIX));
+      console.warn((0, import_core6.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((0, import_core2.formatReady)(LOG_PREFIX, { endpoint: MCP_PATH, tools: summary.tools, details, docs, auth }));
+    console.log((0, import_core6.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 (0, import_core6.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");
@@ -405,6 +649,14 @@ function aiReady(options = {}) {
       console.warn("[agentready] oauth gate failed:", err);
       if (!res.headersSent) res.writeHead(503).end("authorization check failed");
       return null;
+    }) : brokerGate ? (0, import_core6.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;
@@ -413,16 +665,23 @@ function aiReady(options = {}) {
         cfg,
         cwd,
         mounts,
+        { descriptions, openapi },
         (surface) => logSurface(surface.routes, surface.docs.length, "updated: routes registered after startup")
       );
-      return handlerPromise.then((handler) => handler(req, res, authContext));
+      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.error(
-          (0, import_core2.formatFailed)(
+          (0, import_core6.formatFailed)(
             LOG_PREFIX,
             errorMessage(err),
             `${MCP_PATH} now answers 503 until the process restarts (your own routes are unaffected); full error below`
@@ -433,7 +692,39 @@ function aiReady(options = {}) {
       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((0, import_core6.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 (0, import_core6.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(() => {
     });
@@ -450,7 +741,7 @@ function aiReady(options = {}) {
       logSurface(routes, docs.length);
     } catch (err) {
       console.error(
-        (0, import_core2.formatFailed)(
+        (0, import_core6.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`
@@ -461,7 +752,7 @@ function aiReady(options = {}) {
     const problem = await probe;
     if (problem && cfg.oauth) {
       console.warn(
-        (0, import_core2.formatWarning)(
+        (0, import_core6.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"
@@ -482,16 +773,16 @@ function headersOf(req) {
   }
   return headers;
 }
-async function initialize(app, cfg, cwd, mounts, onReady) {
+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 ??= (0, import_node2.loadOrBuildKb)(s.docs, (0, import_node_path2.join)(cwd, ".exposify"));
+    kbPromise ??= (0, import_node2.loadOrBuildKb)(s.docs, (0, import_node_path3.join)(cwd, ".exposify"));
     return kbPromise;
   };
   const built = await getSurface();
@@ -504,9 +795,13 @@ async function initialize(app, cfg, cwd, mounts, onReady) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AIREADY_OPTIONS_TAG,
   aiReady,
+  completeMcpLogin,
+  createHostedAuthResolver,
   describe,
   exposed,
   hidden,
+  hostedBroker,
   routesFromExpress
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { RouteInfo, AgentReadyOptions } from '@exposify/core';
-export { describe, exposed, hidden } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, describe, exposed, hidden, hostedBroker } from '@exposify/core';
 
 interface RoutesFromExpressOptions {
     /**
@@ -15,7 +15,22 @@ interface RoutesFromExpressOptions {
 }
 declare function routesFromExpress(app: unknown, opts?: RoutesFromExpressOptions): RouteInfo[];
 
+/** Symbol under which `aiReady()`'s middleware carries the options it was given. */
+declare const AIREADY_OPTIONS_TAG: unique symbol;
+
 interface ExpressAiReadyOptions extends AgentReadyOptions {
+    /**
+     * The app's own login, for Connect with the hosted broker: AI assistants
+     * sign in on a form served at /mcp/login, which makes this login request
+     * through your app. Found by itself (a POST route that reads a password
+     * from the body and sets a session or signs a token); name another route
+     * (`{ path, fields }`), or `false` to not offer it.
+     */
+    login?: false | {
+        path: string;
+        fields: string[];
+        body?: "json" | "form";
+    };
     /** Where docs globs and the .exposify cache resolve. Default: process.cwd() */
     cwd?: string;
     /**
@@ -29,7 +44,20 @@ interface ExpressAiReadyOptions extends AgentReadyOptions {
      * router/app object registered at that prefix.
      */
     mounts?: Record<string, unknown>;
+    /**
+     * Tool descriptions file written by `exposify-express setup`/`describe`.
+     * Default: exposify.descriptions.json in `cwd`, if present. `false` ignores it.
+     * describe() text in code still wins over it.
+     */
+    descriptions?: string | false;
+    /**
+     * The app's OpenAPI document: an object (e.g. `SwaggerModule.createDocument(app, …)`
+     * in NestJS) or a path to a JSON file. Matching operations give tools real
+     * input schemas, and their summary/description becomes the tool description
+     * (below describe() and exposify.descriptions.json).
+     */
+    openapi?: string | object;
 }
 declare function aiReady(options?: ExpressAiReadyOptions): (req: any, res: any, next: any) => void;
 
-export { type ExpressAiReadyOptions, aiReady, routesFromExpress };
+export { AIREADY_OPTIONS_TAG, type ExpressAiReadyOptions, aiReady, routesFromExpress };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RouteInfo, AgentReadyOptions } from '@exposify/core';
-export { describe, exposed, hidden } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, describe, exposed, hidden, hostedBroker } from '@exposify/core';
 
 interface RoutesFromExpressOptions {
     /**
@@ -15,7 +15,22 @@ interface RoutesFromExpressOptions {
 }
 declare function routesFromExpress(app: unknown, opts?: RoutesFromExpressOptions): RouteInfo[];
 
+/** Symbol under which `aiReady()`'s middleware carries the options it was given. */
+declare const AIREADY_OPTIONS_TAG: unique symbol;
+
 interface ExpressAiReadyOptions extends AgentReadyOptions {
+    /**
+     * The app's own login, for Connect with the hosted broker: AI assistants
+     * sign in on a form served at /mcp/login, which makes this login request
+     * through your app. Found by itself (a POST route that reads a password
+     * from the body and sets a session or signs a token); name another route
+     * (`{ path, fields }`), or `false` to not offer it.
+     */
+    login?: false | {
+        path: string;
+        fields: string[];
+        body?: "json" | "form";
+    };
     /** Where docs globs and the .exposify cache resolve. Default: process.cwd() */
     cwd?: string;
     /**
@@ -29,7 +44,20 @@ interface ExpressAiReadyOptions extends AgentReadyOptions {
      * router/app object registered at that prefix.
      */
     mounts?: Record<string, unknown>;
+    /**
+     * Tool descriptions file written by `exposify-express setup`/`describe`.
+     * Default: exposify.descriptions.json in `cwd`, if present. `false` ignores it.
+     * describe() text in code still wins over it.
+     */
+    descriptions?: string | false;
+    /**
+     * The app's OpenAPI document: an object (e.g. `SwaggerModule.createDocument(app, …)`
+     * in NestJS) or a path to a JSON file. Matching operations give tools real
+     * input schemas, and their summary/description becomes the tool description
+     * (below describe() and exposify.descriptions.json).
+     */
+    openapi?: string | object;
 }
 declare function aiReady(options?: ExpressAiReadyOptions): (req: any, res: any, next: any) => void;
 
-export { type ExpressAiReadyOptions, aiReady, routesFromExpress };
+export { AIREADY_OPTIONS_TAG, type ExpressAiReadyOptions, aiReady, routesFromExpress };