@lanes-sh/link 0.7.2 → 0.9.0

package/src/auth/lanes/login.ts

@@ -0,0 +1,294 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { awaitCallback, plainPage, type LandingPage } from './callback.ts';
+import { isFresh, readSession, writeSession, type LanesSession } from './session.ts';
+
+/**
+ * Signing in to Lanes, from a terminal.
+ *
+ * The same flow the desktop app runs, and deliberately not a second one: a
+ * loopback listener on a port the kernel picks, PKCE, Google's consent screen,
+ * and the exchange brokered by the Lanes API so no client holds the client
+ * secret. `core/src/auth/store.ts` is the reference implementation; this is it
+ * without a webview.
+ *
+ * **Nothing about the identity provider is hardcoded here.** The client id, the
+ * Firebase project and its web API key all come from `/v1/auth/google/config`.
+ * That is partly hygiene — this repository is public and a real Google Cloud
+ * project id must never be committed to it — and partly that a client which
+ * discovers its configuration cannot drift from the service that issues it.
+ *
+ * There are two tokens and they are not interchangeable. Google's `id_token`
+ * proves who signed in *to Google*; exchanging it at Firebase produces the Lanes
+ * session, whose `sub` is what a profile's `members:` names (ADR-060). Storing
+ * the first would be storing a token no part of Lanes accepts.
+ */
+
+/** Where the API is, unless told otherwise. */
+export const DEFAULT_API_URL = 'https://api.lanes.sh';
+
+/** The half of `fetch` this module uses. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface LoginOptions {
+  readonly apiUrl?: string | undefined;
+  /**
+   * Injected for tests, and for nothing else.
+   *
+   * Typed as what is called rather than as `typeof fetch`: Bun's carries a
+   * `preconnect` property, and requiring a double to grow one is requiring it
+   * to stop standing for the thing it replaces.
+   */
+  readonly fetch?: FetchLike | undefined;
+  /** Opens the consent screen. Injected so a test never launches a browser. */
+  readonly open?: ((url: string) => Promise<void>) | undefined;
+  /** Called with the URL, so a headless run can be told where to go. */
+  readonly onUrl?: ((url: string) => void) | undefined;
+  /**
+   * Where the session is written. Injected for tests, and only for tests.
+   *
+   * It exists because the alternative was found the hard way: without it, the
+   * test suite signs the developer's own machine in as a fixture. A function
+   * that writes to `$HOME` and takes no way to say otherwise is one every test
+   * of it has to either skip or damage something to run.
+   */
+  readonly home?: string | undefined;
+  /**
+   * How the page the browser lands on is rendered.
+   *
+   * Injected because this component may not reach the CLI's, and the layering is
+   * right rather than merely enforced: signing somebody in has no business
+   * knowing what a page looks like. `lanes auth login` passes the same branded
+   * card a provider connect flow ends on, so the two look like one product.
+   *
+   * The fallback below is deliberately plain and exists for tests and for any
+   * caller that has no opinion. It is not what a person sees.
+   */
+  readonly page?: ((outcome: LandingPage) => Response) | undefined;
+}
+
+interface BrokerConfig {
+  readonly clientId: string;
+  readonly firebaseApiKey: string;
+  readonly firebaseProjectId: string;
+}
+
+/** RFC 7636 S256. The verifier never leaves this process until the exchange. */
+function pkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+async function brokerConfig(
+  apiUrl: string,
+  call: FetchLike,
+): Promise<BrokerConfig> {
+  const response = await call(`${apiUrl}/v1/auth/google/config`);
+  if (!response.ok) {
+    throw new Error(
+      `${apiUrl} would not say how to sign in (${response.status}). ` +
+        'If this is a self-hosted API, set LANES_API_URL to reach it.',
+    );
+  }
+
+  const body = (await response.json()) as { data?: Record<string, unknown> };
+  const data = body.data ?? {};
+
+  const clientId = typeof data['client_id'] === 'string' ? data['client_id'] : '';
+  const firebaseApiKey =
+    typeof data['firebase_api_key'] === 'string' ? data['firebase_api_key'] : '';
+  const firebaseProjectId =
+    typeof data['firebase_project_id'] === 'string' ? data['firebase_project_id'] : '';
+
+  if (!clientId || !firebaseApiKey) {
+    throw new Error(
+      `${apiUrl} is not configured for sign-in. It answered without a client id or a ` +
+        'Firebase key, which means the deployment is missing GOOGLE_OAUTH_CLIENT_ID or ' +
+        'FIREBASE_API_KEY.',
+    );
+  }
+
+  return { clientId, firebaseApiKey, firebaseProjectId };
+}
+
+export async function login(options: LoginOptions = {}): Promise<LanesSession> {
+  const apiUrl = options.apiUrl ?? process.env['LANES_API_URL'] ?? DEFAULT_API_URL;
+  const call = options.fetch ?? globalThis.fetch;
+
+  const config = await brokerConfig(apiUrl, call);
+  const { verifier, challenge } = pkce();
+  const state = randomBytes(16).toString('base64url');
+
+  const { code, redirectUri } = await awaitCallback(
+    state,
+    async (redirectUri) => {
+      const url = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+      url.searchParams.set('client_id', config.clientId);
+      url.searchParams.set('redirect_uri', redirectUri);
+      url.searchParams.set('response_type', 'code');
+      url.searchParams.set('scope', 'email profile openid');
+      url.searchParams.set('code_challenge', challenge);
+      url.searchParams.set('code_challenge_method', 'S256');
+      url.searchParams.set('state', state);
+      // Google issues a refresh token only when asked, and only on a consent
+      // screen it has actually shown. Without both, a second sign-in on the same
+      // machine returns no refresh token and the session lasts an hour.
+      url.searchParams.set('access_type', 'offline');
+      url.searchParams.set('prompt', 'consent');
+
+      options.onUrl?.(url.toString());
+      await options.open?.(url.toString());
+    },
+    options.page ?? plainPage,
+  );
+
+  const google = await exchangeWithBroker(apiUrl, call, {
+    code,
+    codeVerifier: verifier,
+    redirectUri,
+  });
+
+  const session = await firebaseSession(config, call, google.idToken, apiUrl);
+  await writeSession(session, options.home);
+  return session;
+}
+
+async function exchangeWithBroker(
+  apiUrl: string,
+  call: FetchLike,
+  input: { code: string; codeVerifier: string; redirectUri: string },
+): Promise<{ idToken: string }> {
+  const response = await call(`${apiUrl}/v1/auth/google/exchange`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      code: input.code,
+      code_verifier: input.codeVerifier,
+      redirect_uri: input.redirectUri,
+    }),
+  });
+
+  const body = (await response.json().catch(() => ({}))) as {
+    data?: { id_token?: unknown };
+    error?: unknown;
+  };
+
+  if (!response.ok || typeof body.data?.id_token !== 'string') {
+    throw new Error(
+      `The sign-in could not be completed: ${String(body.error ?? response.status)}`,
+    );
+  }
+
+  return { idToken: body.data.id_token };
+}
+
+/**
+ * Google's id token, exchanged for the Lanes one.
+ *
+ * Firebase's `signInWithIdp` over REST, because there is no browser here to run
+ * the web SDK in. The API key is a public identifier rather than a secret —
+ * it is in the web bundle — which is why it can be served to a CLI at all.
+ */
+async function firebaseSession(
+  config: BrokerConfig,
+  call: FetchLike,
+  googleIdToken: string,
+  apiUrl: string,
+): Promise<LanesSession> {
+  const response = await call(
+    `https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${config.firebaseApiKey}`,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        postBody: `id_token=${googleIdToken}&providerId=google.com`,
+        requestUri: 'http://127.0.0.1',
+        returnSecureToken: true,
+        returnIdpCredential: true,
+      }),
+    },
+  );
+
+  const body = (await response.json().catch(() => ({}))) as {
+    localId?: unknown;
+    email?: unknown;
+    idToken?: unknown;
+    refreshToken?: unknown;
+    expiresIn?: unknown;
+    error?: { message?: unknown };
+  };
+
+  if (
+    !response.ok ||
+    typeof body.localId !== 'string' ||
+    typeof body.idToken !== 'string' ||
+    typeof body.refreshToken !== 'string'
+  ) {
+    throw new Error(
+      `Lanes would not accept the Google sign-in: ${String(body.error?.message ?? response.status)}`,
+    );
+  }
+
+  const seconds = Number(body.expiresIn ?? 3600);
+
+  return {
+    // The prefix is what keeps a subject out of `secret-detection.ts`'s
+    // high-entropy rule and says which provider vouched for it — see
+    // `profile/primitives.ts`, where both halves are one decision.
+    subject: `lanes:${body.localId}`,
+    email: typeof body.email === 'string' ? body.email : null,
+    idToken: body.idToken,
+    refreshToken: body.refreshToken,
+    expiresAt: new Date(Date.now() + seconds * 1000).toISOString(),
+    apiUrl,
+  };
+}
+
+/**
+ * A token this machine can present, refreshing it if it has lapsed.
+ *
+ * The refresh is against Google's secure-token endpoint rather than the Lanes
+ * API, which is what the Firebase SDK does in the desktop app and web — the API
+ * verifies tokens and does not mint them.
+ */
+export async function currentIdToken(
+  options: { fetch?: FetchLike; apiUrl?: string; home?: string } = {},
+): Promise<string | null> {
+  const session = await readSession(options.home);
+  if (session === null) return null;
+  if (isFresh(session)) return session.idToken;
+
+  const call = options.fetch ?? globalThis.fetch;
+  const config = await brokerConfig(session.apiUrl, call).catch(() => null);
+  if (config === null) return null;
+
+  const response = await call(
+    `https://securetoken.googleapis.com/v1/token?key=${config.firebaseApiKey}`,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(session.refreshToken)}`,
+    },
+  );
+
+  const body = (await response.json().catch(() => ({}))) as {
+    id_token?: unknown;
+    refresh_token?: unknown;
+    expires_in?: unknown;
+  };
+
+  if (!response.ok || typeof body.id_token !== 'string') return null;
+
+  const refreshed: LanesSession = {
+    ...session,
+    idToken: body.id_token,
+    refreshToken:
+      typeof body.refresh_token === 'string' ? body.refresh_token : session.refreshToken,
+    expiresAt: new Date(Date.now() + Number(body.expires_in ?? 3600) * 1000).toISOString(),
+  };
+
+  await writeSession(refreshed, options.home);
+  return refreshed.idToken;
+}
+
+export type { LandingPage };

package/src/auth/lanes/members.ts

@@ -0,0 +1,103 @@
+import { currentIdToken, type FetchLike } from './login.ts';
+import { readSession } from './session.ts';
+
+/**
+ * The people a Lanes workspace already holds.
+ *
+ * A profile's `members:` is a *selection from* this list, not a second list
+ * beside it. Membership of a workspace is managed on the dashboard — invited,
+ * accepted, given a role, removed — and reproducing any of that here would be a
+ * second place to say who somebody is, which is the failure this whole release
+ * is about on the connection axis.
+ *
+ * So the flow is: somebody is added to the workspace on the dashboard, and they
+ * appear here the moment they accept. Granting them a profile is then a local
+ * edit naming a subject the server already vouches for.
+ *
+ * **A pending invitation is not delegatable, and that is the useful part.** An
+ * invited person has an email and no `user_uid` until they accept, so there is
+ * no subject to write into a profile — and a `members:` entry naming a guess
+ * would look like a working delegation right up until they tried to use it.
+ * They are listed, marked pending, and refused.
+ */
+
+export interface WorkspaceMember {
+  /** `lanes:<uid>`, or null while the invitation is unaccepted. */
+  readonly subject: string | null;
+  readonly email: string | null;
+  readonly role: string;
+  readonly status: 'pending' | 'active';
+  readonly displayName: string | null;
+}
+
+export interface MembersResult {
+  readonly members: readonly WorkspaceMember[];
+  /** Why the list is empty, when it is, so a caller can say something useful. */
+  readonly unavailable: string | null;
+}
+
+/**
+ * Everyone in the Lanes workspace this one is bound to.
+ *
+ * Returns a reason rather than throwing when it cannot answer. Every caller is a
+ * listing or a validation that has something to say either way, and a network
+ * failure while editing a local file should not be fatal — the endpoint checks
+ * the subject at token time regardless.
+ */
+export async function workspaceMembers(
+  lanesWorkspace: string | undefined,
+  options: { fetch?: FetchLike; home?: string } = {},
+): Promise<MembersResult> {
+  if (lanesWorkspace === undefined) {
+    return {
+      members: [],
+      unavailable: 'this workspace is not bound to a Lanes workspace',
+    };
+  }
+
+  const session = await readSession(options.home);
+  if (session === null) return { members: [], unavailable: 'not signed in' };
+
+  const token = await currentIdToken({ ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.home ? { home: options.home } : {}) });
+  if (token === null) return { members: [], unavailable: 'the session could not be refreshed' };
+
+  const call = options.fetch ?? globalThis.fetch;
+
+  const response = await call(`${session.apiUrl}/v1/workspaces/${lanesWorkspace}/members`, {
+    headers: { authorization: `Bearer ${token}` },
+  }).catch(() => null);
+
+  if (response === null) return { members: [], unavailable: `${session.apiUrl} is unreachable` };
+  if (!response.ok) {
+    return { members: [], unavailable: `${session.apiUrl} answered ${response.status}` };
+  }
+
+  const body = (await response.json().catch(() => ({}))) as {
+    data?: {
+      user_uid?: unknown;
+      email?: unknown;
+      role?: unknown;
+      status?: unknown;
+      display_name?: unknown;
+    }[];
+  };
+
+  return {
+    members: (body.data ?? []).map((row) => ({
+      // The subject a profile names is the uid with the prefix `subjectRef`
+      // requires — the same string `lanes auth login` stores, derived the same
+      // way so the two cannot disagree about who somebody is.
+      subject: typeof row.user_uid === 'string' ? `lanes:${row.user_uid}` : null,
+      email: typeof row.email === 'string' ? row.email : null,
+      role: typeof row.role === 'string' ? row.role : 'member',
+      status: row.status === 'active' ? 'active' : 'pending',
+      displayName: typeof row.display_name === 'string' ? row.display_name : null,
+    })),
+    unavailable: null,
+  };
+}
+
+/** How to show somebody whose subject is the only thing known about them. */
+export function describeMember(member: WorkspaceMember): string {
+  return member.displayName ?? member.email ?? member.subject ?? 'unknown';
+}

package/src/auth/lanes/session.ts

@@ -0,0 +1,97 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * The Lanes identity this machine is signed in as.
+ *
+ * Its own store, beside the desktop app's `~/.lanes/auth.json` rather than
+ * inside it: that file holds a uid, an email and a photo URL and no credential,
+ * and merging a refresh token into it would change what an existing file means.
+ * Two files, one of which is `0600`, is the honest arrangement.
+ *
+ * **Not in the workspace.** A workspace is a set of accounts and profiles and
+ * may be a bucket; who is at the keyboard is neither. Putting this in
+ * `~/.lanes-link` would also mean a second workspace signs you out of the
+ * first, and would upload the session to a bucket on the next deploy.
+ */
+
+/** Where the session lives. Overridable for tests, and for nothing else. */
+export function sessionPath(home = homedir()): string {
+  return join(home, '.lanes', 'credentials.json');
+}
+
+export interface LanesSession {
+  /** The Firebase subject, which is what a profile's `members:` names. */
+  readonly subject: string;
+  readonly email: string | null;
+  /** Exchanged for a fresh id token; the long-lived half. */
+  readonly refreshToken: string;
+  /** The current id token, and when it stops being accepted. */
+  readonly idToken: string;
+  readonly expiresAt: string;
+  /** Which API issued it, so a session cannot be replayed against another. */
+  readonly apiUrl: string;
+}
+
+export async function readSession(home?: string): Promise<LanesSession | null> {
+  try {
+    const text = await readFile(sessionPath(home), 'utf8');
+    const parsed = JSON.parse(text) as Partial<LanesSession>;
+
+    // Shape-checked rather than trusted. This file is written by us and read on
+    // every command, so a half-written or hand-edited one should read as "not
+    // signed in" and send somebody to `lanes auth login` — not throw a JSON
+    // error out of a command that was about to list their memory.
+    if (
+      typeof parsed.subject !== 'string' ||
+      typeof parsed.refreshToken !== 'string' ||
+      typeof parsed.idToken !== 'string' ||
+      typeof parsed.expiresAt !== 'string' ||
+      typeof parsed.apiUrl !== 'string'
+    ) {
+      return null;
+    }
+
+    return {
+      subject: parsed.subject,
+      email: typeof parsed.email === 'string' ? parsed.email : null,
+      refreshToken: parsed.refreshToken,
+      idToken: parsed.idToken,
+      expiresAt: parsed.expiresAt,
+      apiUrl: parsed.apiUrl,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeSession(session: LanesSession, home?: string): Promise<void> {
+  const path = sessionPath(home);
+  await mkdir(dirname(path), { recursive: true });
+
+  // `0600` before the content, and again after: the file holds a refresh token,
+  // and a token written world-readable for the instant between two syscalls is
+  // still a token that was world-readable.
+  await writeFile(path, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function clearSession(home?: string): Promise<void> {
+  // Overwritten rather than deleted. An absent file and an empty one both read
+  // as signed out, and writing is the operation that cannot half-succeed on a
+  // store somebody else is reading.
+  await writeFile(sessionPath(home), '{}\n', { mode: 0o600 }).catch(() => {});
+}
+
+/**
+ * Whether the id token is still worth presenting.
+ *
+ * A minute of slack, because the thing being avoided is a request that leaves
+ * here valid and arrives expired. Refreshing slightly early costs one round
+ * trip; refreshing slightly late costs a failed command.
+ */
+export function isFresh(session: LanesSession, now = Date.now()): boolean {
+  const expires = Date.parse(session.expiresAt);
+  return Number.isFinite(expires) && expires - now > 60_000;
+}

package/src/auth/oauth/grant.ts

@@ -0,0 +1,183 @@
+import { grantableScope, MCP_SCOPE } from './metadata.ts';
+import { invalid, type OAuthResult } from './result.ts';
+import { randomToken, type OAuthStore } from './store.ts';
+
+/**
+ * Turning a code, or a refresh token, into an access token.
+ *
+ * Split from the browser leg because the two halves have nothing to say to each
+ * other: this one never sees a person, a redirect or a consent screen, and the
+ * other never mints a token. What passes between them is an `AuthorizationCode`
+ * row, which is the whole interface.
+ *
+ * Free functions over a context rather than methods, so the split is a real one
+ * — this file cannot reach the server's state except through what it is handed.
+ */
+
+const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * How long a spent refresh token still answers.
+ *
+ * A client whose refresh succeeded but whose *response* was lost holds a token
+ * the server has already spent, and retrying with it is the only move it has.
+ * Without a window that retry is `invalid_grant`, and the reference MCP client
+ * rethrows every `OAuthError` but `server_error` rather than recovering — so
+ * the connector dies and its owner is sent to a browser, over a network blip.
+ *
+ * Thirty seconds is the band Auth0's reuse interval (0–60 s) and Okta's grace
+ * period occupy. What it costs: a captured refresh token keeps working for up
+ * to this long after the real client next rotates it.
+ */
+const REFRESH_REUSE_MS = 30_000;
+
+export interface GrantContext {
+  readonly store: OAuthStore;
+  readonly accessTokenTtlMs: number;
+  /** Where a replayed refresh token is recorded. */
+  readonly log?: { warn(message: string, detail?: Record<string, unknown>): void } | undefined;
+  readonly now: () => number;
+}
+
+export async function exchangeCode(
+  form: URLSearchParams,
+  context: GrantContext,
+): Promise<OAuthResult> {
+  const record = await context.store.takeCode(form.get('code') ?? '');
+  if (!record) return invalid('invalid_grant', 'That code is unknown, used, or expired.');
+
+  if (record.clientId !== form.get('client_id')) {
+    return invalid('invalid_grant', 'That code was issued to a different client.');
+  }
+  // Checked even though the code is already bound to it: a client that sends a
+  // different redirect_uri here than it started with is not the client that
+  // started, and the spec requires the comparison.
+  if (record.redirectUri !== form.get('redirect_uri')) {
+    return invalid('invalid_grant', 'redirect_uri does not match the authorization request.');
+  }
+
+  const verifier = form.get('code_verifier') ?? '';
+  if (!verifier || pkceChallengeFor(verifier) !== record.codeChallenge) {
+    return invalid('invalid_grant', 'code_verifier does not match the code_challenge.');
+  }
+
+  return issue(context, record.clientId, record.scope, randomToken('llr'), undefined, who(record));
+}
+
+export async function refresh(
+  form: URLSearchParams,
+  context: GrantContext,
+): Promise<OAuthResult> {
+  const presented = form.get('refresh_token') ?? '';
+  const record = await context.store.token(presented);
+
+  if (!record || record.kind === 'access') {
+    return invalid('invalid_grant', 'That refresh token is unknown or expired.');
+  }
+
+  // A spent token presented again used to take its whole family with it, on
+  // the reading that a replay is a theft. Against a real connector that was
+  // wrong twice over, and ADR-035 has the evidence. Two answers replace it,
+  // and the tombstone's age is what tells them apart.
+  if (record.kind === 'consumed') {
+    // The client first, before the window is even considered. A spent token
+    // presented by a *different* client is not a retry however recent it is,
+    // and accepting one meant a captured refresh token needed only a single
+    // request inside the window to be turned into a fresh 30-day chain member
+    // carrying the original holder's subject and profiles. The retry this
+    // window exists for always comes from the client that spent it.
+    if (record.clientId !== form.get('client_id')) {
+      return invalid('invalid_grant', 'That refresh token was issued to a different client.');
+    }
+
+    // Inside the window it is a retry of a request already answered, and the
+    // client is owed the answer rather than a dead connector. Not re-consumed:
+    // a client retrying twice is still retrying.
+    const spentAt = record.consumedAt;
+    if (spentAt !== undefined && context.now() - spentAt <= REFRESH_REUSE_MS) {
+      return issue(context, record.clientId, record.scope, randomToken('llr'), record.family, who(record));
+    }
+
+    // Outside it, refused on its own — and the family survives, which is the
+    // half that was taking live sessions down with it.
+    context.log?.warn('refresh token replayed', {
+      clientId: record.clientId,
+      family: record.family,
+    });
+    return invalid('invalid_grant', 'That refresh token has already been used.');
+  }
+
+  if (record.clientId !== form.get('client_id')) {
+    return invalid('invalid_grant', 'That refresh token was issued to a different client.');
+  }
+
+  await context.store.consumeToken(presented);
+  return issue(context, record.clientId, record.scope, randomToken('llr'), record.family, who(record));
+}
+
+/**
+ * Mint an access token and the refresh that replaces it.
+ *
+ * `holder` rides along unchanged through every rotation. A refresh is the same
+ * authorization continuing, so re-deciding who it belongs to would mean a
+ * client silently changing identity between two requests — and re-reading
+ * membership here would revoke a live session on a config edit, which is
+ * exactly what ADR-060 says rotation is for instead.
+ */
+async function issue(
+  context: GrantContext,
+  clientId: string,
+  scope: string,
+  refreshToken: string,
+  family = randomToken('llf'),
+  holder: Holder = {},
+): Promise<OAuthResult> {
+  const accessToken = randomToken('lla');
+  const expiresIn = Math.floor(context.accessTokenTtlMs / 1000);
+
+  await context.store.putToken(accessToken, {
+    clientId,
+    kind: 'access',
+    scope: grantableScope(scope) || MCP_SCOPE,
+    family,
+    ...holder,
+    expiresAt: context.now() + context.accessTokenTtlMs,
+  });
+  await context.store.putToken(refreshToken, {
+    clientId,
+    kind: 'refresh',
+    scope: grantableScope(scope) || MCP_SCOPE,
+    family,
+    ...holder,
+    expiresAt: context.now() + REFRESH_TTL_MS,
+  });
+
+  return {
+    kind: 'json',
+    status: 200,
+    body: {
+      access_token: accessToken,
+      token_type: 'Bearer',
+      expires_in: expiresIn,
+      refresh_token: refreshToken,
+      scope,
+    },
+  };
+}
+
+type Holder = { subject?: string | undefined; profiles?: readonly string[] | undefined };
+
+/** The identity half of a stored record, in the shape `issue` spreads. */
+function who(record: Holder): Holder {
+  return {
+    ...(record.subject !== undefined ? { subject: record.subject } : {}),
+    ...(record.profiles !== undefined ? { profiles: record.profiles } : {}),
+  };
+}
+
+/** `base64url(sha256(verifier))`, which is what S256 means. */
+export function pkceChallengeFor(verifier: string): string {
+  return Buffer.from(
+    new Bun.CryptoHasher('sha256').update(verifier, 'utf8').digest(),
+  ).toString('base64url');
+}