Public: anyone can read this; the crew can change it.
The OAuth consent page names the client and lists each scope in plain words #13614
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13601-the-oauth-consent-page-names-the-client → main 3 commits fork 2 threads · 2 unresolved
5 files
changed +128
−14
docs/features/README.md +1
| @@ -378,6 +378,7 @@ Read with the guide page [Agents: MCP, git, or the terminal](../guide-agents.md) | ||
| 378 | 378 | - [](atom.md) |
| 379 | 379 | - [](guest-pulls.md) |
| 380 | 380 | - [](guests.md) |
| 381 | - [](oauth-consent.md) | |
| 381 | 382 | - [](oauth-grants.md) |
| 382 | 383 | - [](oauth-refresh.md) |
| 383 | 384 | - [](oauth-revoke.md) |
docs/features/oauth-consent.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # OAuth consent words | |
| 2 | ||
| 3 | `/oauth/authorize` names the client (its registered name), the host it will | |
| 4 | send you back to (host only), and one plain sentence for each scope it asked | |
| 5 | for, shown once: `ro`/`rw` on the choices, `openid`, `profile`, `email` under what it learns. | |
| 6 | ||
| 7 | The sentences live in one table, `SCOPE_WORDS` in `src/core/oauth.ts`, which | |
| 8 | the page, and the Read/Read and act choices on it, read from. Scopes the forge does not offer are ignored, as before. | |
| 9 | ||
| 10 | The client's name is escaped wherever it is shown. |
src/core/oauth.ts +17 −2
| @@ -7,7 +7,7 @@ import type { Database } from "bun:sqlite"; | ||
| 7 | 7 | import { sha256 } from "../kernel/hash.ts"; |
| 8 | 8 | import { id, secret } from "../kernel/id.ts"; |
| 9 | 9 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 10 | import { NONCE_MAX, oidcScopes, recordGrant, signIdToken } from "./oidc.ts"; | |
| 10 | import { NONCE_MAX, oidcScopes, recordGrant, signIdToken, type OidcScope } from "./oidc.ts"; | |
| 11 | 11 | import { createToken, listTokens, type TokenInfo } from "./tokens.ts"; |
| 12 | 12 | import { getUserById, isActive } from "./users.ts"; |
| 13 | 13 | |
| @@ -187,6 +187,20 @@ export type OAuthScope = (typeof OAUTH_SCOPES)[number]; | ||
| 187 | 187 | export const isOAuthScope = (v: string): v is OAuthScope => |
| 188 | 188 | OAUTH_SCOPES.some((scope) => scope === v); |
| 189 | 189 | |
| 190 | /** | |
| 191 | * One plain sentence per scope the authorize page can name: the page reads | |
| 192 | * its words here, so a scope cannot be granted that has no sentence, and a | |
| 193 | * sentence cannot outlive its scope. `ro`/`rw` are the API grants, the rest | |
| 194 | * are what an OpenID sign-in tells the app about the person. | |
| 195 | */ | |
| 196 | export const SCOPE_WORDS: Readonly<Record<OAuthScope | OidcScope, string>> = { | |
| 197 | ro: "Read: see your apps, issues and runs", | |
| 198 | rw: "Read and act: tell the crew, plan, and change things as you", | |
| 199 | openid: "who you are on this forge (an identifier that stays the same)", | |
| 200 | profile: "your username and name", | |
| 201 | email: "your email address", | |
| 202 | }; | |
| 203 | ||
| 190 | 204 | /** A valid authorization request: the client is real and the redirect is one it registered. */ |
| 191 | 205 | export interface AuthRequest { |
| 192 | 206 | readonly client: OAuthClient; |
| @@ -195,7 +209,7 @@ export interface AuthRequest { | ||
| 195 | 209 | readonly state: string; |
| 196 | 210 | readonly scope: OAuthScope; |
| 197 | 211 | /** `openid` and the OIDC scopes asked with it; empty for a plain OAuth grant. */ |
| 198 | readonly oidcScopes: readonly string[]; | |
| 212 | readonly oidcScopes: readonly OidcScope[]; | |
| 199 | 213 | readonly nonce: string; |
| 200 | 214 | /** OpenID scopes and no `ro`/`rw`: the person is signed in, no API token is granted. */ |
| 201 | 215 | readonly signInOnly: boolean; |
| @@ -229,6 +243,7 @@ export function parseAuthRequest( | ||
| 229 | 243 | return err("The code_challenge is not a base64url SHA-256."); |
| 230 | 244 | const state = get("state"); |
| 231 | 245 | if (state.length > STATE_MAX) return err("The state is too long."); |
| 246 | // Scopes the forge does not offer are ignored, as they always were. | |
| 232 | 247 | const asked = get("scope").split(/\s+/).find(isOAuthScope); |
| 233 | 248 | const oidc = oidcScopes(get("scope")); |
| 234 | 249 | const openid = oidc.includes("openid"); |
src/web/pages/oauth.ts +7 −12
| @@ -11,6 +11,7 @@ import { | ||
| 11 | 11 | LIFETIMES, |
| 12 | 12 | parseAuthRequest, |
| 13 | 13 | redirectWith, |
| 14 | SCOPE_WORDS, | |
| 14 | 15 | tokenName, |
| 15 | 16 | type AuthRequest, |
| 16 | 17 | } from "../../core/oauth.ts"; |
| @@ -36,8 +37,9 @@ const PARAMS = [ | ||
| 36 | 37 | /** Nothing here is cacheable, and nothing here may be sent on as a referrer. */ |
| 37 | 38 | const guard = (response: Response): Response => { |
| 38 | 39 | response.headers.set("cache-control", "no-store"); |
| 39 | // same-origin, not no-referrer: no-referrer makes the browser send `Origin: null` on the consent form's | |
| 40 | // own POST, and the CSRF gate refused every consent (2026-10-27). Other sites still get no referrer. | |
| 40 | // same-origin, not no-referrer: no-referrer makes the browser send `Origin: null` on the consent | |
| 41 | // form's own POST, and the CSRF gate refused every consent (2026-10-27). Other sites still get no | |
| 42 | // referrer. | |
| 41 | 43 | response.headers.set("referrer-policy", "same-origin"); |
| 42 | 44 | return response; |
| 43 | 45 | }; |
| @@ -77,20 +79,13 @@ const refused = (ctx: Ctx, message: string): Response => | ||
| 77 | 79 | const hidden = (name: string, value: string): Html => |
| 78 | 80 | html`<input type="hidden" name="${name}" value="${value}" />`; |
| 79 | 81 | |
| 80 | /** What an OpenID grant tells the app about the person, in plain words. */ | |
| 81 | const IDENTITY: Record<string, string> = { | |
| 82 | openid: "who you are on this forge (an identifier that stays the same)", | |
| 83 | profile: "your username and name", | |
| 84 | email: "your email address", | |
| 85 | }; | |
| 86 | ||
| 87 | 82 | const identity = (request: AuthRequest): Html | "" => |
| 88 | 83 | request.oidcScopes.length === 0 |
| 89 | 84 | ? "" |
| 90 | 85 | : html`<fieldset class="field"> |
| 91 | 86 | <legend>What it will learn about you</legend> |
| 92 | 87 | <ul> |
| 93 | ${request.oidcScopes.map((s) => html`<li>${IDENTITY[s] ?? s}</li>`)} | |
| 88 | ${request.oidcScopes.map((s) => html`<li>${SCOPE_WORDS[s]}</li>`)} | |
| 94 | 89 | </ul> |
| 95 | 90 | </fieldset>`; |
| 96 | 91 | |
| @@ -136,12 +131,12 @@ function consent(ctx: Ctx, request: AuthRequest, values: Params): Html { | ||
| 136 | 131 | <label |
| 137 | 132 | ><input type="radio" name="grant" value="ro" |
| 138 | 133 | ${request.scope === "ro" ? "checked" : ""} /> |
| 139 | Read: see your apps, issues and runs</label | |
| 134 | ${SCOPE_WORDS.ro}</label | |
| 140 | 135 | > |
| 141 | 136 | <label |
| 142 | 137 | ><input type="radio" name="grant" value="rw" |
| 143 | 138 | ${request.scope === "rw" ? "checked" : ""} /> |
| 144 | Read and act: tell the crew, plan, and change things as you</label | |
| 139 | ${SCOPE_WORDS.rw}</label | |
| 145 | 140 | > |
| 146 | 141 | </fieldset> |
| 147 | 142 | ${formField({ |
test/oauth-consent-words.test.ts added +93
| @@ -0,0 +1,93 @@ | ||
| 1 | /** | |
| 2 | * The consent page says who asks, where it returns, and what each scope means; unknown scopes are | |
| 3 | * ignored. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { SCOPE_WORDS } from "../src/core/oauth.ts"; | |
| 11 | import { createSession } from "../src/core/sessions.ts"; | |
| 12 | import { createUser } from "../src/core/users.ts"; | |
| 13 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 14 | ||
| 15 | const REDIRECT = "https://claude.ai/api/mcp/auth_callback"; | |
| 16 | let dir = ""; | |
| 17 | let app: App; | |
| 18 | let servers: Servers; | |
| 19 | let cookie = ""; | |
| 20 | let clientId = ""; | |
| 21 | let hostileId = ""; | |
| 22 | ||
| 23 | const register = async (name: string) => | |
| 24 | ((await (await fetch(`${servers.url}/oauth/register`, { | |
| 25 | method: "POST", | |
| 26 | headers: { "content-type": "application/json" }, | |
| 27 | body: JSON.stringify({ client_name: name, redirect_uris: [REDIRECT] }), | |
| 28 | })).json()) as any).client_id as string; | |
| 29 | ||
| 30 | beforeAll(async () => { | |
| 31 | dir = await mkdtemp(join(tmpdir(), "forge-oauth-words-")); | |
| 32 | app = createApp({ dataDir: dir, port: 0 }); | |
| 33 | servers = await serve(app); | |
| 34 | const made = await createUser(app.db, { | |
| 35 | origin: "seed", trusted: true, username: "alice", email: "[email protected]", | |
| 36 | password: "a-good-passphrase", adminIfFirst: true, | |
| 37 | }); | |
| 38 | if (!made.ok) throw new Error(made.error); | |
| 39 | cookie = `forge_session=${createSession(app.db, made.value.id).token}`; | |
| 40 | clientId = await register("Words Client"); | |
| 41 | hostileId = await register(`<img src=x onerror=alert(1)>`); | |
| 42 | }); | |
| 43 | afterAll(async () => { | |
| 44 | servers.stop(); | |
| 45 | await rm(dir, { recursive: true, force: true }); | |
| 46 | }); | |
| 47 | ||
| 48 | const get = (scope: string, id = clientId) => | |
| 49 | fetch( | |
| 50 | `${servers.url}/oauth/authorize?${new URLSearchParams({ | |
| 51 | response_type: "code", client_id: id, redirect_uri: REDIRECT, | |
| 52 | code_challenge: "c".repeat(43), code_challenge_method: "S256", state: "s", scope, | |
| 53 | })}`, | |
| 54 | { redirect: "manual", headers: { cookie } }, | |
| 55 | ); | |
| 56 | ||
| 57 | const unescape = (s: string) => s.replace(/'|'/g, "'").replace(/&/g, "&"); | |
| 58 | ||
| 59 | test("the page names the client and the redirect host only", async () => { | |
| 60 | const body = await (await get("ro")).text(); | |
| 61 | expect(body).toContain("Connect Words Client"); | |
| 62 | expect(body).toContain("<strong>claude.ai</strong>"); | |
| 63 | expect(body).not.toContain("<strong>claude.ai/api"); | |
| 64 | }); | |
| 65 | ||
| 66 | for (const scope of Object.keys(SCOPE_WORDS)) { | |
| 67 | test(`scope ${scope} is listed with its sentence`, async () => { | |
| 68 | const res = await get(scope === "ro" || scope === "rw" ? scope : `openid ${scope}`); | |
| 69 | expect(res.status).toBe(200); | |
| 70 | const body = unescape(await res.text()); | |
| 71 | const words = SCOPE_WORDS[scope as keyof typeof SCOPE_WORDS]; | |
| 72 | expect(body).toContain(words); | |
| 73 | // each sentence once | |
| 74 | expect(body.split(words).length).toBe(2); | |
| 75 | }); | |
| 76 | } | |
| 77 | ||
| 78 | test("an unknown scope is ignored, never refused, and never granted", async () => { | |
| 79 | for (const scope of ["admin", "ro offline_access", "rw nonsense", "offline_access"]) { | |
| 80 | const res = await get(scope); | |
| 81 | expect(res.status).toBe(200); | |
| 82 | const body = await res.text(); | |
| 83 | expect(body).toContain('name="grant"'); | |
| 84 | } | |
| 85 | const body = await (await get("rw offline_access")).text(); | |
| 86 | expect(body).toMatch(/value="rw"\s+checked/); | |
| 87 | }); | |
| 88 | ||
| 89 | test("a hostile client name is escaped", async () => { | |
| 90 | const body = await (await get("ro", hostileId)).text(); | |
| 91 | expect(body).not.toContain("<img src=x"); | |
| 92 | expect(body).toContain("<img src=x"); | |
| 93 | }); |
new above
offline