@lanes-sh/link 0.1.0

package/src/auth/oauth/server.ts

@@ -0,0 +1,385 @@
+import { MCP_SCOPE } from './metadata.ts';
+import {
+  hashToken,
+  randomToken,
+  type AuthorizationCode,
+  type OAuthStore,
+  type RegisteredClient,
+} from './store.ts';
+
+/**
+ * The authorization-code flow, as decisions rather than as HTTP.
+ *
+ * Everything here takes parsed input and returns what should happen; the server
+ * component turns that into a `Response`. That split is what makes the flow
+ * testable as a sequence of values — a wrong PKCE verifier, a replayed code, a
+ * redirect URI that does not match — instead of as a browser session.
+ *
+ * Deliberately small. This implements one grant and one refresh, for public
+ * clients, with PKCE required. It is not a general authorization server and
+ * should not grow into one: no client credentials grant, no implicit flow, no
+ * consent scoping, no user directory. There is exactly one user here, and the
+ * proof of being them is the endpoint token they already have.
+ */
+
+/** Codes live about as long as a redirect takes. */
+const CODE_TTL_MS = 60_000;
+const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+export type OAuthResult =
+  | { readonly kind: 'json'; readonly status: number; readonly body: unknown }
+  | { readonly kind: 'redirect'; readonly location: string }
+  /** Render the approval page. The parameters are carried through it. */
+  | {
+      readonly kind: 'consent';
+      readonly request: AuthorizeRequest;
+      readonly retry: boolean;
+      /**
+       * What the client calls itself, if it said.
+       *
+       * Self-reported and therefore not evidence — registration is open, so
+       * anything may claim any name. It is shown because a name is what makes
+       * the screen legible, and shown *beside the redirect host*, which is the
+       * part that cannot be faked: an impostor calling itself Claude still has
+       * to send the code somewhere, and that somewhere is on the screen.
+       */
+      readonly clientName?: string | undefined;
+    }
+  | { readonly kind: 'error'; readonly status: number; readonly message: string };
+
+export interface AuthorizeRequest {
+  readonly clientId: string;
+  readonly redirectUri: string;
+  readonly codeChallenge: string;
+  readonly state: string | undefined;
+  readonly scope: string;
+  readonly resource: string | undefined;
+}
+
+export interface OAuthServerOptions {
+  readonly store: OAuthStore;
+  /** Proof of being the owner. The same token the endpoint already accepts. */
+  readonly verifyOwner: (presented: string) => Promise<boolean>;
+  readonly accessTokenTtlMs: number;
+  readonly now?: () => number;
+}
+
+export class OAuthServer {
+  readonly #options: OAuthServerOptions;
+  readonly #now: () => number;
+
+  constructor(options: OAuthServerOptions) {
+    this.#options = options;
+    this.#now = options.now ?? Date.now;
+  }
+
+  /**
+   * Dynamic client registration (RFC 7591).
+   *
+   * Open, and that is the design rather than an oversight: registering yields
+   * only an identifier for a client that must still complete an approval this
+   * endpoint's owner performs by hand. The alternative — a pre-registered client
+   * id pasted into a console — is the setup step this whole mode exists to
+   * remove.
+   */
+  async register(body: unknown): Promise<OAuthResult> {
+    const input = body as { redirect_uris?: unknown; client_name?: unknown };
+    const uris = Array.isArray(input?.redirect_uris)
+      ? input.redirect_uris.filter((uri): uri is string => typeof uri === 'string')
+      : [];
+
+    if (uris.length === 0) {
+      return invalid('invalid_redirect_uri', 'redirect_uris must list at least one URI');
+    }
+    for (const uri of uris) {
+      if (!isSafeRedirect(uri)) {
+        return invalid('invalid_redirect_uri', `"${uri}" is not an https or loopback URI`);
+      }
+    }
+
+    const client: RegisteredClient = {
+      clientId: randomToken('llc'),
+      redirectUris: uris,
+      ...(typeof input.client_name === 'string' ? { clientName: input.client_name } : {}),
+      createdAt: this.#now(),
+    };
+    await this.#options.store.registerClient(client);
+
+    return {
+      kind: 'json',
+      status: 201,
+      body: {
+        client_id: client.clientId,
+        redirect_uris: client.redirectUris,
+        token_endpoint_auth_method: 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        ...(client.clientName ? { client_name: client.clientName } : {}),
+      },
+    };
+  }
+
+  /**
+   * The authorization request, before anyone has approved anything.
+   *
+   * Errors here are shown rather than redirected. Redirecting an error to a URI
+   * that failed validation is how an open redirector is built, so a bad
+   * `client_id` or `redirect_uri` ends at this endpoint and goes no further.
+   */
+  async authorize(params: URLSearchParams): Promise<OAuthResult> {
+    if (params.get('response_type') !== 'code') {
+      return { kind: 'error', status: 400, message: 'Only response_type=code is supported.' };
+    }
+    if (params.get('code_challenge_method') !== 'S256') {
+      return {
+        kind: 'error',
+        status: 400,
+        message: 'PKCE is required, with code_challenge_method=S256.',
+      };
+    }
+
+    const clientId = params.get('client_id') ?? '';
+    const client = await this.#options.store.client(clientId);
+    if (!client) {
+      return { kind: 'error', status: 400, message: 'Unknown client. Register first.' };
+    }
+
+    const redirectUri = params.get('redirect_uri') ?? client.redirectUris[0] ?? '';
+    if (!matchesRegistered(redirectUri, client.redirectUris)) {
+      return { kind: 'error', status: 400, message: 'redirect_uri does not match a registered one.' };
+    }
+
+    const challenge = params.get('code_challenge') ?? '';
+    if (!challenge) {
+      return { kind: 'error', status: 400, message: 'code_challenge is required.' };
+    }
+
+    return {
+      kind: 'consent',
+      retry: false,
+      ...(client.clientName ? { clientName: client.clientName } : {}),
+      request: {
+        clientId,
+        redirectUri,
+        codeChallenge: challenge,
+        state: params.get('state') ?? undefined,
+        scope: params.get('scope') || MCP_SCOPE,
+        resource: params.get('resource') ?? undefined,
+      },
+    };
+  }
+
+  /**
+   * The owner approving, by presenting the endpoint token.
+   *
+   * A wrong token re-renders the form rather than redirecting an error back to
+   * the client: the client has no business being told whether the owner typed
+   * their token correctly, and a redirect would end the flow on the first typo.
+   */
+  async approve(request: AuthorizeRequest, presented: string): Promise<OAuthResult> {
+    const registered = await this.#options.store.client(request.clientId);
+
+    if (!presented || !(await this.#options.verifyOwner(presented))) {
+      return {
+        kind: 'consent',
+        request,
+        retry: true,
+        ...(registered?.clientName ? { clientName: registered.clientName } : {}),
+      };
+    }
+
+    const client = registered;
+    if (!client || !matchesRegistered(request.redirectUri, client.redirectUris)) {
+      return { kind: 'error', status: 400, message: 'This approval no longer matches a client.' };
+    }
+
+    const code = randomToken('llx');
+    const record: AuthorizationCode = {
+      clientId: request.clientId,
+      redirectUri: request.redirectUri,
+      codeChallenge: request.codeChallenge,
+      scope: request.scope,
+      ...(request.resource ? { resource: request.resource } : {}),
+      expiresAt: this.#now() + CODE_TTL_MS,
+    };
+    await this.#options.store.putCode(code, record);
+
+    const location = new URL(request.redirectUri);
+    location.searchParams.set('code', code);
+    if (request.state !== undefined) location.searchParams.set('state', request.state);
+    return { kind: 'redirect', location: location.toString() };
+  }
+
+  /** Both grants. Form-encoded in, JSON out, RFC 6749 error codes throughout. */
+  async token(form: URLSearchParams): Promise<OAuthResult> {
+    switch (form.get('grant_type')) {
+      case 'authorization_code':
+        return this.#exchangeCode(form);
+      case 'refresh_token':
+        return this.#refresh(form);
+      default:
+        return invalid('unsupported_grant_type', 'Use authorization_code or refresh_token.');
+    }
+  }
+
+  async #exchangeCode(form: URLSearchParams): Promise<OAuthResult> {
+    const record = await this.#options.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 this.#issue(record.clientId, record.scope, randomToken('llr'));
+  }
+
+  async #refresh(form: URLSearchParams): Promise<OAuthResult> {
+    const presented = form.get('refresh_token') ?? '';
+    const record = await this.#options.store.token(presented);
+
+    if (!record || record.kind === 'access') {
+      return invalid('invalid_grant', 'That refresh token is unknown or expired.');
+    }
+
+    // A spent token presented again is the one signal that it has been copied.
+    // Rotation alone does not answer it: whoever refreshes first walks away
+    // with a live pair, and rejecting only the token in hand leaves that pair
+    // working while the other party — usually the real client — is locked out.
+    // So the whole chain goes. A client retrying a response it never saw and a
+    // thief replaying are indistinguishable from here, and re-authorising is
+    // the cheaper of the two mistakes.
+    if (record.kind === 'consumed') {
+      await this.#options.store.revokeFamily(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 this.#options.store.consumeToken(presented);
+    return this.#issue(record.clientId, record.scope, randomToken('llr'), record.family);
+  }
+
+  async #issue(
+    clientId: string,
+    scope: string,
+    refreshToken: string,
+    family = randomToken('llf'),
+  ): Promise<OAuthResult> {
+    const accessToken = randomToken('lla');
+    const expiresIn = Math.floor(this.#options.accessTokenTtlMs / 1000);
+
+    await this.#options.store.putToken(accessToken, {
+      clientId,
+      kind: 'access',
+      scope,
+      family,
+      expiresAt: this.#now() + this.#options.accessTokenTtlMs,
+    });
+    await this.#options.store.putToken(refreshToken, {
+      clientId,
+      kind: 'refresh',
+      scope,
+      family,
+      expiresAt: this.#now() + REFRESH_TTL_MS,
+    });
+
+    return {
+      kind: 'json',
+      status: 200,
+      body: {
+        access_token: accessToken,
+        token_type: 'Bearer',
+        expires_in: expiresIn,
+        refresh_token: refreshToken,
+        scope,
+      },
+    };
+  }
+}
+
+/** `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');
+}
+
+function invalid(error: string, description: string): OAuthResult {
+  // RFC 6749 codes exactly. A client refreshing on a 401 branches on
+  // `invalid_grant` specifically; anything else and it retries forever or gives
+  // up without re-authorising.
+  return { kind: 'json', status: 400, body: { error, error_description: description } };
+}
+
+/**
+ * https, or loopback for a native client.
+ *
+ * A native client cannot receive an https redirect, so RFC 8252 has it listen
+ * on a loopback port instead. Everything else is refused: a redirect to `http://`
+ * on a routable host puts an authorization code on the wire in clear text.
+ */
+function isSafeRedirect(uri: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return false;
+  }
+
+  if (parsed.protocol === 'https:') return true;
+  return parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname);
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]' || hostname === 'localhost';
+}
+
+/**
+ * Exact match, except for the port of a loopback URI.
+ *
+ * RFC 8252 §7.3 requires ignoring the port for the IP-literal form, because a
+ * native client binds an ephemeral one it cannot know at registration time.
+ * Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback`
+ * and then listens on whatever port it got, so the same allowance has to cover
+ * `localhost` or it never connects.
+ */
+export function matchesRegistered(candidate: string, registered: readonly string[]): boolean {
+  if (registered.includes(candidate)) return true;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return false;
+  }
+  if (!isLoopbackHost(parsed.hostname)) return false;
+
+  return registered.some((uri) => {
+    try {
+      const other = new URL(uri);
+      return (
+        isLoopbackHost(other.hostname) &&
+        other.protocol === parsed.protocol &&
+        other.hostname === parsed.hostname &&
+        other.pathname === parsed.pathname
+      );
+    } catch {
+      return false;
+    }
+  });
+}
+
+export { hashToken };

package/src/auth/oauth/store.ts

@@ -0,0 +1,215 @@
+import type { KeyValueStore } from '#stores/state';
+
+/**
+ * What an authorization server has to remember.
+ *
+ * Three kinds of short-lived record — registered clients, authorization codes,
+ * and issued tokens — over the `KeyValueStore` the database already exposes.
+ * No new table and no migration, because there are none: the state store is a
+ * namespaced key-value store and this is namespaced key-value data.
+ *
+ * It is genuinely runtime state, which is the rule for anything living here.
+ * Deleting a profile's database logs every connector out and they authorise
+ * again; nothing about *what should exist* is lost, because a client
+ * registration is a fact about a past conversation rather than a declaration.
+ *
+ * **Tokens are stored hashed.** A bucket listing, a backup, or anyone who can
+ * read the objects must not thereby hold a working credential — the same reasoning that makes
+ * the profile token a constant-time comparison against a hash rather than a
+ * string sitting in a row. Codes are hashed for the same reason and matter less,
+ * living about a minute.
+ */
+
+const CLIENTS = 'oauth/clients';
+const CODES = 'oauth/codes';
+const TOKENS = 'oauth/tokens';
+
+/** Far above any real number of connectors, and far below a problem. */
+const MAX_CLIENTS = 200;
+
+export interface RegisteredClient {
+  readonly clientId: string;
+  readonly redirectUris: readonly string[];
+  readonly clientName?: string | undefined;
+  readonly createdAt: number;
+}
+
+export interface AuthorizationCode {
+  readonly clientId: string;
+  readonly redirectUri: string;
+  /** The S256 challenge. The verifier never leaves the client. */
+  readonly codeChallenge: string;
+  readonly scope: string;
+  readonly resource?: string | undefined;
+  readonly expiresAt: number;
+}
+
+/**
+ * `consumed` is a spent refresh token kept as a tombstone.
+ *
+ * Deleting one outright is what made replay undetectable: a token that is
+ * simply absent cannot be told apart from one that never existed, so the single
+ * signal that a refresh token has been copied was being discarded at the moment
+ * it arrived. A tombstone keeps the family id and nothing else useful, and it
+ * opens no more than a deleted row does — every check that admits a credential
+ * tests for `access` by name.
+ */
+export type TokenKind = 'access' | 'refresh' | 'consumed';
+
+export interface IssuedToken {
+  readonly clientId: string;
+  readonly kind: TokenKind;
+  readonly scope: string;
+  readonly expiresAt: number;
+  /**
+   * Which refresh chain this belongs to.
+   *
+   * Rotation replaces one refresh token with the next, and a client that
+   * retries a request it never saw the answer to will present the previous one.
+   * Keeping the family lets a replayed token invalidate the whole chain rather
+   * than only itself — the standard response to a stolen refresh token, since
+   * the theft and the retry look identical from here.
+   */
+  readonly family: string;
+}
+
+export function hashToken(value: string): string {
+  return new Bun.CryptoHasher('sha256').update(value, 'utf8').digest('hex');
+}
+
+/** 32 random bytes, base64url. The only place a credential is minted here. */
+export function randomToken(prefix: string): string {
+  return `${prefix}_${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64url')}`;
+}
+
+export class OAuthStore {
+  readonly #state: KeyValueStore;
+  readonly #now: () => number;
+
+  constructor(state: KeyValueStore, now: () => number = Date.now) {
+    this.#state = state;
+    this.#now = now;
+  }
+
+  async registerClient(client: RegisteredClient): Promise<void> {
+    await this.#state.set(CLIENTS, client.clientId, JSON.stringify(client));
+    await this.#pruneClients();
+  }
+
+  /**
+   * Keep the client list bounded.
+   *
+   * Registration is deliberately open — it yields an identifier and nothing
+   * else, and requiring authentication for it would mean the pasted client id
+   * this mode exists to avoid. Open does mean an unauthenticated caller can
+   * write rows, so the list is capped and the oldest go first.
+   *
+   * A client holding a live token is never evicted, whatever its age: that is a
+   * connector someone is using, and dropping it would log them out to make room
+   * for a stranger. The cap is far above any real number of connectors, so in
+   * ordinary use this never fires.
+   */
+  async #pruneClients(): Promise<void> {
+    const keys = await this.#state.keys(CLIENTS);
+    if (keys.length <= MAX_CLIENTS) return;
+
+    const active = new Set<string>();
+    for (const key of await this.#state.keys(TOKENS)) {
+      const token = await this.#read<IssuedToken>(TOKENS, key);
+      if (token) active.add(token.clientId);
+    }
+
+    const evictable: RegisteredClient[] = [];
+    for (const key of keys) {
+      const client = await this.#read<RegisteredClient>(CLIENTS, key);
+      if (client && !active.has(client.clientId)) evictable.push(client);
+    }
+
+    evictable.sort((a, b) => a.createdAt - b.createdAt);
+    for (const client of evictable.slice(0, keys.length - MAX_CLIENTS)) {
+      await this.#state.delete(CLIENTS, client.clientId);
+    }
+  }
+
+  async client(clientId: string): Promise<RegisteredClient | null> {
+    return this.#read<RegisteredClient>(CLIENTS, clientId);
+  }
+
+  async putCode(code: string, record: AuthorizationCode): Promise<void> {
+    await this.#state.set(CODES, hashToken(code), JSON.stringify(record));
+  }
+
+  /**
+   * Read a code and consume it in the same step.
+   *
+   * Single-use is not an optimisation: a code that survives its exchange can be
+   * replayed by anyone who reached the redirect — a browser history entry, a
+   * proxy log, a referrer header — and PKCE only binds it to the client that
+   * started the flow, not to one use.
+   */
+  async takeCode(code: string): Promise<AuthorizationCode | null> {
+    const key = hashToken(code);
+    const record = await this.#read<AuthorizationCode>(CODES, key);
+    await this.#state.delete(CODES, key);
+    return record && record.expiresAt > this.#now() ? record : null;
+  }
+
+  async putToken(token: string, record: IssuedToken): Promise<void> {
+    await this.#state.set(TOKENS, hashToken(token), JSON.stringify(record));
+  }
+
+  async token(token: string): Promise<IssuedToken | null> {
+    const key = hashToken(token);
+    const record = await this.#read<IssuedToken>(TOKENS, key);
+    if (!record) return null;
+
+    if (record.expiresAt <= this.#now()) {
+      // Nothing here expires on a timer — there is no sweeper and a single-user
+      // endpoint does not need one. Expiry is enforced on read, and the row is
+      // dropped when it is noticed so the namespace does not grow forever.
+      await this.#state.delete(TOKENS, key);
+      return null;
+    }
+    return record;
+  }
+
+  async revokeToken(token: string): Promise<void> {
+    await this.#state.delete(TOKENS, hashToken(token));
+  }
+
+  /** Spend a refresh token, keeping the tombstone that makes a replay visible. */
+  async consumeToken(token: string): Promise<void> {
+    const key = hashToken(token);
+    const record = await this.#read<IssuedToken>(TOKENS, key);
+    if (!record) return;
+    await this.#state.set(TOKENS, key, JSON.stringify({ ...record, kind: 'consumed' }));
+  }
+
+  /**
+   * Drop every token in a refresh family.
+   *
+   * Called when a rotated-away refresh token is presented again, which is
+   * either a client retrying or a thief replaying. Both are answered the same
+   * way, because from here they are indistinguishable and the safe reading is
+   * the expensive one.
+   */
+  async revokeFamily(family: string): Promise<void> {
+    for (const key of await this.#state.keys(TOKENS)) {
+      const record = await this.#read<IssuedToken>(TOKENS, key);
+      if (record?.family === family) await this.#state.delete(TOKENS, key);
+    }
+  }
+
+  async #read<T>(namespace: string, key: string): Promise<T | null> {
+    const raw = await this.#state.get(namespace, key);
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      // A row that will not parse is a row nothing can use. Treating it as
+      // absent fails closed; throwing would take the endpoint down over one
+      // corrupt record.
+      return null;
+    }
+  }
+}