@every-app/sdk 0.3.0-rc.12 → 0.3.0-rc.13

package/dist/internal/remoteMcp.js

@@ -3,34 +3,53 @@
  * (`everyapp mcp add <url>`, Admin → Apps → Add app → "Add an MCP server",
  * `everyapp_mcp_add`), served to members' AI clients as an MCP app of the
  * Gateway's own, like a built-in provider app (./providerApps.ts) but with
- * its tools read from the server and each call forwarded to it with a
- * credential the Gateway holds (docs/design/2026-10-mcp-by-url.md).
+ * its tools read from the server and each call forwarded to it
+ * (docs/design/2026-10-mcp-by-url.md, docs/design/2026-11-mcp-apps-auth.md).
  *
  * The registration record is the app row's manifest: `id`, `name`,
  * `description` and a `remote` block ({@link RemoteMcpBlock}): the one URL
- * the Gateway ever fetches, how it authenticates ({@link RemoteMcpAuth},
- * the credential always the NAME of a Gateway setting, never a value), how
- * a tool's risk is decided when the server's annotations don't say, the
- * operator's per-tool overrides, and a revision the writers bump so the
- * Gateway re-lists the tools on first use after a change.
+ * the Gateway ever fetches, its credential ({@link RemoteMcpAuth}: none, or
+ * a provider of the registry, whose key or OAuth connection the Gateway
+ * holds and binds to the provider's hosts), how a tool's risk is decided
+ * when the server's annotations don't say, the operator's per-tool
+ * overrides, and a revision the writers bump so the Gateway re-lists the
+ * tools on first use after a change. An app with a provider also lists it
+ * under `capabilities` ({@link remoteMcpAppManifest}), so the settings
+ * model treats its key or client as any app's.
+ *
+ * A credential the registrar gives at `mcp add` becomes a provider row of
+ * the app's own, `<appId>-mcp` ({@link remoteMcpProviderId}; the specs are
+ * built in ./mcpOAuth.ts): an API-key row for a static value
+ * (`<APPID>_MCP_TOKEN`), a discovered `oauth2-user` row for OAuth
+ * (`<APPID>_MCP_CLIENT_ID`, `_SECRET`).
  *
  * Everything here is pure and shared by the CLI, the perimeter's registry
  * rules, the Gateway (which serves the row and validates again at every
  * fetch) and the settings model (./appSettings.ts), so the rules cannot
- * drift: what the URL may be, what the credential may be called, how a
- * server's tool names become the ToolBus's, and what risk a tool gets.
+ * drift: what the URL may be, what the credential may be, how a server's
+ * tool names become the ToolBus's, and what risk a tool gets.
  */
-import { CAPABILITIES } from "./capabilities.js";
-import { isRemoteMcpSecretName } from "./gatewaySettings.js";
+import { CAPABILITIES, apiKeyHosts, } from "./capabilities.js";
 import { isProviderAppId } from "./providerApps.js";
+import { PROVIDER_ID } from "./providerSpec.js";
 import { TOOL_NAME_PATTERN, isToolRisk } from "./tools.js";
-export const REMOTE_MCP_AUTH_KINDS = [
+/** The kinds a stored `remote.auth` block may have. */
+export const REMOTE_MCP_AUTH_KINDS = ["none", "provider"];
+/**
+ * What the registrar may ask for at `mcp add` (`--auth`): none, a static
+ * credential the add turns into a synthesized API-key provider row, or
+ * OAuth, a discovered `oauth2-user` row (./mcpOAuth.ts).
+ */
+export const REMOTE_MCP_CREDENTIAL_KINDS = [
     "none",
     "bearer",
     "header",
+    "query",
     "basic",
     "oauth",
 ];
+/** Why an old registration (`bearer`, `header`, `basic`, `oauth` with a `secret`) no longer parses. */
+export const REMOTE_MCP_AUTH_PREDATES = "this registration predates provider credentials; remove it and add it again";
 /**
  * How a tool's risk is decided for the app. `annotations`: from the
  * server's hints ({@link remoteToolRisk}); `read` or `write`: every tool,
@@ -45,18 +64,17 @@ const ID_PATTERN = /^[a-z]([a-z0-9-]*[a-z0-9])?$/;
 const ID_MAX_LENGTH = 32;
 /** App ids a remote server can't take: the Gateway's own tool prefix. */
 const RESERVED_IDS = ["everyapp"];
-const SECRET_MAX_LENGTH = 64;
-const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,100}$/;
-const PREFIX_MAX_LENGTH = 32;
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
 const URL_MAX_LENGTH = 2048;
 const NAME_MAX_LENGTH = 255;
 const DESCRIPTION_MAX_LENGTH = 1000;
 const OVERRIDES_MAX = 500;
 const UPSTREAM_NAME_MAX = 256;
 /**
- * Headers the `header` kind may not name: the ones the Gateway sets on the
- * request, the ones that route it, and the ones that would carry something
- * other than this app's credential.
+ * Headers a static `header` credential may not name: the ones the Gateway
+ * sets on the request, the ones that route it, and the ones that would
+ * carry something other than this app's credential (`Authorization` is
+ * the `bearer` kind's; `--prefix` gives it another scheme).
  */
 const FORBIDDEN_AUTH_HEADERS = new Set([
     "authorization",
@@ -71,10 +89,99 @@ const FORBIDDEN_AUTH_HEADERS = new Set([
     "mcp-protocol-version",
     "mcp-method",
     "mcp-name",
+    "last-event-id",
 ]);
-/** The default credential name for an app id: `treg` → `TREG_MCP_TOKEN`. */
-export function remoteMcpSecretName(id) {
-    return `${id.toUpperCase().replace(/-/g, "_")}_MCP_TOKEN`;
+/**
+ * Why `header` can't carry a remote MCP server's static credential, or
+ * null when it can: an HTTP header name the MCP transport and the Gateway
+ * don't set themselves.
+ */
+export function remoteMcpHeaderProblem(header) {
+    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
+        return "the header must be an HTTP header name";
+    }
+    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+        return `the header can't be ${header}; use --auth bearer for Authorization`;
+    }
+    return null;
+}
+/** The settings prefix of an app id's synthesized row: `my-server` → `MY_SERVER_MCP_`. */
+function settingsPrefix(appId) {
+    return `${appId.toUpperCase().replace(/-/g, "_")}_MCP_`;
+}
+/**
+ * The provider row `everyapp mcp add` writes for an app's own credential:
+ * `<appId>-mcp` (`treg` → `treg-mcp`), its settings `TREG_MCP_*`.
+ */
+export function remoteMcpProviderId(appId) {
+    return `${appId}-mcp`;
+}
+/** Whether `providerId` is `appId`'s synthesized row ({@link remoteMcpProviderId}). */
+export function isRemoteMcpProviderIdOf(providerId, appId) {
+    return providerId === remoteMcpProviderId(appId);
+}
+/** The static credential's setting on the synthesized row: `treg` → `TREG_MCP_TOKEN`. */
+export function remoteMcpTokenSetting(appId) {
+    return `${settingsPrefix(appId)}TOKEN`;
+}
+/** The OAuth client id's setting on the synthesized row: `treg` → `TREG_MCP_CLIENT_ID`. */
+export function remoteMcpClientIdSetting(appId) {
+    return `${settingsPrefix(appId)}CLIENT_ID`;
+}
+/** The OAuth client secret's setting on the synthesized row: `treg` → `TREG_MCP_CLIENT_SECRET`. */
+export function remoteMcpClientSecretSetting(appId) {
+    return `${settingsPrefix(appId)}CLIENT_SECRET`;
+}
+/**
+ * The redirect URI of an app's synthesized OAuth row, what a server's
+ * client is registered with: `<gateway origin>/connect/<appId>-mcp/callback`.
+ */
+export function remoteMcpRedirectUri(gatewayUrl, appId) {
+    let origin = gatewayUrl.trim().replace(/\/+$/, "");
+    try {
+        origin = new URL(gatewayUrl).origin;
+    }
+    catch {
+        // Not a URL: used as given, without a trailing slash.
+    }
+    return `${origin}/connect/${remoteMcpProviderId(appId)}/callback`;
+}
+/** Where the Gateway serves its OAuth client metadata documents (public, bypassed behind Access). */
+export const REMOTE_MCP_CLIENT_METADATA_PREFIX = "/oauth-clients/";
+/**
+ * The Gateway's client id at a server that takes OAuth client ID metadata
+ * documents (CIMD) instead of registration: the URL of the document that
+ * describes the client, `<gateway origin>/oauth-clients/<appId>-mcp`.
+ * Null for a Gateway that isn't on https (a local one): an authorization
+ * server fetches the document, and only from https.
+ */
+export function remoteMcpClientMetadataUrl(gatewayUrl, appId) {
+    let origin;
+    try {
+        const parsed = new URL(gatewayUrl);
+        if (parsed.protocol !== "https:")
+            return null;
+        origin = parsed.origin;
+    }
+    catch {
+        return null;
+    }
+    return `${origin}${REMOTE_MCP_CLIENT_METADATA_PREFIX}${remoteMcpProviderId(appId)}`;
+}
+/**
+ * The hosts a provider sends its credential to, the hosts an MCP URL
+ * using it must be on: an API-key provider's `hosts` (and its host
+ * setting's value, given `settings`), an OAuth provider's API hosts. Null
+ * for a provider a remote MCP app can't use: an AI provider, a service,
+ * or an OAuth client the Gateway runs no flow for.
+ */
+export function remoteMcpProviderHosts(capability, settings) {
+    if (capability.mode === "api_key")
+        return apiKeyHosts(capability, settings);
+    if (capability.mode === "oauth_client" && capability.flow) {
+        return [...capability.api];
+    }
+    return null;
 }
 /** Whether `id` can be a remote MCP app's id (kebab-case, at most 32, not reserved, not a built-in's). */
 export function remoteMcpIdProblem(id) {
@@ -157,11 +264,16 @@ export function reservedUpstreamHosts() {
  * `https:` (or `http:` and loopback hosts only while the Gateway itself
  * runs on `http://`, local dev), a host name rather than an address, no
  * credentials or fragment in it, not the Gateway's own origin or one of
- * its app hosts, and not a provider whose key the Gateway holds. The
- * Gateway checks the stored URL again before every fetch, so a row edited
- * by hand is refused the same way.
+ * its app hosts, and not a provider whose key the Gateway holds
+ * ({@link reservedUpstreamHosts}) unless the app names that provider:
+ * `providerHosts` are the hosts of the provider the app's credential is
+ * (never an app's own synthesized row), and a reserved host among them is
+ * allowed (`mcp add https://api.elevenlabs.io/v1/mcp --provider
+ * elevenlabs`). The Gateway's own origin, its app domains and IPs stay
+ * refused always. The Gateway checks the stored URL again before every
+ * fetch, so a row edited by hand is refused the same way.
  */
-export function remoteMcpUrlProblem(url, env) {
+export function remoteMcpUrlProblem(url, env, options = {}) {
     if (typeof url !== "string" || !url.trim())
         return "give the server's URL";
     if (url.length > URL_MAX_LENGTH)
@@ -230,74 +342,67 @@ export function remoteMcpUrlProblem(url, env) {
             return `the URL is on this Gateway's app domain (${normalized})`;
         }
     }
-    if (reservedUpstreamHosts().includes(host)) {
-        return `${host} is a provider this Gateway holds a key for; apps reach it through the Gateway's capabilities, not as an MCP app`;
+    const named = (options.providerHosts ?? []).map((each) => each.toLowerCase().replace(/\.$/, ""));
+    if (reservedUpstreamHosts().includes(host) && !named.includes(host)) {
+        return `${host} is a provider this Gateway holds a key for; add it with --provider <that provider> so the app uses its key, or reach it through the Gateway's capabilities`;
     }
     return null;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** The credential name's problem, or null: in the family, and bounded. */
-export function remoteMcpSecretProblem(name) {
-    if (typeof name !== "string" || !name)
-        return "give the credential's setting name";
-    if (name.length > SECRET_MAX_LENGTH)
-        return "the credential's name is too long";
-    if (!isRemoteMcpSecretName(name)) {
-        return `the credential's name must end in _MCP_TOKEN (letters, digits and underscores), like ${remoteMcpSecretName("treg")}`;
-    }
-    return null;
-}
-/** The auth block's problem, or the block as typed. */
+/**
+ * The auth block's problem, or the block as typed: `{ kind: "none" }`,
+ * or `{ kind: "provider", provider }` naming a provider id. A
+ * block of the kinds before provider credentials (`bearer`, `header`,
+ * `basic`, `oauth`) is refused with {@link REMOTE_MCP_AUTH_PREDATES}: such
+ * a row serves nothing and reads as needing setup.
+ */
 export function parseRemoteMcpAuth(raw) {
     if (!isRecord(raw) || typeof raw["kind"] !== "string") {
         return { ok: false, problem: "auth must name a kind" };
     }
     const kind = raw["kind"];
-    if (!REMOTE_MCP_AUTH_KINDS.includes(kind)) {
+    if (["bearer", "header", "basic", "oauth"].includes(kind)) {
+        return { ok: false, problem: REMOTE_MCP_AUTH_PREDATES };
+    }
+    if (kind === "none") {
+        for (const field of Object.keys(raw)) {
+            if (field !== "kind") {
+                return {
+                    ok: false,
+                    problem: `auth.${field} is not a field of kind none`,
+                };
+            }
+        }
+        return { ok: true, auth: { kind } };
+    }
+    if (kind !== "provider") {
         return {
             ok: false,
             problem: `auth.kind must be one of ${REMOTE_MCP_AUTH_KINDS.join(", ")}`,
         };
     }
-    if (kind === "none" || kind === "oauth") {
-        return { ok: true, auth: { kind } };
-    }
-    const secretProblem = remoteMcpSecretProblem(raw["secret"]);
-    if (secretProblem)
-        return { ok: false, problem: `auth.secret: ${secretProblem}` };
-    const secret = raw["secret"];
-    if (kind === "bearer" || kind === "basic") {
-        return { ok: true, auth: { kind, secret } };
-    }
-    const header = raw["header"];
-    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
-        return { ok: false, problem: "auth.header must be an HTTP header name" };
+    for (const field of Object.keys(raw)) {
+        if (!["kind", "provider"].includes(field)) {
+            return {
+                ok: false,
+                problem: `auth.${field} is not a field of kind provider`,
+            };
+        }
     }
-    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+    const provider = raw["provider"];
+    if (typeof provider !== "string" || !PROVIDER_ID.test(provider)) {
         return {
             ok: false,
-            problem: `auth.header can't be ${header}; use kind "bearer" or "basic" for Authorization`,
+            problem: "auth.provider must be a provider id: lowercase letters, digits and hyphens, a letter first",
         };
     }
-    const prefix = raw["prefix"];
-    if (prefix !== undefined) {
-        if (typeof prefix !== "string" ||
-            prefix.length > PREFIX_MAX_LENGTH ||
-            /[\r\n]/.test(prefix)) {
-            return { ok: false, problem: "auth.prefix must be a short string" };
-        }
-    }
-    return {
-        ok: true,
-        auth: {
-            kind: "header",
-            secret,
-            header,
-            ...(typeof prefix === "string" && prefix ? { prefix } : {}),
-        },
-    };
+    return { ok: true, auth: { kind: "provider", provider } };
+}
+/** The provider the block names, or null for `none`. */
+export function remoteMcpProviderOf(auth) {
+    return auth.kind === "provider" ? auth.provider : null;
 }
 /**
  * The `remote` block of a stored manifest, checked field by field (a row
@@ -391,14 +496,21 @@ export function remoteMcpOf(manifest) {
     const parsed = parseRemoteMcpBlock(manifest["remote"]);
     return parsed.ok ? parsed.block : null;
 }
+/**
+ * Why a stored manifest's `remote` block can't be read, or null when it
+ * can or there is none: {@link REMOTE_MCP_AUTH_PREDATES} for a block from
+ * before provider credentials.
+ */
+export function remoteMcpBlockProblem(manifest) {
+    if (!isRecord(manifest) || manifest["remote"] === undefined)
+        return null;
+    const parsed = parseRemoteMcpBlock(manifest["remote"]);
+    return parsed.ok ? null : parsed.problem;
+}
 /** Whether a stored manifest declares a remote MCP server at all (well-formed or not). */
 export function hasRemoteMcpBlock(manifest) {
     return isRecord(manifest) && manifest["remote"] !== undefined;
 }
-/** The credential's setting name the block declares, if its kind takes one. */
-export function remoteMcpSecretOf(auth) {
-    return "secret" in auth ? auth.secret : null;
-}
 /**
  * A description for a row that gave none: the server's origin, read as a
  * sentence. The origin only: a path or query may carry something the
@@ -438,12 +550,45 @@ export function remoteToolOverride(block, upstreamName) {
 export function isHeaderSafeToolName(name) {
     return /^[\x21-\x7e]{1,256}$/.test(name);
 }
-/** The manifest a remote MCP app's row stores, from what the registrar gave. */
+/**
+ * The manifest a remote MCP app's row stores, from what the registrar
+ * gave. An app with a provider credential lists the provider under
+ * `capabilities` like a deployed app that uses it, so the settings model
+ * (./appSettings.ts) asks for its key or client, `secret list` names it
+ * and the connect flow asks for its scopes: nothing about a remote app's
+ * credential is special there. `providerCapability` is the provider as
+ * the registry resolves it (the synthesized row's, before it is written);
+ * for an OAuth provider the entry lists `scopes`, the server's own scope
+ * strings the connect asks for (discovery's, or none: the server decides).
+ */
 export function remoteMcpAppManifest(input) {
     const name = (input.name ?? "").trim().slice(0, NAME_MAX_LENGTH) || input.id;
     const description = (input.description ?? "").trim().slice(0, DESCRIPTION_MAX_LENGTH) ||
         remoteMcpDefaultDescription(name, input.remote.url);
-    return { id: input.id, name, description, remote: input.remote };
+    const manifest = {
+        id: input.id,
+        name,
+        description,
+        remote: input.remote,
+    };
+    const auth = input.remote.auth;
+    if (auth.kind !== "provider")
+        return manifest;
+    let where = "";
+    try {
+        where = new URL(input.remote.url).origin;
+    }
+    catch {
+        where = "the server";
+    }
+    const why = `${name}'s MCP server at ${where} takes this credential; the Gateway sends it there when a member calls the app's tools.`;
+    const shortWhy = why.length > 200 ? `${why.slice(0, 199)}…` : why;
+    manifest.capabilities = {
+        [auth.provider]: input.providerCapability?.mode === "oauth_client"
+            ? { scopes: [...(input.scopes ?? [])], why: shortWhy }
+            : { access: "read", why: shortWhy },
+    };
+    return manifest;
 }
 /**
  * A tool's risk for the Gateway. An override wins; then the app's `read`
@@ -496,41 +641,36 @@ export function normalizeRemoteToolName(name) {
     return TOOL_NAME_PATTERN.test(out) ? out : null;
 }
 /**
- * The request headers that carry the credential for `auth`, from the
- * setting's value. The value never appears anywhere else.
+ * Plain words for how the app authenticates, for lists and dialogs. With
+ * the provider's capability as the registry resolves it: "bearer token",
+ * "header X-Api-Key", "query parameter key", "user and password" (an
+ * API-key provider; "<kind>, <provider>'s key" when the provider isn't
+ * the app's own synthesized row), or "OAuth, each member connects" (an
+ * OAuth provider). Without it, the provider's id.
  */
-export function remoteMcpAuthHeaders(auth, value) {
-    switch (auth.kind) {
-        case "none":
-        case "oauth":
-            return {};
-        case "bearer":
-            return { authorization: `Bearer ${value}` };
-        case "basic":
-            return { authorization: `Basic ${base64(value)}` };
-        case "header":
-            return { [auth.header]: `${auth.prefix ?? ""}${value}` };
-    }
-}
-function base64(text) {
-    const bytes = new TextEncoder().encode(text);
-    let binary = "";
-    for (const byte of bytes)
-        binary += String.fromCharCode(byte);
-    return btoa(binary);
-}
-/** Plain words for an auth kind, for lists and dialogs. */
-export function remoteMcpAuthLabel(auth) {
-    switch (auth.kind) {
-        case "none":
-            return "no credential";
-        case "bearer":
-            return "bearer token";
-        case "basic":
-            return "user and password";
-        case "header":
-            return `header ${auth.header}`;
-        case "oauth":
-            return "OAuth (not supported yet)";
-    }
+export function remoteMcpAuthLabel(auth, capability) {
+    if (auth.kind === "none")
+        return "no credential";
+    if (!capability)
+        return `provider ${auth.provider}`;
+    if (capability.mode === "oauth_client") {
+        return "OAuth, each member connects";
+    }
+    if (capability.mode !== "api_key")
+        return `provider ${auth.provider}`;
+    const placement = capability.auth;
+    const words = placement.kind === "bearer"
+        ? placement.scheme && placement.scheme.toLowerCase() !== "bearer"
+            ? `${placement.scheme} token`
+            : "bearer token"
+        : placement.kind === "header"
+            ? `header ${placement.header}`
+            : placement.kind === "query"
+                ? `query parameter ${placement.param}`
+                : placement.as === "pair"
+                    ? "user and password"
+                    : "basic auth";
+    return auth.provider.endsWith("-mcp")
+        ? words
+        : `${words}, ${capability.label}'s key`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-app/sdk",
-  "version": "0.3.0-rc.12",
+  "version": "0.3.0-rc.13",
   "license": "MIT",
   "type": "module",
   "exports": {