@exposify/express 0.3.7 → 0.3.8

package/README.md

@@ -17,6 +17,111 @@ credentials (`Authorization`/`Cookie`), forwarded to your routes unchanged.
 There is no separate authorization layer to configure or get wrong — an
 agent can do exactly what the person it's acting for could already do.
 
+## "Click Connect and log in" (OAuth)
+
+By default the MCP client has to be handed a token by hand. If your app's
+auth provider is an OAuth 2.1 authorization server (Auth0, WorkOS, Clerk,
+Okta, Keycloak, Supabase Auth, ...), add `oauth` and MCP clients log in on
+their own:
+
+```ts
+app.use(aiReady({
+  oauth: {
+    issuer: "https://acme.us.auth0.com/",   // exactly the tokens' `iss`
+    resource: "https://api.acme.com/mcp",   // the public MCP URL = required token audience
+    scopes: ["read"],                       // optional
+  },
+}));
+```
+
+The whole `/mcp` endpoint then requires a valid access token. A request
+without one gets `401` + `WWW-Authenticate: Bearer resource_metadata="…"`,
+and Protected Resource Metadata (RFC 9728) is served at
+`/.well-known/oauth-protected-resource[/mcp]`. That is enough for Claude,
+Cursor, etc. to discover your issuer, register, open your real login page
+and refresh tokens later, with nothing for the user to paste. Tokens are
+verified as JWTs against the issuer's JWKS (discovered from its metadata):
+signature, `iss`, `aud` = `resource`, expiry, and `scopes`. An expired
+token is an HTTP `401` (so the client refreshes), and an unreachable
+issuer is a `503`, never a pass.
+
+Then the validated `Authorization` is forwarded to your routes in-process,
+exactly like passthrough.
+
+### One change in your app: accept the MCP audience
+
+MCP tokens are issued for the MCP URL (`aud: "https://api.acme.com/mcp"`),
+and most JWT middleware rejects any audience it wasn't told about. So add
+the MCP URL next to your existing audience. Your web app's tokens keep
+working:
+
+```ts
+const MCP_URL = "https://api.acme.com/mcp";
+app.use(aiReady({ oauth: { issuer: ISSUER, resource: MCP_URL } }));
+
+// express-oauth2-jwt-bearer (Auth0):
+app.use(auth({ issuerBaseURL: ISSUER, audience: ["https://api.acme.com", MCP_URL] }));
+
+// or jose directly:
+await jwtVerify(token, JWKS, { issuer: ISSUER, audience: ["https://api.acme.com", MCP_URL] });
+```
+
+Any other middleware works the same way: pass both values wherever it takes
+the expected audience. On the provider side, the issuer must be willing to
+mint tokens for the MCP URL. In Auth0, for example, add an API whose
+identifier is the MCP URL, and leave your existing API alone.
+
+If you miss this, sign-in still succeeds but every tool call fails. The
+first time your app answers `401` to a token the MCP endpoint already
+validated, `aiReady()` logs one warning naming the audience to add and
+quoting your app's own `WWW-Authenticate` header.
+
+- `resource` is required, never inferred from `Host` (proxies get it
+  wrong). Use your public URL; `http` is only accepted for `localhost`.
+- `audience` overrides the expected `aud` for issuers that can't bind
+  tokens to `resource`. It's weaker: any token for that audience passes,
+  and a warning is logged at startup.
+- `jwksUri` skips metadata discovery. `verify: async (token) => claims | null`
+  replaces JWT verification (opaque tokens, introspection).
+- A custom `auth` resolver receives `(headers, { claims })`, so it can map
+  the validated user to whatever your app expects.
+- `oauth` can't be combined with `docsAuth: "public"` (that throws): clients
+  only start login on a connect-time `401`, so the docs tools are behind
+  the token too.
+- Apps without an OAuth authorization server (session cookies,
+  passport-local, homegrown JWTs) need one first; this package doesn't
+  include one.
+
+## Startup log
+
+On boot (`npm run dev`, or in production), right after your routes
+register, `aiReady()` prints one line saying whether MCP is up:
+
+```
+[agentready] MCP ready at /mcp: 6 tools (4 read, 1 write, search_docs), 1 write route hidden (opt in with exposed()), 2 docs indexed, auth: passthrough
+```
+
+When something's wrong, the line names the problem and a fix instead:
+
+```
+[agentready] MCP failed to start: <reason>
+  fix: <what to do>
+[agentready] warning: MCP is up at /mcp but exposes no route tools
+  fix: register app.use(aiReady()) before your routers, ...
+[agentready] warning: can't verify access tokens from oauth.issuer https://...: <reason>
+  fix: make oauth.issuer match the tokens' `iss` exactly ...
+```
+
+- With `oauth`, the issuer's metadata and keys are fetched once at boot, so
+  a wrong issuer shows up here instead of on the first login.
+- Routes registered later (e.g. after an `await`) are picked up on the first
+  `/mcp` request, which prints an updated line only if the count changed.
+- Failures and warnings always print. The ready line is on by default and
+  off under `NODE_ENV=test`. `startupLog: true | false` overrides that
+  (and also turns the issuer check on or off).
+- The check is read-only and never throws into your app; your own routes
+  keep working either way.
+
 ## Exposure policy
 
 - **Reads (GET/HEAD) are exposed automatically.** Writes are hidden by
@@ -60,11 +165,13 @@ app.use(aiReady({ mounts: { "/legacy": legacyRouter } }));
 
 ```ts
 aiReady({
-  auth?: "passthrough" | "none",        // default "passthrough"
+  auth?: "passthrough" | "none" | AuthResolver, // default "passthrough"
+  oauth?: { issuer, resource, scopes?, audience?, jwksUri?, verify? }, // see above
+  startupLog?: boolean,                  // default on, off under NODE_ENV=test
   docs?: string[],                       // default ["README.md", "docs/**/*.md"]
   expose?: string[] | "*",               // e.g. ["GET /trends"]; default unset
   exclude?: string[],                    // picomatch globs against the route path
-  docsAuth?: "public" | "required",      // default "public"
+  docsAuth?: "public" | "required",      // default "public" ("required" with oauth)
   embedder?: (texts: string[]) => Promise<number[][]>,
   telemetry?: { enabled: boolean; sink?(event): void; capturePayloads?: boolean },
   cwd?: string,                          // default process.cwd()
@@ -84,6 +191,10 @@ default above.
   only works when `aiReady()` is registered *before* the mount. A router
   mounted both before and after `aiReady()` ("straddle" mount) resolves
   correctly on Express 4 but silently drops the earlier prefix on Express 5.
+- With `oauth`, only a global `scopes` set is checked at the edge; per-tool
+  scopes aren't supported (your routes' own `403`s still come back as tool
+  errors). Combining `oauth` with a token-broker resolver isn't supported
+  yet.
 - In-process dispatch uses `light-my-request`, which splices Express's
   process-wide request/response prototypes for the duration of each
   dispatch — a narrow concurrency window under real concurrent traffic, a

package/dist/index.cjs

@@ -59,6 +59,7 @@ function installMountRecorder(routerCtor) {
     const wrapper = function(...args) {
       try {
         recordUse(this, args);
+        recordTaggedOwner(this, args);
       } catch {
       }
       return originalUse.apply(this, args);
@@ -68,6 +69,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);
@@ -324,8 +340,26 @@ async function readPackageInfo(cwd) {
 // src/index.ts
 var import_core3 = require("@exposify/core");
 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 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 };
+}
+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 = (0, import_core2.resolveOptions)(options);
+  const gate = cfg.oauth ? (0, import_core2.createOAuthGate)(cfg.oauth) : null;
+  const metadataPaths = cfg.oauth ? prmPaths(cfg.oauth.resource) : /* @__PURE__ */ new Set();
   const cwd = options.cwd ?? process.cwd();
   const mounts = options.mounts;
   try {
@@ -335,26 +369,120 @@ function aiReady(options = {}) {
   let handlerPromise = null;
   let disabled = false;
   let warned = false;
-  return (req, res, next) => {
+  const logReady = (0, import_core2.startupLogEnabled)(options.startupLog);
+  const auth = (0, import_core2.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((0, import_core2.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 }));
+  };
+  const middleware = (req, res, next) => {
     const path = req.path ?? req.url.split("?")[0];
+    if (gate && metadataPaths.has(path)) {
+      void sendWebResponse(res, gate.metadataResponse(req.method));
+      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;
+    }) : Promise.resolve({});
+    authorized.then((authContext) => {
+      if (!authContext) return;
+      handlerPromise ??= initialize(
+        req.app,
+        cfg,
+        cwd,
+        mounts,
+        (surface) => logSurface(surface.routes, surface.docs.length, "updated: routes registered after startup")
+      );
+      return handlerPromise.then((handler) => handler(req, res, authContext));
+    }).catch((err) => {
       disabled = true;
       handlerPromise = null;
       if (!warned) {
         warned = true;
-        console.warn("[agentready] disabled after internal error:", err);
+        console.error(
+          (0, import_core2.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");
     });
   };
+  middleware[MOUNT_OWNER_TAG] = true;
+  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 (0, import_node2.loadDocsFromFs)(cfg.docs, cwd);
+      logSurface(routes, docs.length);
+    } catch (err) {
+      console.error(
+        (0, import_core2.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(
+        (0, import_core2.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, onReady) {
   let surface = null;
   let kbPromise = null;
   const getSurface = async () => {
@@ -366,8 +494,12 @@ async function initialize(app, cfg, cwd, mounts) {
     kbPromise ??= (0, import_node2.loadOrBuildKb)(s.docs, (0, import_node_path2.join)(cwd, ".exposify"));
     return kbPromise;
   };
-  await getSurface();
+  const built = await getSurface();
   await getKb();
+  try {
+    onReady(built);
+  } catch {
+  }
   return (0, import_node2.createNodeMcpHandler)({ getSurface, getKb, cfg });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js

@@ -8,10 +8,19 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/index.ts
 import { join as join2 } from "path";
 import {
-  resolveOptions
+  countTools,
+  createOAuthGate,
+  describeAuth,
+  formatFailed,
+  formatReady,
+  formatWarning,
+  resolveOptions,
+  routeToolsPhrase,
+  startupLogEnabled
 } from "@exposify/core";
 import {
   createNodeMcpHandler,
+  loadDocsFromFs as loadDocsFromFs2,
   loadOrBuildKb
 } from "@exposify/core/node";
 
@@ -42,6 +51,7 @@ function installMountRecorder(routerCtor) {
     const wrapper = function(...args) {
       try {
         recordUse(this, args);
+        recordTaggedOwner(this, args);
       } catch {
       }
       return originalUse.apply(this, args);
@@ -51,6 +61,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);
@@ -307,8 +332,26 @@ async function readPackageInfo(cwd) {
 // src/index.ts
 import { exposed, hidden, describe } from "@exposify/core";
 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())`] : [];
+  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 cwd = options.cwd ?? process.cwd();
   const mounts = options.mounts;
   try {
@@ -318,26 +361,120 @@ 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 (gate && metadataPaths.has(path)) {
+      void sendWebResponse(res, gate.metadataResponse(req.method));
+      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;
+    }) : Promise.resolve({});
+    authorized.then((authContext) => {
+      if (!authContext) return;
+      handlerPromise ??= initialize(
+        req.app,
+        cfg,
+        cwd,
+        mounts,
+        (surface) => logSurface(surface.routes, surface.docs.length, "updated: routes registered after startup")
+      );
+      return handlerPromise.then((handler) => 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");
     });
   };
+  middleware[MOUNT_OWNER_TAG] = true;
+  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, onReady) {
   let surface = null;
   let kbPromise = null;
   const getSurface = async () => {
@@ -349,8 +486,12 @@ async function initialize(app, cfg, cwd, mounts) {
     kbPromise ??= loadOrBuildKb(s.docs, join2(cwd, ".exposify"));
     return kbPromise;
   };
-  await getSurface();
+  const built = await getSurface();
   await getKb();
+  try {
+    onReady(built);
+  } catch {
+  }
   return createNodeMcpHandler({ getSurface, getKb, cfg });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exposify/express",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,7 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@exposify/core": "0.3.11",
+    "@exposify/core": "0.3.12",
     "light-my-request": "^6.0.0"
   },
   "peerDependencies": {
@@ -36,6 +36,7 @@
     "express": "npm:express@^5.1.0",
     "express4": "npm:express@^4.19.0",
     "express5": "npm:express@^5.1.0",
+    "jose": "^6.1.3",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"