@everfur/cli 0.1.0 → 0.2.1

package/dist/chunk-SJUEHHU6.js

@@ -0,0 +1,893 @@
+#!/usr/bin/env node
+import { hostnameOf, listen, close, writeJson, serveStatelessMcp } from './chunk-FC23PLWG.js';
+import { createHostedTokenVerifier, tokenBucketOf, isAccessTokenShaped, buildServer, MCP_SCOPE, tenantContextOf, sendTestUserRef, hostedVerifyUserRef, REVOKED_AUTHORIZATION_REMEDY, SYNTHETIC_USER_REF_PREFIX } from './chunk-XMIERMOW.js';
+import { BASE_URL_ENV_VAR, resolveEndpoint, fetchTransport, systemClock, createApiClient, withPrefix, ephemeralCredential, validateContractText, isJsonObject, describeFailure } from './chunk-KQICUK54.js';
+import { createServer } from 'http';
+import { InvalidTokenError, TooManyRequestsError, TemporarilyUnavailableError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { isIP } from 'net';
+
+// src/mcp/hosted/config.ts
+var PUBLIC_URL_ENV_VAR = "MCP_PUBLIC_URL";
+var PORT_ENV_VAR = "EVERFUR_MCP_HTTP_PORT";
+var LEGACY_PORT_ENV_VAR = "MCP_PORT";
+var ALLOWED_HOSTS_ENV_VAR = "MCP_ALLOWED_HOSTS";
+var ALLOWED_ORIGINS_ENV_VAR = "MCP_ALLOWED_ORIGINS";
+var DEFAULT_ALLOWED_ORIGINS = Object.freeze(["https://claude.ai", "https://claude.com"]);
+var TRUSTED_PROXY_HOPS_ENV_VAR = "MCP_TRUSTED_PROXY_HOPS";
+var MAX_TRUSTED_PROXY_HOPS = 8;
+var DEFAULT_HOSTED_PORT = 3100;
+var DEFAULT_MCP_PATH = "/mcp";
+var LOCAL_HTTP_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+function parsePublicUrl(raw) {
+  const value = (raw ?? "").trim();
+  if (value.length === 0) {
+    throw new Error(`${PUBLIC_URL_ENV_VAR} is required: the full MCP endpoint URL editors reach this server at (https://mcp.everfur.com${DEFAULT_MCP_PATH}).`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`${PUBLIC_URL_ENV_VAR} is not a URL.`);
+  }
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && LOCAL_HTTP_HOSTS.has(parsed.hostname))) {
+    throw new Error(`${PUBLIC_URL_ENV_VAR} must be https (http only on localhost, 127.0.0.1 or [::1]).`);
+  }
+  if (parsed.search !== "" || parsed.hash !== "" || value.endsWith("?") || value.endsWith("#")) {
+    throw new Error(`${PUBLIC_URL_ENV_VAR} must carry no query or fragment.`);
+  }
+  const path = stripTrailingSlashes(parsed.pathname);
+  if (path === "") {
+    throw new Error(
+      `${PUBLIC_URL_ENV_VAR} must be the full MCP endpoint URL, path included (${parsed.origin}${DEFAULT_MCP_PATH}), not the origin: it is the resource every token names and the URL a user enters.`
+    );
+  }
+  return {
+    publicUrl: `${parsed.origin}${path}`,
+    publicOrigin: parsed.origin,
+    mcpPath: path
+  };
+}
+function parsePort(env) {
+  const [name, raw] = (env[PORT_ENV_VAR] ?? "").trim() !== "" ? [PORT_ENV_VAR, env[PORT_ENV_VAR]] : [LEGACY_PORT_ENV_VAR, env[LEGACY_PORT_ENV_VAR]];
+  if (raw === void 0 || raw.trim() === "") return DEFAULT_HOSTED_PORT;
+  if (!/^\d+$/.test(raw.trim())) throw new Error(`${name} must be an integer between 0 and 65535.`);
+  const value = Number(raw.trim());
+  if (!Number.isSafeInteger(value) || value < 0 || value > 65535) {
+    throw new Error(`${name} must be an integer between 0 and 65535.`);
+  }
+  return value;
+}
+function parseTrustedProxyHops(raw) {
+  if (raw === void 0 || raw.trim() === "") return 0;
+  const value = Number(raw.trim());
+  if (!/^\d+$/.test(raw.trim()) || !Number.isSafeInteger(value) || value > MAX_TRUSTED_PROXY_HOPS) {
+    throw new Error(`${TRUSTED_PROXY_HOPS_ENV_VAR} must be an integer between 0 and ${MAX_TRUSTED_PROXY_HOPS}.`);
+  }
+  return value;
+}
+function parseAllowedHosts(raw) {
+  if (raw === void 0 || raw.trim() === "") return [];
+  const values = raw.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
+  if (values.length === 0) throw new Error(`${ALLOWED_HOSTS_ENV_VAR} must contain at least one hostname when set.`);
+  return values.map((value) => {
+    const hostname = hostnameOf(value);
+    if (hostname === null) throw new Error(`${ALLOWED_HOSTS_ENV_VAR} carries a value that is not a hostname.`);
+    return hostname;
+  });
+}
+function normalizeOrigin(value) {
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+  if (parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "") return null;
+  if (parsed.pathname !== "/" && parsed.pathname !== "") return null;
+  return parsed.origin;
+}
+function parseAllowedOrigins(raw) {
+  if (raw === void 0 || raw.trim() === "") return [];
+  const values = raw.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
+  if (values.length === 0) throw new Error(`${ALLOWED_ORIGINS_ENV_VAR} must contain at least one origin when set.`);
+  return values.map((value) => {
+    const origin = normalizeOrigin(value);
+    if (origin === null) throw new Error(`${ALLOWED_ORIGINS_ENV_VAR} carries a value that is not an origin (scheme and host only).`);
+    const hostname = new URL(origin).hostname;
+    if (origin.startsWith("http:") && !LOCAL_HTTP_HOSTS.has(hostname)) {
+      throw new Error(`${ALLOWED_ORIGINS_ENV_VAR} must list https origins (http only on localhost, 127.0.0.1 or [::1]).`);
+    }
+    return origin;
+  });
+}
+function loadHostedMcpConfig(env) {
+  if ((env[BASE_URL_ENV_VAR] ?? "").trim().length === 0) {
+    throw new Error(`${BASE_URL_ENV_VAR} is required: the Everfur API this server verifies bearers against.`);
+  }
+  const endpoint = resolveEndpoint(null, env);
+  if (endpoint.ok === false) {
+    throw new Error(`${BASE_URL_ENV_VAR} is not usable: ${endpoint.errors.join("; ").replace(/--base-url/g, BASE_URL_ENV_VAR)}`);
+  }
+  const publicUrl = parsePublicUrl(env[PUBLIC_URL_ENV_VAR]);
+  const publicHostname = hostnameOf(new URL(publicUrl.publicOrigin).host);
+  if (publicHostname === null) throw new Error(`${PUBLIC_URL_ENV_VAR} names no host.`);
+  return Object.freeze({
+    apiBaseUrl: endpoint.endpoint.baseUrl,
+    publicUrl: publicUrl.publicUrl,
+    publicOrigin: publicUrl.publicOrigin,
+    mcpPath: publicUrl.mcpPath,
+    host: "0.0.0.0",
+    port: parsePort(env),
+    allowedHosts: /* @__PURE__ */ new Set([publicHostname, ...parseAllowedHosts(env[ALLOWED_HOSTS_ENV_VAR])]),
+    trustedProxyHops: parseTrustedProxyHops(env[TRUSTED_PROXY_HOPS_ENV_VAR]),
+    allowedOrigins: /* @__PURE__ */ new Set([...DEFAULT_ALLOWED_ORIGINS, ...parseAllowedOrigins(env[ALLOWED_ORIGINS_ENV_VAR])])
+  });
+}
+function resourceMetadataUrl(config) {
+  return `${config.publicUrl}/.well-known/oauth-protected-resource`;
+}
+
+// src/mcp/hosted/contract.ts
+var HOSTED_CONTRACT_PATH = "/mcp/contract";
+var MAX_CACHED_DOCUMENTS = 3;
+function createHostedContractCache() {
+  return { latest: null, documents: /* @__PURE__ */ new Map() };
+}
+function snapshotOf(outcome, source) {
+  return Object.freeze({
+    source,
+    digest: outcome.digest.actual,
+    generatedAt: outcome.generatedAt,
+    validation: { ...outcome, path: source }
+  });
+}
+function unavailable(reason, cliCode, message, details, status = null, requestId = null) {
+  return Object.freeze({ kind: "unavailable", reason, cliCode, message, details: Object.freeze([...details]), status, requestId });
+}
+function remember(cache, outcome, etag) {
+  cache.documents.set(outcome.digest.actual, outcome);
+  cache.latest = { digest: outcome.digest.actual, etag };
+  while (cache.documents.size > MAX_CACHED_DOCUMENTS) {
+    const oldest = cache.documents.keys().next().value;
+    if (oldest === void 0 || oldest === outcome.digest.actual) break;
+    cache.documents.delete(oldest);
+  }
+}
+async function readOnce(options) {
+  const endpoint = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: options.apiBaseUrl });
+  if (endpoint.ok === false) {
+    return unavailable("endpoint_missing", "usage_error", "the hosted server has no usable Everfur API base URL to fetch the contract from", endpoint.errors);
+  }
+  const baseUrl = endpoint.endpoint.baseUrl;
+  const source = `GET ${HOSTED_CONTRACT_PATH} on ${baseUrl}`;
+  const cache = options.cache;
+  const cached = cache.latest === null ? null : cache.documents.get(cache.latest.digest) ?? null;
+  const client = createApiClient({
+    transport: options.transport ?? fetchTransport,
+    clock: options.clock ?? systemClock,
+    endpoint: endpoint.endpoint,
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  const result = await client.request({
+    method: "GET",
+    path: HOSTED_CONTRACT_PATH,
+    credentials: { authorization: withPrefix(ephemeralCredential("editor access token", options.bearer), "Bearer ") },
+    ...cached !== null && cache.latest !== null ? { headers: { "if-none-match": cache.latest.etag } } : {},
+    acceptStatuses: [304],
+    responseType: "text"
+  });
+  if (result.ok === true) {
+    if (result.status === 304) {
+      if (cached === null) {
+        return unavailable("remote_error", "malformed_response", `${source} answered 304 to a request that held no cached contract`, [], 304, result.requestId);
+      }
+      return { kind: "loaded", contract: snapshotOf(cached, source) };
+    }
+    const text = typeof result.value === "string" ? result.value : "";
+    const outcome = validateContractText(source, text);
+    if (outcome.kind !== "valid") {
+      return unavailable(
+        "invalid_contract",
+        outcome.kind === "digest_mismatch" ? "digest_mismatch" : "invalid_contract",
+        `${source} did not return a usable contract`,
+        [
+          outcome.kind === "digest_mismatch" ? "the served document declares a digest that does not match its projection" : "the response body is not a contract-public envelope"
+        ],
+        result.status,
+        result.requestId
+      );
+    }
+    remember(cache, outcome, result.headers["etag"] ?? `"${outcome.digest.actual}"`);
+    return { kind: "loaded", contract: snapshotOf(outcome, source) };
+  }
+  if (result.kind === "network" || result.kind === "timeout") {
+    if (cached !== null) {
+      return { kind: "loaded", contract: snapshotOf(cached, `(cached from ${source}; the API was unreachable, not revalidated)`) };
+    }
+    return unavailable("unreachable", "remote_unreachable", `the Everfur API at ${baseUrl} could not be reached to fetch the contract`, [
+      result.kind === "timeout" ? `the request timed out after ${result.timeoutMs}ms` : "the connection failed",
+      "no cached copy of the contract is available on this server"
+    ]);
+  }
+  if (result.kind === "http" && (result.status === 401 || result.status === 403)) {
+    if (result.status === 401) options.onUnauthorized?.();
+    return unavailable("credential_rejected", "remote_error", `the Everfur API refused this sign-in for the contract (${result.status})`, [
+      REVOKED_AUTHORIZATION_REMEDY
+    ], result.status, result.requestId);
+  }
+  if (result.kind === "http" && result.status === 404) {
+    return unavailable("remote_error", "remote_error", `${baseUrl} does not serve GET ${HOSTED_CONTRACT_PATH}`, [
+      "the hosted MCP surface is dark on this deployment of the Everfur API"
+    ], 404, result.requestId);
+  }
+  return unavailable(
+    "remote_error",
+    result.kind === "malformed" ? "malformed_response" : "remote_error",
+    `${source} did not succeed`,
+    [result.kind === "http" ? `the API answered ${result.status}` : "the API answered a body this server does not recognise"],
+    result.status,
+    result.requestId
+  );
+}
+function createHostedContractProvider(options) {
+  let pending = null;
+  return () => {
+    if (pending === null) pending = readOnce(options);
+    return pending;
+  };
+}
+
+// src/mcp/hosted/instructions.ts
+var HOSTED_MCP_INSTRUCTIONS = `Everfur partner integration tools, hosted by Everfur.
+
+Everfur is a pet-health API. Partners embed chat, medical-records and Televet (vet visit) surfaces in their own apps and
+pages via @everfur/sdk (React Native and Expo; the web through @everfur/sdk/web and a hosted frame; Flutter through
+everfur_sdk). On the web the plan follows the contract: a React tree embeds the SDK in the page, any other page includes
+the loader and gets the frame, and a Shopify storefront gets the Everfur app's theme block with Shopify vouching for the
+signed-in customer (identity_mode shopify-app-proxy). A capability the web cannot render (photo in the page, anything
+but chat in the frame) is reported as blocked by the platform; the React Native entry points are not a substitute for
+it, and the HTTP routes are not an integration of their own.
+
+This server runs on Everfur's hosts as the partner who connected it. The partner console sign-in made when the
+connector was added decides the tenant, and every tool runs as that tenant: its publishable key, API base URL and
+contract are resolved from the sign-in on each call. The server holds no key, token or variable of the partner's and
+reads no file or path on the developer's machine. A project is described with project_details (package dependencies,
+package manager and file-presence markers, never source files or credentials), and a theme with theme_source (the text
+of a tailwind config or of the CSS that declares the theme, read statically and never executed).
+
+The integration tools:
+- everfur_plan_integration produces an integration plan, or a refusal that names each missing fact (identity mode,
+  capabilities, backend language, environment) rather than a plan built on a guess. An integration built on a guessed
+  identity mode is wrong in a way that only shows up in production. Omitted, the environment is the connected tenant's.
+- everfur_verify_integration exercises the real wire with a short-lived session the Everfur API mints for a synthetic
+  test user of a sandbox tenant (its entitlements report livemode false). On a live tenant the signed session step is
+  reported GATED; no session can be supplied by hand. identity_mode anonymous verifies the anonymous path instead: the
+  tenant's publishable key and a device session id derived for a synthetic test user, with nothing minted. It is the
+  read-only check a live tenant takes, GET requests only.
+- everfur_diagnose separates the four byte-identical causes of an empty entitlement verdict.
+- everfur_explain_error looks an error code up in the contract's registry, case sensitive, and refuses a code the
+  registry does not list, with near misses. Three naming families are live at once and one code is the default for
+  four different HTTP statuses, so the registry, not the shape of a code's string, says whether a retry can help.
+- everfur_send_test_message sends a real message to a sandbox tenant only, and streams the real answer.
+
+The tenant tools read the connected tenant's own state and change nothing:
+- everfur_get_tenant_status: the plan and its limits, features, live or test mode, embed origins, the capabilities the
+  account holds, the publishable key's id and prefix, and the Televet return destination keys and booking lead.
+- everfur_list_webhook_endpoints, everfur_list_webhook_deliveries and everfur_get_webhook_delivery: the webhook
+  endpoints and the delivery log with each delivery's attempts.
+- everfur_list_events: the events Everfur emitted to the tenant.
+- everfur_get_usage_summary and everfur_get_records_status_summary: aggregate chat usage and records request counts.
+None of them returns a signing secret, a key value, or a member's conversation, message or record content.
+everfur_search_docs searches the contract's error registry, capability packs and integration guide.
+
+Every tool returns structured content. A failed call carries error.code, error.retryable and error.next_action, which
+are stable, while the message is prose that may change. TENANT_SURFACE_NOT_ENABLED means that surface is not switched
+on for the connected tenant, a setting Everfur holds rather than a fault in the call. CONTRACT_UNAVAILABLE means the Everfur API did not serve the contract, and error.retryable says
+whether a later call can succeed. CONTRACT_CREDENTIAL_UNUSABLE means the Everfur API refused the sign-in the call
+carried, which reconnecting the connector renews. Reference material is served as resources (everfur://guide,
+everfur://contract/errors, everfur://mcp/refusal-codes), and the prompts integrate-web, integrate-react-native and
+diagnose-integration lay out an order to call the tools in.`;
+
+// src/mcp/hosted/tenant-env.ts
+var VERIFY_SESSIONS_PATH = "/mcp/verify-sessions";
+function toolApiBaseUrl(context, fallback) {
+  const resolved = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: context.apiBaseUrl });
+  return resolved.ok ? resolved.endpoint.baseUrl : fallback;
+}
+async function mintVerifySession(options) {
+  const userRef = options.userRef;
+  if (!userRef.startsWith(SYNTHETIC_USER_REF_PREFIX)) {
+    return {
+      sessionToken: null,
+      outcome: { kind: "failed", reason: "the hosted server mints a session for a synthetic everfur-verify- test user only", requestId: null, details: [] }
+    };
+  }
+  const endpoint = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: options.apiBaseUrl });
+  if (endpoint.ok === false) {
+    return {
+      sessionToken: null,
+      outcome: { kind: "failed", reason: "the hosted server has no usable Everfur API base URL to mint a verify session with", requestId: null, details: [...endpoint.errors] }
+    };
+  }
+  const client = createApiClient({
+    transport: options.transport ?? fetchTransport,
+    clock: options.clock ?? systemClock,
+    endpoint: endpoint.endpoint,
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  const result = await client.request({
+    method: "POST",
+    path: VERIFY_SESSIONS_PATH,
+    credentials: { authorization: withPrefix(ephemeralCredential("editor access token", options.bearer), "Bearer ") },
+    body: { user_ref: userRef }
+  });
+  if (result.ok === false) {
+    const failure = result.kind === "http" ? { kind: "http", status: result.status, code: result.code } : { kind: result.kind, status: null, code: null };
+    if (result.kind === "http" && result.status === 403 && result.code === "sandbox_only") {
+      return {
+        sessionToken: null,
+        outcome: {
+          kind: "gated",
+          reason: "this tenant is live: the Everfur API mints verify sessions for sandbox tenants only",
+          requestId: result.requestId
+        }
+      };
+    }
+    if (result.kind === "http" && result.status === 401) {
+      options.onUnauthorized?.();
+      return {
+        sessionToken: null,
+        outcome: {
+          kind: "failed",
+          reason: "the Everfur API refused the sign-in this call carried when asked to mint a verify session",
+          requestId: result.requestId,
+          details: [REVOKED_AUTHORIZATION_REMEDY],
+          failure
+        }
+      };
+    }
+    return {
+      sessionToken: null,
+      outcome: {
+        kind: "failed",
+        // Operator-owned facts only: the method, the path, the status and the wire CODE, never the wire text.
+        reason: describeFailure(result),
+        requestId: result.requestId,
+        details: result.kind === "http" && result.code !== null ? [`call everfur_explain_error with the code ${result.code} for the cause and the next action`] : [],
+        failure
+      }
+    };
+  }
+  const body = result.value;
+  const token = isJsonObject(body) ? body["session_token"] : void 0;
+  if (typeof token !== "string" || token.length === 0) {
+    return {
+      sessionToken: null,
+      outcome: {
+        kind: "failed",
+        reason: `POST ${VERIFY_SESSIONS_PATH} answered ${result.status} without a session_token`,
+        requestId: result.requestId,
+        details: []
+      }
+    };
+  }
+  const expiresAtSeconds = isJsonObject(body) && typeof body["expires_at"] === "number" ? body["expires_at"] : null;
+  const capabilities = isJsonObject(body) && Array.isArray(body["capabilities"]) ? body["capabilities"].filter((entry) => typeof entry === "string") : [];
+  return {
+    sessionToken: token,
+    outcome: {
+      kind: "minted",
+      userRef,
+      expiresAt: expiresAtSeconds === null ? "unreported" : new Date(expiresAtSeconds * 1e3).toISOString(),
+      capabilities,
+      requestId: result.requestId
+    }
+  };
+}
+function synthesizeTenantEnv(options) {
+  const publishableKey = options.context.publishableKey;
+  return Object.freeze({
+    [BASE_URL_ENV_VAR]: toolApiBaseUrl(options.context, options.apiBaseUrl),
+    ...publishableKey === null ? {} : { EVERFUR_PARTNER_KEY: publishableKey }
+  });
+}
+function createHostedMint(options) {
+  return () => mintVerifySession(options);
+}
+var TENANT_READS_PATH = "/mcp/tenant";
+var ROUTE_SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+function createHostedTenantReads(options) {
+  const endpoint = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: options.apiBaseUrl });
+  if (endpoint.ok === false) {
+    throw new Error(`the hosted tenant reads need a usable API base URL: ${endpoint.errors.join("; ")}`);
+  }
+  const client = createApiClient({
+    transport: options.transport ?? fetchTransport,
+    clock: options.clock ?? systemClock,
+    endpoint: endpoint.endpoint,
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  return (route, query = {}) => {
+    const segments = route.split("/");
+    if (!segments.every((segment) => ROUTE_SEGMENT.test(segment))) {
+      return Promise.reject(new Error("a tenant read named a route outside /mcp/tenant"));
+    }
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value !== void 0) params.set(name, String(value));
+    }
+    const search = params.toString();
+    const path = `${TENANT_READS_PATH}/${segments.join("/")}${search === "" ? "" : `?${search}`}`;
+    return client.request({
+      method: "GET",
+      path,
+      credentials: { authorization: withPrefix(ephemeralCredential("editor access token", options.bearer), "Bearer ") }
+    }).then((result) => {
+      if (result.ok === false && result.kind === "http" && result.status === 401) options.onUnauthorized?.();
+      return result;
+    });
+  };
+}
+var DEFAULT_MAX_CLIENTS = 1e4;
+function bucketKey(client, bucket) {
+  return `${client}\0${bucket}`;
+}
+function createFailureBudget(options) {
+  const now = options.now ?? Date.now;
+  const maxClients = options.maxClients ?? DEFAULT_MAX_CLIENTS;
+  const clientLimit = options.clientLimit ?? options.limit;
+  const windows = /* @__PURE__ */ new Map();
+  function current(client, at) {
+    const entry = windows.get(client);
+    if (entry === void 0) return null;
+    if (at - entry.startedAt >= options.windowMs) {
+      windows.delete(client);
+      return null;
+    }
+    return entry;
+  }
+  function trim(at) {
+    if (windows.size < maxClients) return;
+    for (const [client, entry] of windows) {
+      if (at - entry.startedAt >= options.windowMs) windows.delete(client);
+    }
+    while (windows.size >= maxClients) {
+      const oldest = windows.keys().next().value;
+      if (oldest === void 0) break;
+      windows.delete(oldest);
+    }
+  }
+  function count(key, at) {
+    const entry = current(key, at);
+    if (entry !== null) {
+      entry.count += 1;
+      return;
+    }
+    trim(at);
+    windows.set(key, { startedAt: at, count: 1 });
+  }
+  function scopes(client, bucket) {
+    return bucket === void 0 ? [[client, clientLimit]] : [[bucketKey(client, bucket), options.limit], [client, clientLimit]];
+  }
+  return Object.freeze({
+    exhausted(client, bucket) {
+      const at = now();
+      return scopes(client, bucket).some(([key, limit]) => {
+        const entry = current(key, at);
+        return entry !== null && entry.count >= limit;
+      });
+    },
+    record(client, bucket) {
+      const at = now();
+      if (bucket === void 0) {
+        count(client, at);
+        return;
+      }
+      const key = bucketKey(client, bucket);
+      const spent = current(key, at);
+      const underLimit = spent === null || spent.count < options.limit;
+      count(key, at);
+      if (underLimit) count(client, at);
+    },
+    retryAfterSeconds(client, bucket) {
+      const at = now();
+      let seconds = 1;
+      for (const [key, limit] of scopes(client, bucket)) {
+        const entry = current(key, at);
+        if (entry === null || entry.count < limit) continue;
+        seconds = Math.max(seconds, Math.ceil((entry.startedAt + options.windowMs - at) / 1e3));
+      }
+      return seconds;
+    },
+    get size() {
+      return windows.size;
+    }
+  });
+}
+function clientIpOf(req, trustedHops) {
+  const socketAddress = req.socket.remoteAddress ?? "unknown";
+  if (trustedHops <= 0) return socketAddress;
+  const raw = req.headers["x-forwarded-for"];
+  const header = Array.isArray(raw) ? raw.join(",") : raw ?? "";
+  const entries = header.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  const candidate = entries[entries.length - trustedHops];
+  return candidate !== void 0 && isIP(candidate) !== 0 ? candidate : socketAddress;
+}
+
+// src/mcp/hosted/well-known.ts
+var WELL_KNOWN_DOCUMENTS = Object.freeze(["oauth-authorization-server", "oauth-protected-resource"]);
+var WELL_KNOWN_MAX_AGE_SECONDS = 300;
+function stripTrailingSlashes2(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+function wellKnownPaths(config) {
+  const paths = /* @__PURE__ */ new Map();
+  const publicPath = stripTrailingSlashes2(config.publicUrl.slice(config.publicOrigin.length));
+  for (const document of WELL_KNOWN_DOCUMENTS) {
+    paths.set(`/.well-known/${document}`, document);
+    paths.set(`/.well-known/${document}${config.mcpPath}`, document);
+    if (publicPath.length > 0) paths.set(`${publicPath}/.well-known/${document}`, document);
+  }
+  return paths;
+}
+function describes(document, body, options) {
+  if (!isJsonObject(body)) return "the document is not a JSON object";
+  if (document === "oauth-protected-resource") {
+    const resource = body["resource"];
+    if (typeof resource !== "string" || stripTrailingSlashes2(resource) !== options.publicUrl) {
+      return "the document names a resource other than this server";
+    }
+    const servers = body["authorization_servers"];
+    if (!Array.isArray(servers) || servers.length === 0 || !servers.every((entry) => typeof entry === "string")) {
+      return "the document names no authorization server";
+    }
+    return null;
+  }
+  const issuer = body["issuer"];
+  if (typeof issuer !== "string" || stripTrailingSlashes2(issuer) !== options.publicOrigin) {
+    return "the document names an issuer other than this origin";
+  }
+  for (const field of ["authorization_endpoint", "token_endpoint"]) {
+    if (typeof body[field] !== "string") return `the document carries no ${field}`;
+  }
+  return null;
+}
+function createWellKnownMirror(options) {
+  const endpoint = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: options.apiBaseUrl });
+  if (endpoint.ok === false) throw new Error(`the metadata mirror needs a usable API base URL: ${endpoint.errors.join("; ")}`);
+  const client = createApiClient({
+    transport: options.transport ?? fetchTransport,
+    clock: options.clock ?? systemClock,
+    endpoint: endpoint.endpoint,
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  const now = options.now ?? Date.now;
+  const maxAgeMs = options.maxAgeMs ?? WELL_KNOWN_MAX_AGE_SECONDS * 1e3;
+  const cache = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  async function fetchDocument(document) {
+    const result = await client.request({ method: "GET", path: `/mcp/.well-known/${document}`, responseType: "text" });
+    if (result.ok === false) {
+      return { ok: false, status: 503, reason: `the Everfur API did not serve ${document}` };
+    }
+    const text = typeof result.value === "string" ? result.value : "";
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return { ok: false, status: 503, reason: `the Everfur API answered ${document} with a body that is not JSON` };
+    }
+    const problem = describes(document, parsed, options);
+    if (problem !== null) return { ok: false, status: 503, reason: `${document}: ${problem}` };
+    cache.set(document, { body: text, fetchedAt: now() });
+    return { ok: true, body: text };
+  }
+  return Object.freeze({
+    async read(document) {
+      const cached = cache.get(document);
+      if (cached !== void 0 && now() - cached.fetchedAt < maxAgeMs) return { ok: true, body: cached.body };
+      const pending = inflight.get(document);
+      if (pending !== void 0) return pending;
+      const refresh = fetchDocument(document).then((read) => {
+        if (read.ok === false && cached !== void 0) return { ok: true, body: cached.body };
+        return read;
+      }).finally(() => {
+        inflight.delete(document);
+      });
+      inflight.set(document, refresh);
+      return refresh;
+    }
+  });
+}
+
+// src/mcp/hosted/http.ts
+var HEALTH_PATH = "/healthz";
+var MAX_BODY_BYTES = 1024 * 1024;
+var DRAIN_CEILING_BYTES = 16 * 1024 * 1024;
+var RETRY_AFTER_SECONDS = 5;
+var CORS_REQUEST_HEADERS = "authorization, content-type, accept, mcp-protocol-version";
+var CORS_EXPOSED_HEADERS = "www-authenticate, retry-after";
+var PREFLIGHT_MAX_AGE_SECONDS = 300;
+var UNAUTHENTICATED_FAILURE_LIMIT = 20;
+var UNAUTHENTICATED_FAILURE_ADDRESS_LIMIT = 200;
+var UNAUTHENTICATED_FAILURE_WINDOW_MS = 6e4;
+function createHostedFailureBudget(now) {
+  return createFailureBudget({
+    limit: UNAUTHENTICATED_FAILURE_LIMIT,
+    clientLimit: UNAUTHENTICATED_FAILURE_ADDRESS_LIMIT,
+    windowMs: UNAUTHENTICATED_FAILURE_WINDOW_MS,
+    ...now === void 0 ? {} : { now }
+  });
+}
+function refusalFor(req, config, methods) {
+  if (!methods.includes(req.method ?? "")) return { status: 405, message: "Method not allowed.", headers: { allow: methods.join(", ") } };
+  const host = hostnameOf(req.headers.host);
+  if (host === null || !config.allowedHosts.has(host)) return { status: 421, message: "Host is not allowed.", headers: {} };
+  return null;
+}
+function allowedOriginOf(origin, config) {
+  if (origin === void 0) return null;
+  const normalized = normalizeOrigin(origin);
+  return normalized !== null && config.allowedOrigins.has(normalized) ? normalized : null;
+}
+function originAllowed(origin, config) {
+  return origin === void 0 || allowedOriginOf(origin, config) !== null;
+}
+function bearerOf(req) {
+  const header = req.headers.authorization;
+  if (header === void 0 || header.trim() === "") return { present: false };
+  const match = header.match(/^Bearer\s+(\S+)\s*$/i);
+  return { present: true, token: match?.[1] ?? null };
+}
+function readBody(req, res, limit) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let received = 0;
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    req.on("data", (chunk) => {
+      if (settled) return;
+      received += chunk.length;
+      if (received > limit) {
+        writeJson(res, 413, { error: "Request body is too large." }, { connection: "close" });
+        req.destroy();
+        settle(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => settle(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", () => settle(null));
+  });
+}
+function jsonRpcError(res, status, code, message) {
+  writeJson(res, status, { jsonrpc: "2.0", error: { code, message }, id: null });
+}
+function createHostedMcpRequestListener(options) {
+  const { config } = options;
+  const transport = options.transport ?? fetchTransport;
+  const clock = options.clock ?? systemClock;
+  const failureBudget = options.failureBudget ?? createHostedFailureBudget(options.now);
+  const verifier = options.verifier ?? createHostedTokenVerifier({
+    apiBaseUrl: config.apiBaseUrl,
+    resource: config.publicUrl,
+    transport,
+    clock,
+    failureBudget,
+    ...options.now === void 0 ? {} : { now: options.now }
+  });
+  const wellKnown = options.wellKnown ?? createWellKnownMirror({
+    apiBaseUrl: config.apiBaseUrl,
+    publicUrl: config.publicUrl,
+    publicOrigin: config.publicOrigin,
+    transport,
+    clock,
+    ...options.now === void 0 ? {} : { now: options.now }
+  });
+  const contractCache = options.contractCache ?? createHostedContractCache();
+  const metadataPaths = wellKnownPaths(config);
+  const metadataUrl = resourceMetadataUrl(config);
+  const unauthorized = (res, error) => {
+    const challenge = error === null ? `Bearer resource_metadata="${metadataUrl}", scope="${MCP_SCOPE}"` : `Bearer error="${error.errorCode}", error_description="${error.message}", resource_metadata="${metadataUrl}", scope="${MCP_SCOPE}"`;
+    const body = error === null ? { error: "invalid_token", error_description: "Authentication required." } : error.toResponseObject();
+    writeJson(res, 401, body, { "www-authenticate": challenge });
+  };
+  const unavailable2 = (res, error) => {
+    writeJson(res, 503, error.toResponseObject(), { "retry-after": String(RETRY_AFTER_SECONDS) });
+  };
+  const throttled = (res, error, clientIp, bucket) => {
+    writeJson(res, 429, error.toResponseObject(), { "retry-after": String(failureBudget.retryAfterSeconds(clientIp, bucket)) });
+  };
+  const contextFor = async (call) => {
+    const tenant = tenantContextOf(call.authInfo);
+    if (tenant === null || call.authInfo === void 0) {
+      throw new Error("a hosted tool call reached the tools without a verified tenant context");
+    }
+    const idempotencyKey = call.args["idempotency_key"];
+    const label = call.args["user_ref"];
+    const userRef = call.tool === "everfur_send_test_message" && typeof idempotencyKey === "string" && idempotencyKey.length > 0 ? sendTestUserRef(idempotencyKey) : hostedVerifyUserRef(typeof label === "string" ? label : void 0);
+    const bearer = call.authInfo.token;
+    const onUnauthorized = () => verifier.forget(bearer);
+    return {
+      env: synthesizeTenantEnv({ context: tenant, apiBaseUrl: config.apiBaseUrl }),
+      credentialSource: "hosted",
+      hostedMint: createHostedMint({ bearer, apiBaseUrl: config.apiBaseUrl, userRef, transport, clock, onUnauthorized }),
+      syntheticUserRef: userRef,
+      tenantReads: createHostedTenantReads({ bearer, apiBaseUrl: config.apiBaseUrl, transport, clock, onUnauthorized })
+    };
+  };
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://mcp.invalid");
+    if (url.pathname === HEALTH_PATH) {
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        writeJson(res, 405, { error: "Method not allowed." }, { allow: "GET, HEAD" });
+        return;
+      }
+      writeJson(res, 200, { status: "ok" });
+      return;
+    }
+    const document = metadataPaths.get(url.pathname);
+    if (document !== void 0) {
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, {
+          "access-control-allow-origin": "*",
+          "access-control-allow-methods": "GET, OPTIONS",
+          "access-control-allow-headers": "mcp-protocol-version",
+          "access-control-max-age": String(WELL_KNOWN_MAX_AGE_SECONDS)
+        });
+        res.end();
+        return;
+      }
+      const refused2 = refusalFor(req, config, ["GET", "HEAD"]);
+      if (refused2 !== null) {
+        writeJson(res, refused2.status, { error: refused2.message }, refused2.headers);
+        return;
+      }
+      const read = await wellKnown.read(document);
+      if (read.ok === false) {
+        writeJson(res, read.status, { error: "temporarily_unavailable", error_description: read.reason }, { "retry-after": String(RETRY_AFTER_SECONDS) });
+        return;
+      }
+      res.writeHead(200, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": `public, max-age=${WELL_KNOWN_MAX_AGE_SECONDS}`,
+        "access-control-allow-origin": "*"
+      });
+      res.end(req.method === "HEAD" ? void 0 : read.body);
+      return;
+    }
+    if (url.pathname !== config.mcpPath) {
+      writeJson(res, 404, { error: "Not found." });
+      return;
+    }
+    const corsOrigin = allowedOriginOf(req.headers.origin, config);
+    if (req.method === "OPTIONS" && corsOrigin !== null) {
+      const host = hostnameOf(req.headers.host);
+      if (host === null || !config.allowedHosts.has(host)) {
+        writeJson(res, 421, { error: "Host is not allowed." });
+        return;
+      }
+      res.writeHead(204, {
+        "access-control-allow-origin": corsOrigin,
+        "access-control-allow-methods": "POST",
+        "access-control-allow-headers": CORS_REQUEST_HEADERS,
+        "access-control-max-age": String(PREFLIGHT_MAX_AGE_SECONDS),
+        vary: "Origin"
+      });
+      res.end();
+      return;
+    }
+    const refused = refusalFor(req, config, ["POST"]);
+    if (refused !== null) {
+      writeJson(res, refused.status, { error: refused.message }, refused.headers);
+      return;
+    }
+    if (!originAllowed(req.headers.origin, config)) {
+      writeJson(res, 403, { error: "Origin is not allowed." });
+      return;
+    }
+    if (corsOrigin !== null) {
+      res.setHeader("access-control-allow-origin", corsOrigin);
+      res.setHeader("access-control-expose-headers", CORS_EXPOSED_HEADERS);
+      res.setHeader("vary", "Origin");
+    }
+    const declared = Number(req.headers["content-length"] ?? "0");
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+      const drain = declared <= DRAIN_CEILING_BYTES;
+      writeJson(res, 413, { error: "Request body is too large." }, drain ? {} : { connection: "close" });
+      if (drain) req.resume();
+      else req.destroy();
+      return;
+    }
+    const clientIp = clientIpOf(req, config.trustedProxyHops);
+    const bearer = bearerOf(req);
+    if (bearer.present === false) {
+      unauthorized(res, null);
+      return;
+    }
+    const bucket = bearer.token === null ? void 0 : tokenBucketOf(bearer.token);
+    if (bearer.token === null || !isAccessTokenShaped(bearer.token)) {
+      failureBudget.record(clientIp, bucket);
+      unauthorized(res, new InvalidTokenError("The bearer is not an Everfur MCP access token."));
+      return;
+    }
+    let authInfo;
+    try {
+      authInfo = await verifier.verifyAccessToken(bearer.token, { clientIp, ...bucket === void 0 ? {} : { bucket } });
+    } catch (error) {
+      if (error instanceof InvalidTokenError) {
+        failureBudget.record(clientIp, bucket);
+        unauthorized(res, error);
+        return;
+      }
+      if (error instanceof TooManyRequestsError) {
+        throttled(res, error, clientIp, bucket);
+        return;
+      }
+      unavailable2(res, error instanceof TemporarilyUnavailableError ? error : new TemporarilyUnavailableError("The Everfur API could not verify this access token."));
+      return;
+    }
+    if (typeof authInfo.expiresAt !== "number" || authInfo.expiresAt * 1e3 <= (options.now ?? Date.now)()) {
+      failureBudget.record(clientIp, bucket);
+      unauthorized(res, new InvalidTokenError("The access token has expired."));
+      return;
+    }
+    const text = await readBody(req, res, MAX_BODY_BYTES);
+    if (text === null) return;
+    let parsedBody;
+    try {
+      parsedBody = JSON.parse(text);
+    } catch {
+      jsonRpcError(res, 400, -32700, "Parse error: Invalid JSON");
+      return;
+    }
+    const mcp = buildServer(
+      { env: {}, credentialSource: "hosted" },
+      {
+        transport,
+        clock,
+        contract: createHostedContractProvider({
+          apiBaseUrl: config.apiBaseUrl,
+          bearer: authInfo.token,
+          cache: contractCache,
+          transport,
+          clock,
+          onUnauthorized: () => verifier.forget(authInfo.token)
+        })
+      },
+      { instructions: HOSTED_MCP_INSTRUCTIONS, contextFor, readsLocalFiles: false }
+    );
+    await serveStatelessMcp(Object.assign(req, { auth: authInfo }), res, mcp, parsedBody);
+  };
+}
+async function startHostedMcpServer(options) {
+  const server = createServer(createHostedMcpRequestListener(options));
+  await listen(server, options.config.port, options.config.host);
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    await close(server);
+    throw new Error("The hosted MCP server did not bind a TCP address.");
+  }
+  const hostname = address.family === "IPv6" ? `[${address.address}]` : address.address;
+  return {
+    url: new URL(`http://${hostname}:${address.port}${options.config.mcpPath}`),
+    close: () => {
+      server.closeAllConnections();
+      return close(server);
+    }
+  };
+}
+
+export { loadHostedMcpConfig, startHostedMcpServer };