@12-apps/mcp 1.19.0 → 2.0.0

package/src/guide.ts

@@ -99,104 +99,125 @@ const CONNECTOR_TAIL: readonly string[] = [
  * stage 2 creates the connector and signs in — which registers the connection on
  * the store side, so no prompt needs to be pasted afterwards.
  */
-const CHATGPT_CONFIGURE_STAGES: readonly AiHostConfigureStage[] = [
-  {
-    id: "enable-dev-mode",
-    label: "enable developer mode",
-    link: {
-      url: "https://chatgpt.com/plugins#settings/Security",
-      label: "Abrir Segurança e login",
+function chatgptConfigureStages(
+  platformName: string,
+): readonly AiHostConfigureStage[] {
+  return [
+    {
+      id: "enable-dev-mode",
+      label: "enable developer mode",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Security",
+        label: "Abrir Segurança e login",
+      },
+      steps: [
+        "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
+      ],
     },
-    steps: [
-      "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
-    ],
-  },
-  {
-    id: "configurar",
-    label: "configurar",
-    link: {
-      url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
-      label: "Criar o conector",
+    {
+      id: "configurar",
+      label: "configurar",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
+        label: "Criar o conector",
+      },
+      steps: [
+        "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
+        'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
+        `Clique em "Sign in with ${platformName}" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.`,
+      ],
     },
-    steps: [
-      "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
-      'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
-      'Clique em "Sign in with Future Drink" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.',
-    ],
-  },
-];
+  ];
+}
 
 /**
  * The AI hosts a store owner can connect, in recommended order. Same OAuth flow
  * everywhere (the host drives it) — only the menu path differs per app.
+ *
+ * A FUNCTION of the platform's name, because one step is not generic: the
+ * ChatGPT connector's consent screen shows an OAuth button labelled with
+ * whoever operates the server, and the owner is told which button to click. It
+ * used to name one particular STORE on one particular deployment — not even the
+ * product, a tenant of it — so every other adopter instructed its owners to
+ * click a button that does not exist.
  */
-export const AI_HOST_GUIDES: readonly AiHostGuide[] = [
-  {
-    id: "claude",
-    label: "Claude.ai",
-    brand: "claude",
-    kind: "No navegador",
-    link: {
-      url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
-      label: "Abrir os conectores do Claude",
-    },
-    docs: {
-      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-      label: "documentação oficial da Anthropic — conectores personalizados",
+export function aiHostGuides(platformName: string): readonly AiHostGuide[] {
+  const chatgptStages = chatgptConfigureStages(platformName);
+  return [
+    {
+      id: "claude",
+      label: "Claude.ai",
+      brand: "claude",
+      kind: "No navegador",
+      link: {
+        url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
+        label: "Abrir os conectores do Claude",
+      },
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
+        "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
-      "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-  {
-    id: "claude-desktop",
-    label: "Claude Desktop",
-    brand: "claude",
-    kind: "Aplicativo (Windows/Mac)",
-    docs: {
-      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-      label: "documentação oficial da Anthropic — conectores personalizados",
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      brand: "claude",
+      kind: "Aplicativo (Windows/Mac)",
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
+        "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
-      "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-  {
-    id: "chatgpt",
-    label: "ChatGPT",
-    brand: "openai",
-    kind: "No navegador",
-    link: { url: "https://chatgpt.com/plugins", label: "Abrir os plugins do ChatGPT" },
-    docs: {
-      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-      label: "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+    {
+      id: "chatgpt",
+      label: "ChatGPT",
+      brand: "openai",
+      kind: "No navegador",
+      link: {
+        url: "https://chatgpt.com/plugins",
+        label: "Abrir os plugins do ChatGPT",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label:
+          "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+      },
+      configureStages: chatgptStages,
+      // Mirrors the flattened stage instructions so the MCP connect guide
+      // (`connectToChatGpt`) can never drift from what owners see in the wizard.
+      steps: chatgptStages.flatMap((stage) => stage.steps),
     },
-    configureStages: CHATGPT_CONFIGURE_STAGES,
-    // Mirrors the flattened stage instructions so the MCP connect guide
-    // (`connectToChatGpt`) can never drift from what owners see in the wizard.
-    steps: CHATGPT_CONFIGURE_STAGES.flatMap((stage) => stage.steps),
-  },
-  {
-    id: "codex",
-    label: "Codex",
-    brand: "openai",
-    kind: "App / CLI de desenvolvedor",
-    link: { url: "https://developers.openai.com/codex", label: "Documentação do Codex" },
-    docs: {
-      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-      label: "documentação oficial da OpenAI — conectar um servidor MCP",
+    {
+      id: "codex",
+      label: "Codex",
+      brand: "openai",
+      kind: "App / CLI de desenvolvedor",
+      link: {
+        url: "https://developers.openai.com/codex",
+        label: "Documentação do Codex",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label: "documentação oficial da OpenAI — conectar um servidor MCP",
+      },
+      steps: [
+        "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
+        "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
-      "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-];
+  ];
+}
 
 export interface AiCapability {
   /** Stable id — maps to an icon in the component. */
@@ -217,7 +238,8 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
   {
     id: "inventory",
     title: "Controle o estoque",
-    detail: '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
+    detail:
+      '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
   },
   {
     id: "catalog",
@@ -239,15 +261,39 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
 export const AI_PERMISSION_MODEL =
   "O assistente age em seu nome, com exatamente as suas permissões: ele pode fazer o que você pode fazer na sua loja — nada além disso. Não é preciso criar nenhuma chave ou credencial extra; a autorização usa o seu próprio login.";
 
+/** The two tools the paste-in prompt drives, and what to call the store id. */
+export interface AiConnectPromptSpec {
+  /**
+   * The tool that REGISTERS the connection server-side, so the store learns
+   * which assistant connected.
+   */
+  announceTool: string;
+  /** A real READ tool, called straight after, to prove the access works. */
+  probeTool: string;
+  /** What that read returns, in the owner's own words ("o estoque da loja"). */
+  probeSubject: string;
+  /** What the assistant should ask for if it needs to identify the store. */
+  identifierName: string;
+}
+
 /**
- * The message the owner pastes into the assistant's chat right after connecting.
- * It makes the assistant (1) call `announceAiConnection` reporting which host it
- * is (chatgpt / claude / codex) — the tool that registers the connection on the
- * server side so the store learns which assistant connected — and (2) call a
- * real read tool to confirm access. The owner types nothing.
+ * The message the owner pastes into the assistant's chat right after
+ * connecting: announce the connection, then read something real to prove it
+ * works. The owner types nothing.
+ *
+ * BUILT from the host's tool names rather than shipped with them. This was a
+ * constant naming two tools — `announceAiConnection` and `listInventory` — that
+ * THIS PACKAGE does not define or serve; they belong to one adopter's surface.
+ * Any other host handed its owner a prompt instructing the assistant to call
+ * two tools that do not exist, and because nothing registered the connection,
+ * the wizard's confirm step then waited forever for a state that could never
+ * arrive.
  */
-export const AI_CONNECT_PROMPT =
-  "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
-  '1) Execute a ferramenta announceAiConnection informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n' +
-  "2) Execute a ferramenta listInventory para confirmar o acesso ao estoque da minha loja.\n" +
-  "Se precisar do identificador da loja, me pergunte o tenantSlug.";
+export function aiConnectPrompt(spec: AiConnectPromptSpec): string {
+  return (
+    "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
+    `1) Execute a ferramenta ${spec.announceTool} informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n` +
+    `2) Execute a ferramenta ${spec.probeTool} para confirmar o acesso a ${spec.probeSubject}.\n` +
+    `Se precisar do identificador da loja, me pergunte o ${spec.identifierName}.`
+  );
+}

package/src/hono/index.ts

@@ -0,0 +1,43 @@
+import { Hono } from "hono";
+import type { Context } from "hono";
+
+import {
+  createApiMcpOauth,
+  type ApiMcpOauth,
+} from "../oauth/create-api-mcp-oauth";
+import type { McpOauthConfig } from "../oauth/context";
+
+/**
+ * `@12-apps/mcp/hono` — the OAuth authorization server as a mountable router.
+ *
+ * Behind its own subpath with `hono` as an OPTIONAL peer (the report-builder / rbac
+ * precedent), so a host on another framework — or one importing only the tool
+ * generator — never resolves it.
+ *
+ * Mounted at the ORIGIN ROOT, because two of the six paths are `.well-known`
+ * documents and a connector reads them from the origin, not from a prefix:
+ *
+ *   const oauth = mcpOauthRouter({ stores, resolveSession });
+ *   app.route('/', oauth.router);
+ *
+ * The adapter is deliberately thin: each handler already answers a Fetch `Response`
+ * (a 302 with a `Location`, RFC 6749 JSON, an RFC 8414 document), and those shapes
+ * are fixed by specification — there is no envelope to apply, and applying one
+ * would break every client.
+ */
+export interface McpOauthHono extends ApiMcpOauth {
+  router: Hono;
+}
+
+export function mcpOauthRouter(config: McpOauthConfig): McpOauthHono {
+  const api = createApiMcpOauth(config);
+  const router = new Hono();
+
+  for (const route of api.routes) {
+    const handler = (c: Context): Promise<Response> => route.handle(c.req.raw);
+    if (route.method === "GET") router.get(route.path, handler);
+    else router.post(route.path, handler);
+  }
+
+  return { ...api, router };
+}

package/src/index.ts

@@ -13,10 +13,11 @@ export * from "./types";
 // truth for BOTH the `@12-apps/mcp/react` onboarding UI and the server-side connect
 // tools, so what an agent reads via MCP cannot drift from what owners see.
 export {
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_CAPABILITIES,
   AI_PERMISSION_MODEL,
-  AI_CONNECT_PROMPT,
+  aiConnectPrompt,
+  type AiConnectPromptSpec,
   providerForHostId,
   type AiHostBrand,
   type AiHostLink,
@@ -73,4 +74,5 @@ export {
   buildAuthorizationServerMetadata,
   type AuthorizationServerMetadata,
   type AuthorizationServerMetadataInput,
+  type AuthorizationServerPaths,
 } from "./auth/authorization-server-metadata";

package/src/oauth/access-token.ts

@@ -0,0 +1,186 @@
+import { SignJWT, jwtVerify, importJWK, type JWTPayload } from "jose";
+
+import { issuer, resourceAudience, DEFAULT_MCP_RESOURCE_PATH, type McpScope } from "./config";
+import { SIGNING_ALG, type McpSigningKeyProvider } from "./keys";
+
+/**
+ * JWT access-token issuer + verifier (12-23, ported from future-pay's
+ * `lib/mcp/oauth/jwt.ts` — behaviour unchanged; the signing key arrives through a
+ * provider and the resource path is config).
+ *
+ * The access token is a short-lived, ES256-signed JWT bound to the signed-in
+ * user. It carries the claims the resource server checks LOCALLY against the
+ * published JWKS (no introspection round-trip): `iss` (the issuer origin), `aud`
+ * (`${origin}${resourcePath}`), `sub`, `email`, `scope` (space-delimited), `iat`,
+ * `exp` (short TTL), and `jti`; the JWT header carries `kid` so the verifier can
+ * select the public key during rotation.
+ *
+ * Failures are typed so the caller maps them to the right OAuth challenge
+ * (`invalid_token` vs `insufficient_scope`).
+ */
+
+/** Access-token lifetime — short-lived (15 min) per the spec. */
+export const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
+
+/** Clock skew tolerated on `exp`/`iat` validation, in seconds. */
+const CLOCK_TOLERANCE_SECONDS = 5;
+
+/** The identity a verified access token resolves to. */
+export interface VerifiedAccessToken {
+  email: string;
+  subject: string;
+  scopes: string[];
+}
+
+/** Distinct verification failure reasons the caller maps to OAuth challenges. */
+export type AccessTokenErrorCode = "invalid_token" | "insufficient_scope";
+
+/** A typed verification failure — `code` drives the `WWW-Authenticate` challenge. */
+export class AccessTokenError extends Error {
+  readonly code: AccessTokenErrorCode;
+
+  constructor(code: AccessTokenErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = "AccessTokenError";
+    this.code = code;
+  }
+}
+
+/** Inputs bound into a minted access token. */
+export interface SignAccessTokenInput {
+  email: string;
+  subject: string;
+  scopes: readonly McpScope[] | readonly string[];
+  origin: string;
+  /** Where the MCP resource is mounted. Default `/api/mcp`. */
+  resourcePath?: string;
+  /** Token lifetime in seconds. Default 15 minutes. */
+  ttlSeconds?: number;
+}
+
+/** Deterministic-clock option shared by mint + verify. */
+interface ClockOption {
+  /** Epoch milliseconds; defaults to `Date.now()`. Injected for deterministic tests. */
+  now?: number;
+}
+
+/** The full access-token claim set (beyond the registered JWT claims). */
+interface AccessTokenClaims extends JWTPayload {
+  email: string;
+  scope: string;
+}
+
+function nowSeconds(now?: number): number {
+  return Math.floor((now ?? Date.now()) / 1000);
+}
+
+/**
+ * Mint an ES256-signed access token bound to the user.
+ *
+ * Returns `null` when no signing key is configured (safe-by-default: the AS
+ * refuses to issue rather than falling back to a weaker mode). Sets the `kid`
+ * header from the loaded key so the verifier can resolve the public JWK during
+ * rotation.
+ */
+export async function signAccessToken(
+  loadSigningKey: McpSigningKeyProvider,
+  input: SignAccessTokenInput,
+  options?: ClockOption,
+): Promise<string | null> {
+  const key = await loadSigningKey();
+  if (!key) return null;
+
+  const iat = nowSeconds(options?.now);
+  const exp = iat + (input.ttlSeconds ?? ACCESS_TOKEN_TTL_SECONDS);
+  const scope = input.scopes.join(" ");
+
+  return new SignJWT({ email: input.email, scope } satisfies AccessTokenClaims)
+    .setProtectedHeader({ alg: SIGNING_ALG, kid: key.kid })
+    .setIssuer(issuer(input.origin))
+    .setAudience(resourceAudience(input.origin, input.resourcePath ?? DEFAULT_MCP_RESOURCE_PATH))
+    .setSubject(input.subject)
+    .setIssuedAt(iat)
+    .setExpirationTime(exp)
+    .setJti(crypto.randomUUID())
+    .sign(key.privateKey);
+}
+
+/** Options for {@link verifyAccessToken}. */
+export interface VerifyAccessTokenOptions extends ClockOption {
+  /** The deployment origin — derives the expected `iss` and `aud`. */
+  origin: string;
+  /** Where the MCP resource is mounted. Default `/api/mcp`. */
+  resourcePath?: string;
+  /** When set, the token must carry this scope or verification fails `insufficient_scope`. */
+  requiredScope?: McpScope | string;
+}
+
+/** Parse the space-delimited `scope` claim into a de-duplicated string array. */
+function parseScopes(scope: unknown): string[] {
+  if (typeof scope !== "string" || scope.trim() === "") return [];
+  return [...new Set(scope.trim().split(/\s+/))];
+}
+
+/**
+ * Verify a bearer access token locally against the published JWKS public key.
+ *
+ * Checks signature (via the public JWK selected by the token's `kid`), `iss`,
+ * `aud`, and `exp`. When `requiredScope` is supplied, also enforces scope. On
+ * success returns `{ email, subject, scopes }`; on failure throws an
+ * {@link AccessTokenError} whose `code` distinguishes `invalid_token` (bad
+ * signature / wrong issuer / wrong audience / expired / malformed / unconfigured
+ * key) from `insufficient_scope` (a valid token lacking the required scope).
+ */
+/**
+ * The cryptographic half: signature, `iss`, `aud`, `exp`.
+ *
+ * Every jose failure — bad signature, wrong issuer, wrong audience, expiry,
+ * malformed token, unknown key — collapses into ONE opaque `invalid_token`. A
+ * message naming the failed claim would be an oracle for the next attempt.
+ */
+async function verifiedPayload(
+  loadSigningKey: McpSigningKeyProvider,
+  token: string,
+  options: VerifyAccessTokenOptions,
+): Promise<JWTPayload> {
+  const key = await loadSigningKey();
+  // No signing key configured → nothing can verify (safe-by-default).
+  if (!key) throw new AccessTokenError("invalid_token", "no signing key configured");
+
+  try {
+    const { payload } = await jwtVerify(token, await importJWK(key.publicJwk, SIGNING_ALG), {
+      algorithms: [SIGNING_ALG],
+      issuer: issuer(options.origin),
+      audience: resourceAudience(options.origin, options.resourcePath ?? DEFAULT_MCP_RESOURCE_PATH),
+      clockTolerance: CLOCK_TOLERANCE_SECONDS,
+      currentDate: options.now === undefined ? undefined : new Date(options.now),
+    });
+    return payload;
+  } catch {
+    throw new AccessTokenError("invalid_token", "token verification failed");
+  }
+}
+
+export async function verifyAccessToken(
+  loadSigningKey: McpSigningKeyProvider,
+  token: string,
+  options: VerifyAccessTokenOptions,
+): Promise<VerifiedAccessToken> {
+  const payload = await verifiedPayload(loadSigningKey, token, options);
+
+  const email = typeof payload.email === "string" ? payload.email : null;
+  const subject = typeof payload.sub === "string" ? payload.sub : null;
+  if (!email || !subject) {
+    throw new AccessTokenError("invalid_token", "missing subject or email claim");
+  }
+
+  const scopes = parseScopes(payload.scope);
+  if (options.requiredScope && !scopes.includes(options.requiredScope)) {
+    throw new AccessTokenError(
+      "insufficient_scope",
+      `token lacks required scope '${options.requiredScope}'`,
+    );
+  }
+
+  return { email, subject, scopes };
+}