A desktop browser with x402 built in: when a page asks for payment, it pays in stablecoins and shows the content.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-browser.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-browser.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-browser.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 site icons (favicons) in tabs, address bar suggestions and the bookmarks panel 7249579 15 hours, 50 minutes ago History
mcp-oauth.ts · 15.1 KB · 322 lines
1/**
2 * Signing in to an MCP server with OAuth, the way a desktop app should: authorization code with PKCE (S256), a
3 * loopback listener for the redirect, and no client secret. Main process only: tokens never reach a page or the chrome UI.
4 *
5 * 1. discover — the server's protected-resource document names its authorization server; that one names the endpoints
6 * 2. register — once per server (dynamic client registration), keeping the client id
7 * 3. authorize — open the person's own browser on the consent page; wait for the redirect on 127.0.0.1
8 * 4. exchange — trade the code for an access token (short-lived) and a refresh token
9 * 5. refresh — quietly, shortly before the access token runs out
10 *
11 * Everything that touches the network goes through an injectable `fetch`, so the whole flow is tested without one.
12 */
13
14import { createHash, randomBytes } from "node:crypto";
15import { createServer, type Server } from "node:http";
16import type { AddressInfo } from "node:net";
17
18export type Fetch = (url: string, init?: { method?: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal }) => Promise<{
19 ok: boolean;
20 status: number;
21 headers: { get(name: string): string | null };
22 text(): Promise<string>;
23}>;
24
25export class OAuthError extends Error {
26 readonly code: "discovery" | "registration" | "denied" | "timeout" | "state" | "token" | "refresh" | "no-port" | "unsafe" | "scope";
27 constructor(code: OAuthError["code"], message: string) {
28 super(message);
29 this.name = "OAuthError";
30 this.code = code;
31 }
32}
33
34/** Ports the redirect listener may use. All are registered up front, because a server matches redirect addresses exactly. */
35export const REDIRECT_PORTS = [53682, 53683, 53684, 53685, 53686];
36export const redirectUri = (port: number) => `http://127.0.0.1:${port}/callback`;
37
38export interface ServerMeta {
39 resource: string;
40 issuer: string;
41 authorizationEndpoint: string;
42 tokenEndpoint: string;
43 registrationEndpoint?: string;
44 revocationEndpoint?: string;
45 scopes: string[];
46}
47
48export interface Tokens {
49 access: string;
50 refresh?: string;
51 /** Epoch milliseconds. */
52 expiresAt: number;
53 scope?: string;
54}
55
56const MAX_DOC = 100_000;
57
58/** https anywhere; plain http only to this machine (a server under test). Nothing else may be asked for a token. */
59export function assertSafeEndpoint(u: string, what: string): URL {
60 let url: URL;
61 try {
62 url = new URL(u);
63 } catch {
64 throw new OAuthError("unsafe", `${what} is not an address`);
65 }
66 const loop = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
67 if (url.username || url.password || !(url.protocol === "https:" || (url.protocol === "http:" && loop))) throw new OAuthError("unsafe", `${what} must be https (or http to this machine): ${url.origin}`);
68 return url;
69}
70
71async function getJson(f: Fetch, url: string, what: string): Promise<Record<string, unknown>> {
72 assertSafeEndpoint(url, what);
73 let res;
74 try {
75 res = await f(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
76 } catch (e) {
77 throw new OAuthError("discovery", `could not reach ${new URL(url).host} for ${what}: ${(e as Error).message}`);
78 }
79 if (!res.ok) throw new OAuthError("discovery", `${what} answered ${res.status}`);
80 const text = await res.text();
81 if (text.length > MAX_DOC) throw new OAuthError("discovery", `${what} is too large`);
82 try {
83 const j = JSON.parse(text) as unknown;
84 if (j && typeof j === "object" && !Array.isArray(j)) return j as Record<string, unknown>;
85 } catch {
86 /* fall through */
87 }
88 throw new OAuthError("discovery", `${what} is not a JSON object`);
89}
90
91const str = (v: unknown): string | undefined => (typeof v === "string" && v ? v : undefined);
92
93/** Find the authorization server of an MCP server, and its endpoints. */
94export async function discover(mcpUrl: string, f: Fetch): Promise<ServerMeta> {
95 const base = assertSafeEndpoint(mcpUrl, "the server address");
96 const path = base.pathname === "/" ? "" : base.pathname;
97 let prm: Record<string, unknown> | null = null;
98 for (const candidate of [`${base.origin}/.well-known/oauth-protected-resource${path}`, `${base.origin}/.well-known/oauth-protected-resource`]) {
99 try {
100 prm = await getJson(f, candidate, "the server's protected-resource document");
101 break;
102 } catch (e) {
103 if (e instanceof OAuthError && e.code === "unsafe") throw e;
104 }
105 }
106 if (!prm) throw new OAuthError("discovery", `${base.host} does not publish how to sign in (no protected-resource document)`);
107 const servers = Array.isArray(prm.authorization_servers) ? prm.authorization_servers.filter((x): x is string => typeof x === "string") : [];
108 const issuer = servers[0] ?? base.origin;
109 const iss = assertSafeEndpoint(issuer, "the authorization server");
110 const ipath = iss.pathname === "/" ? "" : iss.pathname;
111 let as: Record<string, unknown> | null = null;
112 for (const candidate of [`${iss.origin}/.well-known/oauth-authorization-server${ipath}`, `${iss.origin}/.well-known/openid-configuration${ipath}`]) {
113 try {
114 as = await getJson(f, candidate, "the authorization server's document");
115 break;
116 } catch (e) {
117 if (e instanceof OAuthError && e.code === "unsafe") throw e;
118 }
119 }
120 if (!as) throw new OAuthError("discovery", `${iss.host} does not publish its sign-in endpoints`);
121 const authorizationEndpoint = str(as.authorization_endpoint);
122 const tokenEndpoint = str(as.token_endpoint);
123 if (!authorizationEndpoint || !tokenEndpoint) throw new OAuthError("discovery", "the authorization server did not name its endpoints");
124 assertSafeEndpoint(authorizationEndpoint, "the authorization endpoint");
125 assertSafeEndpoint(tokenEndpoint, "the token endpoint");
126 const methods = Array.isArray(as.code_challenge_methods_supported) ? as.code_challenge_methods_supported : null;
127 if (methods && !methods.includes("S256")) throw new OAuthError("discovery", "the server does not support PKCE with S256");
128 const reg = str(as.registration_endpoint);
129 const rev = str(as.revocation_endpoint);
130 if (reg) assertSafeEndpoint(reg, "the registration endpoint");
131 if (rev) assertSafeEndpoint(rev, "the revocation endpoint");
132 const scopes = Array.isArray(prm.scopes_supported) ? prm.scopes_supported.filter((x): x is string => typeof x === "string") : Array.isArray(as.scopes_supported) ? as.scopes_supported.filter((x): x is string => typeof x === "string") : [];
133 return {
134 resource: str(prm.resource) ?? mcpUrl,
135 issuer,
136 authorizationEndpoint,
137 tokenEndpoint,
138 ...(reg ? { registrationEndpoint: reg } : {}),
139 ...(rev ? { revocationEndpoint: rev } : {}),
140 scopes,
141 };
142}
143
144/** Register this app with the server (public client, loopback redirects). Returns the client id. */
145export async function register(meta: ServerMeta, f: Fetch, appName: string): Promise<string> {
146 if (!meta.registrationEndpoint) throw new OAuthError("registration", "this server does not offer registration, so there is no way to sign in without a client id");
147 let res;
148 try {
149 res = await f(meta.registrationEndpoint, {
150 method: "POST",
151 headers: { "content-type": "application/json", accept: "application/json" },
152 body: JSON.stringify({
153 client_name: appName,
154 redirect_uris: REDIRECT_PORTS.map(redirectUri),
155 grant_types: ["authorization_code", "refresh_token"],
156 response_types: ["code"],
157 token_endpoint_auth_method: "none",
158 ...(meta.scopes.length ? { scope: meta.scopes.join(" ") } : {}),
159 }),
160 signal: AbortSignal.timeout(20_000),
161 });
162 } catch (e) {
163 throw new OAuthError("registration", `could not register: ${(e as Error).message}`);
164 }
165 const text = await res.text();
166 if (!res.ok) throw new OAuthError("registration", `registration was refused (${res.status})`);
167 let id: string | undefined;
168 try {
169 id = str((JSON.parse(text) as Record<string, unknown>).client_id);
170 } catch {
171 /* handled below */
172 }
173 if (!id) throw new OAuthError("registration", "registration did not return a client id");
174 return id;
175}
176
177// ---- PKCE ----------------------------------------------------------------------------------------------------------
178
179const b64url = (b: Buffer) => b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
180export function newPkce(): { verifier: string; challenge: string } {
181 const verifier = b64url(randomBytes(48));
182 return { verifier, challenge: b64url(createHash("sha256").update(verifier).digest()) };
183}
184export const newState = () => b64url(randomBytes(24));
185
186export function authorizeUrl(meta: ServerMeta, clientId: string, redirect: string, challenge: string, state: string): string {
187 const u = new URL(meta.authorizationEndpoint);
188 u.searchParams.set("response_type", "code");
189 u.searchParams.set("client_id", clientId);
190 u.searchParams.set("redirect_uri", redirect);
191 u.searchParams.set("code_challenge", challenge);
192 u.searchParams.set("code_challenge_method", "S256");
193 u.searchParams.set("state", state);
194 if (meta.scopes.length) u.searchParams.set("scope", meta.scopes.join(" "));
195 u.searchParams.set("resource", meta.resource);
196 return u.href;
197}
198
199// ---- the redirect listener ---------------------------------------------------------------------------------------
200
201export const DONE_PAGE = (ok: boolean) =>
202 `<!doctype html><meta charset="utf-8"><title>${ok ? "Signed in" : "Not signed in"}</title><body style="font:16px system-ui;padding:48px;max-width:32em;margin:auto"><h2>${ok ? "You are signed in." : "Sign-in did not finish."}</h2><p>${ok ? "You can close this tab and go back to the browser." : "Go back to the browser and try again."}</p>`;
203
204export interface Callback {
205 port: number;
206 redirectUri: string;
207 /** Resolves with the code once the right redirect arrives; rejects on denial, timeout or cancel. */
208 code: Promise<string>;
209 cancel(): void;
210}
211
212/** Listen on 127.0.0.1 only, on the first free registered port. Wrong state or host is ignored, so a stray request cannot end the flow. */
213export async function listenForCode(state: string, opts: { timeoutMs?: number; ports?: number[] } = {}): Promise<Callback> {
214 const ports = opts.ports ?? REDIRECT_PORTS;
215 let server: Server | undefined;
216 let chosen = 0;
217 let resolveCode!: (c: string) => void;
218 let rejectCode!: (e: Error) => void;
219 const code = new Promise<string>((res, rej) => {
220 resolveCode = res;
221 rejectCode = rej;
222 });
223 code.catch(() => {}); // the caller handles it; never an unhandled rejection
224 const stop = () => {
225 clearTimeout(timer);
226 server?.close();
227 server?.closeAllConnections?.();
228 };
229 const timer: NodeJS.Timeout = setTimeout(() => {
230 stop();
231 rejectCode(new OAuthError("timeout", "nobody approved the sign-in in time"));
232 }, opts.timeoutMs ?? 300_000);
233 for (const port of ports) {
234 const s = createServer((req, res) => {
235 const actual = (s.address() as AddressInfo).port;
236 const u = new URL(req.url ?? "/", `http://127.0.0.1:${actual}`);
237 const hostOk = req.headers.host === `127.0.0.1:${actual}` || req.headers.host === `localhost:${actual}`;
238 if (!hostOk || req.method !== "GET" || u.pathname !== "/callback") {
239 res.writeHead(404).end();
240 return;
241 }
242 if (u.searchParams.get("state") !== state) {
243 res.writeHead(400, { "content-type": "text/html" }).end(DONE_PAGE(false));
244 return;
245 }
246 const err = u.searchParams.get("error");
247 const c = u.searchParams.get("code");
248 res.writeHead(err || !c ? 400 : 200, { "content-type": "text/html", "cache-control": "no-store" }).end(DONE_PAGE(!err && !!c));
249 stop();
250 if (err) rejectCode(new OAuthError("denied", err === "access_denied" ? "sign-in was declined" : `the server refused the sign-in (${err.slice(0, 60)})`));
251 else if (c) resolveCode(c);
252 else rejectCode(new OAuthError("denied", "the server sent no code"));
253 });
254 const ok = await new Promise<boolean>((resolve) => {
255 s.once("error", () => resolve(false));
256 s.listen(port, "127.0.0.1", () => resolve(true));
257 });
258 if (ok) {
259 server = s;
260 chosen = (s.address() as AddressInfo).port; // the same as `port`, except for port 0 (any free one), which tests use
261 break;
262 }
263 }
264 if (!server) {
265 clearTimeout(timer);
266 throw new OAuthError("no-port", `none of the ports ${ports[0]}–${ports[ports.length - 1]} is free for the sign-in redirect`);
267 }
268 return { port: chosen, redirectUri: redirectUri(chosen), code, cancel: () => (stop(), rejectCode(new OAuthError("denied", "sign-in was cancelled"))) };
269}
270
271// ---- tokens ------------------------------------------------------------------------------------------------------
272
273async function tokenRequest(meta: ServerMeta, f: Fetch, params: Record<string, string>, code: "token" | "refresh", now: number): Promise<Tokens> {
274 let res;
275 try {
276 res = await f(meta.tokenEndpoint, {
277 method: "POST",
278 headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
279 body: new URLSearchParams(params).toString(),
280 signal: AbortSignal.timeout(20_000),
281 });
282 } catch (e) {
283 throw new OAuthError(code, `could not reach the token endpoint: ${(e as Error).message}`);
284 }
285 const text = await res.text();
286 let j: Record<string, unknown> = {};
287 try {
288 j = JSON.parse(text) as Record<string, unknown>;
289 } catch {
290 /* handled below */
291 }
292 if (!res.ok) throw new OAuthError(code, `the server refused (${res.status}${typeof j.error === "string" ? `: ${j.error.slice(0, 60)}` : ""})`);
293 const access = str(j.access_token);
294 if (!access) throw new OAuthError(code, "the server returned no access token");
295 const expires = typeof j.expires_in === "number" && j.expires_in > 0 ? j.expires_in : 3600;
296 return { access, ...(str(j.refresh_token) ? { refresh: str(j.refresh_token) as string } : {}), expiresAt: now + expires * 1000, ...(str(j.scope) ? { scope: str(j.scope) as string } : {}) };
297}
298
299export const exchangeCode = (meta: ServerMeta, f: Fetch, a: { clientId: string; code: string; verifier: string; redirect: string }, now = Date.now()) =>
300 tokenRequest(meta, f, { grant_type: "authorization_code", code: a.code, redirect_uri: a.redirect, client_id: a.clientId, code_verifier: a.verifier, resource: meta.resource }, "token", now);
301
302/** A refresh may or may not return a new refresh token; when it does not, the old one stays good. */
303export async function refreshTokens(meta: ServerMeta, f: Fetch, a: { clientId: string; refresh: string }, now = Date.now()): Promise<Tokens> {
304 const t = await tokenRequest(meta, f, { grant_type: "refresh_token", refresh_token: a.refresh, client_id: a.clientId, resource: meta.resource }, "refresh", now);
305 return t.refresh ? t : { ...t, refresh: a.refresh };
306}
307
308/** Best effort: tell the server to forget a token. Never throws. */
309export async function revoke(meta: ServerMeta, f: Fetch, clientId: string, token: string): Promise<boolean> {
310 if (!meta.revocationEndpoint) return false;
311 try {
312 const res = await f(meta.revocationEndpoint, {
313 method: "POST",
314 headers: { "content-type": "application/x-www-form-urlencoded" },
315 body: new URLSearchParams({ token, client_id: clientId }).toString(),
316 signal: AbortSignal.timeout(10_000),
317 });
318 return res.ok;
319 } catch {
320 return false;
321 }
322}