@exposify/express 0.3.8 → 0.3.9

package/dist/index.js

@@ -6,14 +6,21 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/index.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import {
   countTools,
+  createBrokerGate,
   createOAuthGate,
   describeAuth,
   formatFailed,
   formatReady,
   formatWarning,
+  fieldKind,
+  handleLoginPage,
+  hostedResolverInfo,
+  loginResultFromResponse,
+  publicRequestUrl,
+  reportAppLogin,
   resolveOptions,
   routeToolsPhrase,
   startupLogEnabled
@@ -25,9 +32,14 @@ import {
 } 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
@@ -140,6 +152,7 @@ function flattenHandlers(items) {
 }
 
 // src/introspect.ts
+var routeHandlers = /* @__PURE__ */ new WeakMap();
 function routesFromExpress(app, opts) {
   const router = routerOf(app);
   const out = [];
@@ -192,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;
       }
@@ -283,60 +298,250 @@ 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";
@@ -352,8 +557,46 @@ 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 {
@@ -380,10 +623,24 @@ function aiReady(options = {}) {
   };
   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");
@@ -397,6 +654,14 @@ function aiReady(options = {}) {
       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;
@@ -405,9 +670,16 @@ 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;
@@ -425,7 +697,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(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(() => {
     });
@@ -474,16 +778,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 ??= loadOrBuildKb(s.docs, join2(cwd, ".exposify"));
+    kbPromise ??= loadOrBuildKb(s.docs, join3(cwd, ".exposify"));
     return kbPromise;
   };
   const built = await getSurface();
@@ -495,9 +799,13 @@ async function initialize(app, cfg, cwd, mounts, onReady) {
   return createNodeMcpHandler({ getSurface, getKb, cfg });
 }
 export {
+  AIREADY_OPTIONS_TAG,
   aiReady,
+  completeMcpLogin,
+  createHostedAuthResolver,
   describe,
   exposed,
   hidden,
+  hostedBroker,
   routesFromExpress
 };