Merge pull request #285 from Blazity/feat/mcp-offline-access

feat(worker): issue refresh tokens via offline_access for MCP OAuth

Author: outof-place

apps/worker/src/auth.test.ts

@@ -311,7 +311,7 @@ describe("MCP OAuth provider", () => {
 
     await expect(auth.api.getOAuthServerConfig()).resolves.toMatchObject({
       issuer: "http://localhost:3000/api/auth",
-      scopes_supported: [...MCP_SCOPES],
+      scopes_supported: [...MCP_SCOPES, "offline_access"],
       registration_endpoint: "http://localhost:3000/api/auth/oauth2/register",
       code_challenge_methods_supported: expect.arrayContaining(["S256"]),
       grant_types_supported: expect.arrayContaining([

apps/worker/src/mcp/auth-pages.test.ts

@@ -102,6 +102,35 @@ describe("MCP auth pages", () => {
     expect(html).not.toContain("oauth_query");
   });
 
+  it("shows offline_access with an honest refresh-token description and keeps it in the posted scope", () => {
+    const html = renderMcpConsentPage({
+      clientName: "Agent",
+      redirectUri: "https://callback.example.com/oauth/callback",
+      requestedScopes: ["mcp:read", "offline_access"],
+      flowId: "flow-safe",
+    });
+
+    expect(html).toContain("offline_access");
+    expect(html).toContain("Stay signed in");
+    expect(html).toContain("not access to any of your data");
+    // The hidden field the browser posts back must carry offline_access, or the
+    // provider never issues a refresh token.
+    expect(html).toContain('name="scope" value="mcp:read offline_access"');
+  });
+
+  it("omits the refresh-token description when offline_access is not requested", () => {
+    const html = renderMcpConsentPage({
+      clientName: "Agent",
+      redirectUri: "https://callback.example.com/oauth/callback",
+      requestedScopes: ["mcp:read", "runs:dispatch"],
+      flowId: "flow-safe",
+    });
+
+    expect(html).not.toContain("offline_access");
+    expect(html).not.toContain("Stay signed in");
+    expect(html).toContain('name="scope" value="mcp:read runs:dispatch"');
+  });
+
   it("keeps signed oauth_query state HttpOnly and rejects missing, expired, or tampered state", () => {
     const now = new Date("2026-08-11T12:00:00.000Z");
     const cookie = createOAuthFlowCookie("client_id=abc&sig=opaque", SECRET, now);

apps/worker/src/mcp/auth-pages.ts

@@ -1,6 +1,18 @@
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 
-import { MCP_SCOPES, type McpScope } from "./contracts.js";
+import { MCP_SCOPES } from "./contracts.js";
+
+// offline_access is the standard OAuth2 / OIDC refresh-token marker, the same scope
+// Atlassian and Supabase surface on their consent screens. It is deliberately not an
+// MCP permission: request-context.ts materializes an actor's scope set by intersecting
+// against MCP_SCOPES, so offline_access can never become one. The consent path is the
+// one place it has to pass through, so the provider issues the 30-day refresh token,
+// which is why the consent allowlist is MCP_SCOPES plus this single marker. Every
+// consent spot (the get-gate, the rendered screen, and the post-grant) reads it through
+// allowedScopes, so this one list keeps all three in agreement by construction.
+export const OFFLINE_ACCESS_SCOPE = "offline_access";
+export const CONSENT_SCOPES = [...MCP_SCOPES, OFFLINE_ACCESS_SCOPE] as const;
+export type ConsentScope = (typeof CONSENT_SCOPES)[number];
 
 const FLOW_COOKIE = "mcp_oauth";
 const FLOW_TTL_SECONDS = 10 * 60;
@@ -164,17 +176,25 @@ export function renderMcpConsentPage(input: {
   const hostname = safeHostname(input.redirectUri);
   const scopes = allowedScopes(input.requestedScopes);
   const scopeList = scopes
-    .map((scope) => `<li><code>${escapeHtml(scope)}</code></li>`)
+    .map((scope) => `<li><code>${escapeHtml(scope)}</code>${scopeDescription(scope)}</li>`)
     .join("");
   return htmlPage(
     "Authorize MCP client",
     `<main class="card" aria-labelledby="consent-title"><p class="eyebrow">MCP authorization</p><h1 id="consent-title">Authorize ${escapeHtml(input.clientName)}</h1><p class="lede">This application is requesting access to your AI Workflow account.</p><dl class="details"><div><dt>Application</dt><dd>${escapeHtml(input.clientName)}</dd></div><div><dt>Redirect host</dt><dd><code>${escapeHtml(hostname)}</code></dd></div></dl><h2>Requested access</h2><ul class="scopes">${scopeList}</ul><form method="post" action="/mcp-auth/consent"><input type="hidden" name="flow_id" value="${escapeHtml(input.flowId)}"><input type="hidden" name="scope" value="${escapeHtml(scopes.join(" "))}"><div class="actions"><button class="secondary" name="accept" value="false" type="submit">Deny</button><button class="primary" name="accept" value="true" type="submit">Allow</button></div></form></main>`,
   );
 }
 
-export function allowedScopes(scopes: readonly string[]): McpScope[] {
-  const allowed = new Set<string>(MCP_SCOPES);
-  return [...new Set(scopes)].filter((scope): scope is McpScope => allowed.has(scope));
+// offline_access is not access to any data, so the screen says what it actually does
+// instead of showing a bare code the person cannot weigh. Every other scope renders as
+// its code alone, exactly as before.
+function scopeDescription(scope: ConsentScope): string {
+  if (scope !== OFFLINE_ACCESS_SCOPE) return "";
+  return "<small>Stay signed in. Lets this application refresh its own access without sending you back here. It is not access to any of your data.</small>";
+}
+
+export function allowedScopes(scopes: readonly string[]): ConsentScope[] {
+  const allowed = new Set<string>(CONSENT_SCOPES);
+  return [...new Set(scopes)].filter((scope): scope is ConsentScope => allowed.has(scope));
 }
 
 export function isSameOriginPost(request: Request, expectedOrigin: string): boolean {
@@ -216,5 +236,5 @@ function escapeHtml(value: string): string {
 }
 
 function htmlPage(title: string, body: string): string {
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)}</title><style>:root{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#172033;background:#f5f7fb}*{box-sizing:border-box}body{min-height:100vh;margin:0;display:grid;place-items:center;padding:24px;background:radial-gradient(circle at top,#fff 0,#f5f7fb 55%)}.card{width:min(100%,460px);padding:36px;border:1px solid #dfe5ef;border-radius:18px;background:#fff;box-shadow:0 18px 48px #17203314}.eyebrow{margin:0 0 10px;color:#53627a;font-size:12px;font-weight:700;letter-spacing:.12em;text-transform:uppercase}.lede{margin:0 0 26px;color:#53627a;line-height:1.55}h1{margin:0 0 10px;font-size:30px;letter-spacing:-.03em}h2{margin:28px 0 12px;font-size:15px}form{display:grid;gap:9px}label,dt{color:#344158;font-size:13px;font-weight:650}input{width:100%;margin:0 0 8px;padding:11px 12px;border:1px solid #cbd4e2;border-radius:9px;background:#fff;color:inherit;font:inherit}input:focus{outline:3px solid #b9d7ff;border-color:#377dcc}button,.secondary{display:inline-flex;align-items:center;justify-content:center;min-height:42px;padding:10px 16px;border-radius:9px;font:inherit;font-weight:700;text-decoration:none;cursor:pointer}.primary{border:1px solid #1f5fa8;background:#1f5fa8;color:#fff}.secondary{border:1px solid #b9c5d6;background:#fff;color:#24334d}.divider{display:flex;align-items:center;gap:12px;margin:22px 0;color:#8490a3;font-size:12px}.divider:before,.divider:after{content:"";height:1px;flex:1;background:#e3e8f0}.fine-print{margin:18px 0 0;color:#718097;font-size:12px;line-height:1.5;text-align:center}.error{margin:0 0 18px;padding:10px 12px;border:1px solid #efb9b9;border-radius:9px;background:#fff4f4;color:#a52f2f;font-size:13px}.details{display:grid;gap:12px;margin:24px 0;padding:16px;border-radius:12px;background:#f6f8fb}.details div{display:grid;gap:4px}.details dd{margin:0;color:#53627a;font-size:14px}.scopes{display:grid;gap:9px;margin:0;padding:0;list-style:none}.scopes li{padding:11px 12px;border:1px solid #e1e7f0;border-radius:9px;background:#fbfcfe}.scopes code,dd code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px}.actions{display:flex;justify-content:flex-end;gap:10px;margin-top:28px}</style></head><body>${body}</body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)}</title><style>:root{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#172033;background:#f5f7fb}*{box-sizing:border-box}body{min-height:100vh;margin:0;display:grid;place-items:center;padding:24px;background:radial-gradient(circle at top,#fff 0,#f5f7fb 55%)}.card{width:min(100%,460px);padding:36px;border:1px solid #dfe5ef;border-radius:18px;background:#fff;box-shadow:0 18px 48px #17203314}.eyebrow{margin:0 0 10px;color:#53627a;font-size:12px;font-weight:700;letter-spacing:.12em;text-transform:uppercase}.lede{margin:0 0 26px;color:#53627a;line-height:1.55}h1{margin:0 0 10px;font-size:30px;letter-spacing:-.03em}h2{margin:28px 0 12px;font-size:15px}form{display:grid;gap:9px}label,dt{color:#344158;font-size:13px;font-weight:650}input{width:100%;margin:0 0 8px;padding:11px 12px;border:1px solid #cbd4e2;border-radius:9px;background:#fff;color:inherit;font:inherit}input:focus{outline:3px solid #b9d7ff;border-color:#377dcc}button,.secondary{display:inline-flex;align-items:center;justify-content:center;min-height:42px;padding:10px 16px;border-radius:9px;font:inherit;font-weight:700;text-decoration:none;cursor:pointer}.primary{border:1px solid #1f5fa8;background:#1f5fa8;color:#fff}.secondary{border:1px solid #b9c5d6;background:#fff;color:#24334d}.divider{display:flex;align-items:center;gap:12px;margin:22px 0;color:#8490a3;font-size:12px}.divider:before,.divider:after{content:"";height:1px;flex:1;background:#e3e8f0}.fine-print{margin:18px 0 0;color:#718097;font-size:12px;line-height:1.5;text-align:center}.error{margin:0 0 18px;padding:10px 12px;border:1px solid #efb9b9;border-radius:9px;background:#fff4f4;color:#a52f2f;font-size:13px}.details{display:grid;gap:12px;margin:24px 0;padding:16px;border-radius:12px;background:#f6f8fb}.details div{display:grid;gap:4px}.details dd{margin:0;color:#53627a;font-size:14px}.scopes{display:grid;gap:9px;margin:0;padding:0;list-style:none}.scopes li{padding:11px 12px;border:1px solid #e1e7f0;border-radius:9px;background:#fbfcfe}.scopes code,dd code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px}.scopes small{display:block;margin-top:6px;color:#53627a;font-size:12px;line-height:1.45}.actions{display:flex;justify-content:flex-end;gap:10px;margin-top:28px}</style></head><body>${body}</body></html>`;
 }

apps/worker/src/mcp/oauth-metadata.test.ts

@@ -80,6 +80,7 @@ describe("MCP OAuth discovery", () => {
         "prompts:write",
         "workflows:write",
         "tickets:write",
+        "offline_access",
       ],
       code_challenge_methods_supported: ["S256"],
       grant_types_supported: expect.arrayContaining([

apps/worker/src/mcp/oauth.test.ts

@@ -54,7 +54,7 @@ describe("MCP OAuth provider options", () => {
   it("advertises the exact scopes, S256, and supported grants", () => {
     const options = createMcpOAuthOptions(DEPLOYMENT);
 
-    expect(options.scopes).toEqual(MCP_SCOPES);
+    expect(options.scopes).toEqual([...MCP_SCOPES, "offline_access"]);
     expect(options.validAudiences).toEqual(["https://worker.example.com/mcp"]);
     expect(options.grantTypes).toEqual(
       expect.arrayContaining(["authorization_code", "client_credentials", "refresh_token"]),
@@ -63,6 +63,19 @@ describe("MCP OAuth provider options", () => {
     expect(options.silenceWarnings).toEqual({ oauthAuthServerConfig: true });
   });
 
+  it("advertises offline_access as a registrable but opt-in refresh-token scope", () => {
+    const options = createMcpOAuthOptions(DEPLOYMENT);
+
+    // Advertised in AS metadata and allowed at /authorize and DCR, so an interactive
+    // client can request a refresh token by asking for it.
+    expect(options.scopes).toContain("offline_access");
+    expect(options.clientRegistrationAllowedScopes).toContain("offline_access");
+    // Never a default, so it is opt-in and is never written into an unattended
+    // client's grant. request-context.ts drops it from the actor's permission set.
+    expect(options.clientRegistrationDefaultScopes).not.toContain("offline_access");
+    expect(options.clientCredentialGrantDefaultScopes).not.toContain("offline_access");
+  });
+
   it("keeps unauthenticated DCR disabled by default", () => {
     const options = createMcpOAuthOptions(DEPLOYMENT);
 

apps/worker/src/mcp/oauth.ts

@@ -60,10 +60,19 @@ export function createMcpOAuthOptions(deployment: McpOAuthDeployment) {
   const automationScopes = scopes.filter(
     (scope) => scope !== "prompts:write" && scope !== "workflows:write",
   );
+  // offline_access is the standard OAuth2/OIDC marker a client sends to ask for a
+  // refresh token, the same way Atlassian and Supabase do it. It is advertised and
+  // registrable so an interactive client can opt in, but it is permission-inert:
+  // request-context.ts materializes an actor's scope set by intersecting the token's
+  // issued scopes against MCP_SCOPES, so offline_access never becomes a permission.
+  // It stays out of both defaults below, so it is opt-in and never written into an
+  // unattended client's grant.
+  const OFFLINE_ACCESS = "offline_access";
+  const advertisedScopes = [...scopes, OFFLINE_ACCESS];
   const resolveOrganizationId = () => deploymentOrganizationId(deployment);
 
   const options = {
-    scopes,
+    scopes: advertisedScopes,
     validAudiences: [canonicalMcpResource(baseURL)],
     grantTypes: [
       "authorization_code",
@@ -76,7 +85,7 @@ export function createMcpOAuthOptions(deployment: McpOAuthDeployment) {
     allowDynamicClientRegistration: true,
     allowUnauthenticatedClientRegistration: deployment.allowPublicDcr ?? false,
     clientRegistrationDefaultScopes: scopes,
-    clientRegistrationAllowedScopes: scopes,
+    clientRegistrationAllowedScopes: advertisedScopes,
     clientCredentialGrantDefaultScopes: automationScopes,
     codeChallengeMethodsSupported: ["S256"] as const,
     silenceWarnings: { oauthAuthServerConfig: true },

apps/worker/src/mcp/request-context.test.ts

@@ -84,6 +84,23 @@ describe("requireMcpActor", () => {
     });
   });
 
+  // offline_access is the refresh-token marker, never a permission. Both the token
+  // claim and the client row carry it here, so the only thing that can remove it is
+  // the MCP_SCOPES intersection in request-context.ts, which is the mechanism the
+  // whole "permission-inert" argument rests on.
+  it("never lets offline_access leak into the actor's permission scopes", async () => {
+    await db
+      .update(oauthClient)
+      .set({ scopes: ["mcp:read", "runs:dispatch", "offline_access"] });
+    state.verifyAccessToken.mockResolvedValue(
+      userClaims({ scope: "mcp:read runs:dispatch offline_access" }),
+    );
+
+    const actor = await requireMcpActor(request());
+
+    expect(actor.scopes).toEqual(new Set(["mcp:read", "runs:dispatch"]));
+  });
+
   it("normalizes an admin membership instead of trusting the token role", async () => {
     await db.update(member).set({ role: "admin" });
     state.verifyAccessToken.mockResolvedValue(userClaims({ organization_role: "member" }));

apps/worker/src/routes/mcp-auth/consent.get.test.ts

@@ -88,6 +88,35 @@ describe("MCP consent screen", () => {
     expect(response.status).toBe(400);
   });
 
+  it("renders offline_access as a refresh-token scope when the client requests it", async () => {
+    const response = await handlerFor(consentRoute)(
+      new Request(consentUrl({ scope: "mcp:read offline_access" })),
+    );
+
+    expect(response.status).toBe(200);
+    const body = await response.text();
+    expect(body).toContain("offline_access");
+    expect(body).toContain("Stay signed in");
+    // The hidden field the browser posts back has to carry it, or the provider never
+    // issues a refresh token.
+    expect(body).toContain('name="scope" value="mcp:read offline_access"');
+  });
+
+  it("leaves a request without offline_access exactly as it was", async () => {
+    const response = await handlerFor(consentRoute)(
+      new Request(
+        consentUrl({
+          scope: "mcp:read runs:dispatch prompts:write workflows:write tickets:write",
+        }),
+      ),
+    );
+
+    expect(response.status).toBe(200);
+    const body = await response.text();
+    expect(body).not.toContain("offline_access");
+    expect(body).not.toContain("Stay signed in");
+  });
+
   it("still refuses an unregistered or edited redirect, whose signature prelogin rejects", async () => {
     // This is the negative case for the check the route no longer performs.
     // Two independent guards keep it covered, both verified against the

apps/worker/src/routes/mcp-auth/consent.post.test.ts

@@ -57,7 +57,7 @@ function handlerFor(route: Parameters<typeof eventHandler>[0]) {
   return toWebHandler(app);
 }
 
-function consentUrl(): string {
+function consentUrl(overrides: Record<string, string> = {}): string {
   const query = new URLSearchParams({
     response_type: "code",
     client_id: CLIENT_ID,
@@ -69,13 +69,14 @@ function consentUrl(): string {
     exp: "1786597132",
     ba_iat: "1786596532923",
     sig: "0e6g9sZI2vvfQEnndJjoGGfdPi2kfBu9W21XvBmGbe4=",
+    ...overrides,
   });
   return `https://worker.example.com/mcp-auth/consent?${query.toString()}`;
 }
 
 /** Walks the browser's half: render the page, then post the form it rendered. */
-async function renderThenApprove(accept = "true") {
-  const rendered = await handlerFor(consentGet)(new Request(consentUrl()));
+async function renderThenApprove(accept = "true", url = consentUrl()) {
+  const rendered = await handlerFor(consentGet)(new Request(url));
   expect(rendered.status).toBe(200);
   const html = await rendered.text();
   const setCookie = rendered.headers.get("set-cookie") ?? "";
@@ -126,6 +127,23 @@ describe("MCP consent POST", () => {
     expect(response.headers.get("set-cookie")).toContain("Max-Age=0");
   });
 
+  it("grants offline_access to the provider so it issues a refresh token", async () => {
+    const { response } = await renderThenApprove(
+      "true",
+      consentUrl({ scope: "mcp:read runs:dispatch offline_access" }),
+    );
+
+    expect(response.status).toBe(302);
+    const request = state.authHandler.mock.calls[0]?.[0] as Request;
+    const posted = (await request.json()) as { scope: string };
+    // dist/index.mjs:509 only mints a refresh token when the granted scopes include
+    // offline_access, so it has to survive all the way to this POST.
+    expect(posted.scope.split(" ")).toContain("offline_access");
+    expect(posted.scope.split(" ")).toEqual(
+      expect.arrayContaining(["mcp:read", "runs:dispatch", "offline_access"]),
+    );
+  });
+
   it("carries a denial through instead of pretending it approved", async () => {
     const { response } = await renderThenApprove("false");