@lanes-sh/link 0.1.0

package/src/connectivity/auth/oauth-authcode/broker.ts

@@ -0,0 +1,261 @@
+/**
+ * Talking to a service that holds an OAuth client secret this machine cannot.
+ *
+ * Three requests, one shape each, and no knowledge of whose client is on the
+ * other end — the URL arrives as declared manifest data. Both callers live in
+ * different components (the CLI performs the first exchange, the dispatcher
+ * refreshes while serving), and putting the wire format here is what stops the
+ * two drifting into disagreeing about it.
+ *
+ * Everything here is a plain `fetch` against an operator-declared origin. There
+ * is deliberately no retry: a broker that is down should surface as a refusal
+ * the operator can read, not as a command that hangs.
+ */
+
+/**
+ * Stamped on a credential this broker issued, and read back at refresh.
+ *
+ * The one fact the refresh path cannot derive: which client minted the token it
+ * is holding. Config cannot answer it, because config can change afterwards.
+ */
+export const BROKERED = 'broker';
+
+/** What the broker will authorise, and whether it is currently doing so. */
+export interface BrokerConfig {
+  readonly clientId: string;
+  /** Every scope the client is registered for. Empty means "unstated". */
+  readonly scopesSupported: readonly string[];
+  /** Added to every request so the exchange returns an identity assertion. */
+  readonly identityScopes: readonly string[];
+  readonly open: boolean;
+  /** Why it is closed, or near capacity. The broker's words, printed verbatim. */
+  readonly notice: string | undefined;
+  readonly docsUrl: string | undefined;
+  /** How full the shared client is, when the broker says. Advisory. */
+  readonly capacity: { readonly accounts: number; readonly cap: number } | undefined;
+}
+
+/** A token response, in the vendor's own field names. */
+export interface BrokerTokens {
+  readonly access_token?: string;
+  readonly refresh_token?: string;
+  readonly id_token?: string;
+  readonly expires_in?: number;
+  readonly scope?: string;
+  readonly token_type?: string;
+}
+
+/**
+ * A refusal, carrying what the caller needs to explain it.
+ *
+ * `ownClient` is the broker saying "registering a client of your own is the way
+ * past this". It matters because the two failures look identical otherwise: a
+ * shared client at capacity and a replayed authorization code are both a 4xx,
+ * and only one of them is solved by an hour in a cloud console.
+ */
+export class BrokerError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly notice: string | undefined;
+  readonly ownClient: boolean;
+  readonly docsUrl: string | undefined;
+  readonly retryAfterSeconds: number | undefined;
+
+  constructor(
+    message: string,
+    fields: {
+      status: number;
+      code?: string | undefined;
+      notice?: string | undefined;
+      ownClient?: boolean | undefined;
+      docsUrl?: string | undefined;
+      retryAfterSeconds?: number | undefined;
+    },
+  ) {
+    super(message);
+    this.name = 'BrokerError';
+    this.status = fields.status;
+    this.code = fields.code;
+    this.notice = fields.notice;
+    this.ownClient = fields.ownClient === true;
+    this.docsUrl = fields.docsUrl;
+    this.retryAfterSeconds = fields.retryAfterSeconds;
+  }
+}
+
+type Fetch = typeof globalThis.fetch;
+
+export const BROKER_ORIGIN_ENV = 'LANES_LINK_BROKER_ORIGIN';
+
+/** Loopback, in the spellings a `URL` will hand back for one. */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+/**
+ * Aiming the exchange somewhere other than the origin the manifest declares.
+ *
+ * A broker running on this machine and a staging deployment are the same
+ * problem: everything about the flow is unchanged except which host holds the
+ * secret. An origin is the whole of the difference, so a provider keeps its own
+ * path and only the origin in front of it moves.
+ *
+ * It refuses rather than falls back, because the failure it would otherwise
+ * cause is the expensive kind — believing you are exercising a local broker
+ * while a real authorization code goes to production. A variable that is
+ * ignored when malformed is worse than one that stops the command.
+ *
+ * `http` is confined to loopback for the same reason the redirect is: off this
+ * machine it puts an authorization code on the wire in the clear.
+ */
+export function brokerOriginOverride(
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): string | undefined {
+  const raw = env[BROKER_ORIGIN_ENV]?.trim();
+  if (!raw) return undefined;
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${BROKER_ORIGIN_ENV} is not a URL: ${raw}`);
+  }
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    // `localhost:8080` is the mistake people make, and it *parses* — as a URL
+    // whose scheme is "localhost". Saying which scheme it read is what turns
+    // that from a baffling refusal into an obvious missing `http://`.
+    throw new Error(
+      `${BROKER_ORIGIN_ENV} must be an http or https URL. "${raw}" reads as scheme ` +
+        `"${url.protocol.replace(':', '')}" — a host and port with no scheme becomes one.`,
+    );
+  }
+  if (url.protocol === 'http:' && !LOOPBACK.has(url.hostname)) {
+    throw new Error(
+      `${BROKER_ORIGIN_ENV} may only be http for a loopback host. "${url.hostname}" over http ` +
+        `would put the authorization code on the wire in the clear — use https.`,
+    );
+  }
+  return url.origin;
+}
+
+/** The `{success, data}` envelope, unwrapped, or thrown as a `BrokerError`. */
+async function unwrap(response: Response, what: string): Promise<Record<string, unknown>> {
+  const text = await response.text();
+  let body: Record<string, unknown> = {};
+  try {
+    body = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+  } catch {
+    // A proxy or a captive portal answering in HTML is a real failure mode, and
+    // "Unexpected token <" tells the operator nothing about what went wrong.
+    if (response.ok) {
+      throw new BrokerError(`${what} returned a response that was not JSON.`, {
+        status: response.status,
+      });
+    }
+  }
+
+  if (!response.ok || body['success'] === false) {
+    const retry = Number(response.headers.get('retry-after'));
+    throw new BrokerError(str(body['error']) ?? `${what} failed (${response.status}).`, {
+      status: response.status,
+      code: str(body['code']),
+      notice: str(body['notice']),
+      ownClient: body['own_client'] === true,
+      docsUrl: str(body['docs_url']),
+      retryAfterSeconds: Number.isFinite(retry) && retry > 0 ? retry : undefined,
+    });
+  }
+
+  const data = body['data'];
+  return data !== null && typeof data === 'object' ? (data as Record<string, unknown>) : body;
+}
+
+const str = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.length > 0 ? value : undefined;
+
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+
+async function post(
+  url: string,
+  body: unknown,
+  what: string,
+  fetchImpl: Fetch,
+  headers: Record<string, string> = {},
+): Promise<Record<string, unknown>> {
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+    });
+  } catch (cause) {
+    throw new BrokerError(`${what} could not be reached (${String(cause)}).`, { status: 0 });
+  }
+  return await unwrap(response, what);
+}
+
+export async function brokerConfig(
+  url: string,
+  fetchImpl: Fetch = globalThis.fetch,
+): Promise<BrokerConfig> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${url}/config`, { headers: { accept: 'application/json' } });
+  } catch (cause) {
+    throw new BrokerError(`${url} could not be reached (${String(cause)}).`, { status: 0 });
+  }
+  const data = await unwrap(response, url);
+
+  const clientId = str(data['client_id']);
+  if (!clientId) {
+    throw new BrokerError(`${url} did not return a client id.`, { status: response.status });
+  }
+
+  const capacity = data['capacity'];
+  return {
+    clientId,
+    scopesSupported: strings(data['scopes_supported']),
+    identityScopes: strings(data['identity_scopes']),
+    open: data['status'] !== 'closed',
+    notice: str(data['notice']),
+    docsUrl: str(data['docs_url']),
+    capacity:
+      capacity !== null && typeof capacity === 'object'
+        ? {
+            accounts: Number((capacity as Record<string, unknown>)['accounts']) || 0,
+            cap: Number((capacity as Record<string, unknown>)['cap']) || 0,
+          }
+        : undefined,
+  };
+}
+
+export async function brokerExchange(
+  url: string,
+  input: { code: string; codeVerifier: string; redirectUri: string },
+  fetchImpl: Fetch = globalThis.fetch,
+): Promise<BrokerTokens> {
+  return (await post(
+    `${url}/exchange`,
+    { code: input.code, code_verifier: input.codeVerifier, redirect_uri: input.redirectUri },
+    url,
+    fetchImpl,
+  )) as BrokerTokens;
+}
+
+export async function brokerRefresh(
+  url: string,
+  input: { refreshToken: string; idToken?: string | undefined },
+  fetchImpl: Fetch = globalThis.fetch,
+): Promise<BrokerTokens> {
+  // The assertion goes in a header rather than the body so the broker can
+  // attribute and rate-limit the call before it parses anything, and so it does
+  // not land in whatever logs request bodies.
+  return (await post(
+    `${url}/refresh`,
+    { refresh_token: input.refreshToken },
+    url,
+    fetchImpl,
+    input.idToken ? { authorization: `Bearer ${input.idToken}` } : {},
+  )) as BrokerTokens;
+}

package/src/connectivity/auth/oauth-authcode/index.ts

@@ -0,0 +1,64 @@
+import { auth } from '@modelcontextprotocol/client';
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { CredentialOAuthProvider, upstreamAccessToken } from './provider.ts';
+import { refreshDirectly } from './refresh.ts';
+
+/**
+ * OAuth 2.0 authorization code — the three-legged flow, with a refresh token
+ * held in the secret store.
+ *
+ * The only method here that needs more than a stored string: a browser round
+ * trip at connect time, a refresh on every use, and two different ways to run
+ * that refresh depending on whether the provider has a metadata document.
+ *
+ * The other flows the credential-type list names — JWT bearer, client
+ * credentials — are sibling folders that do not exist yet. See ../README.md.
+ */
+
+export async function resolveUpstreamToken(
+  manifest: ProviderManifest,
+  connectionId: string,
+  credentials: SecretStore,
+): Promise<string | null> {
+  if (manifest.auth.kind !== 'oauth') return null;
+
+  const provider = new CredentialOAuthProvider({
+    manifest,
+    connectionId,
+    credentials,
+    scopes: manifest.auth.scopes,
+  });
+
+  // Where to re-run discovery from, if a refresh needs it. An `http` connector
+  // has no metadata document, so it names its authorization server in the
+  // manifest instead — and the refresh below only ever exchanges a stored
+  // refresh token, which needs the token endpoint and nothing else.
+  const endpoint =
+    manifest.connector.kind === 'mcp' ? manifest.connector.endpoint : manifest.auth.token_url;
+
+  return upstreamAccessToken({
+    connectionKey: `${manifest.id}.${connectionId}`,
+    provider,
+    async refresh(target) {
+      // No browser here on purpose: this path runs while serving requests, and
+      // a refresh that silently opened one would be both useless and alarming.
+      // If re-consent is genuinely needed the provider throws with the command
+      // that fixes it.
+      if (!endpoint) throw new Error(`Provider "${manifest.id}" declares no token endpoint.`);
+
+      // A non-MCP provider refreshes directly. The SDK's `auth()` wants to
+      // rediscover the authorization server first, which a REST API does not
+      // describe — it fails with "prepareTokenRequest() or authorizationCode is
+      // required", which says nothing about the real problem. Exchanging a
+      // stored refresh token needs the token endpoint and the client, and
+      // nothing else.
+      if (manifest.connector.kind !== 'mcp') {
+        return (await refreshDirectly(manifest, target, endpoint, credentials)) as never;
+      }
+
+      await auth(target as never, { serverUrl: endpoint });
+      return (await target.tokens()) as never;
+    },
+  });
+}

package/src/connectivity/auth/oauth-authcode/provider.ts

@@ -0,0 +1,279 @@
+import type { SecretStore } from '#secrets';
+import type { ProviderManifest } from '#connectivity';
+
+/**
+ * The SDK's `OAuthClientProvider`, backed by our `SecretStore`.
+ *
+ * This one class is the whole reason a provider is now a manifest. The SDK
+ * drives discovery, registration, authorization, and refresh; we only say where
+ * the resulting material lives. **DCR and bring-your-own-client differ by a
+ * single method**: whether `clientInformation()` returns something.
+ *
+ *   - returns a stored client  → the SDK uses it            (Google)
+ *   - returns `undefined`      → the SDK registers via DCR  (Notion, Linear)
+ *
+ * Everything persists through the credential store, so registered clients and
+ * refresh tokens are encrypted at rest like any other credential. That matters
+ * for DCR in particular: re-registering orphans the previous grant, so the
+ * client id has to survive restarts.
+ */
+
+/** Loosely typed against the SDK's shapes; the SDK validates them itself. */
+type ClientInformation = Record<string, unknown> & { client_id?: string };
+type Tokens = Record<string, unknown> & { refresh_token?: string; access_token?: string };
+
+export interface OAuthProviderOptions {
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly credentials: SecretStore;
+  /** Loopback callback the CLI is listening on. Absent for non-interactive refresh. */
+  readonly redirectUrl?: string | undefined;
+  /** Opens the browser. Absent when refreshing, where no interaction is possible. */
+  readonly openBrowser?: ((url: URL) => void) | undefined;
+  readonly scopes?: readonly string[];
+  /**
+   * The `state` the CLI's loopback listener will accept. Absent for a
+   * non-interactive refresh, which has no callback leg to bind.
+   */
+  readonly state?: string | undefined;
+}
+
+export class CredentialOAuthProvider {
+  readonly #options: OAuthProviderOptions;
+  #codeVerifier: string | undefined;
+  #discoveryState: unknown;
+
+  constructor(options: OAuthProviderOptions) {
+    this.#options = options;
+  }
+
+  // --- where things live -------------------------------------------------
+
+  /**
+   * The registered client.
+   *
+   * For `manual` registration this is keyed by the shared `oauth_apps` entry,
+   * because every Gmail and Drive connection authorises against the *same*
+   * Google app. For `dynamic` it is keyed per provider, since the registration
+   * belongs to us rather than to an operator-supplied app.
+   */
+  get #clientRef(): string {
+    const auth = this.#options.manifest.auth;
+    if (auth.kind === 'oauth' && auth.registration === 'manual' && auth.app) {
+      return `${auth.app}/client`;
+    }
+    return `${this.#options.manifest.id}/client`;
+  }
+
+  get #tokensRef(): string {
+    return `${this.#options.manifest.id}/${this.#options.connectionId}`;
+  }
+
+  // --- OAuthClientProvider ----------------------------------------------
+
+  get redirectUrl(): string | undefined {
+    return this.#options.redirectUrl;
+  }
+
+  get clientMetadata(): Record<string, unknown> {
+    return {
+      client_name: 'Lanes Link',
+      client_uri: 'https://github.com/lanes-sh/link',
+      redirect_uris: this.#options.redirectUrl ? [this.#options.redirectUrl] : [],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'client_secret_post',
+      ...(this.#options.scopes?.length ? { scope: this.#options.scopes.join(' ') } : {}),
+    };
+  }
+
+  async clientInformation(): Promise<ClientInformation | undefined> {
+    const auth = this.#options.manifest.auth;
+
+    // Manual registration: the operator supplied a client, so hand it over and
+    // the SDK will not attempt to register. Google requires this even for
+    // Google's own MCP servers.
+    if (auth.kind === 'oauth' && auth.registration === 'manual' && auth.app) {
+      const [clientId, clientSecret] = await Promise.all([
+        this.#options.credentials.get(`${auth.app}/client_id`),
+        this.#options.credentials.get(`${auth.app}/client_secret`),
+      ]);
+      if (!clientId) return undefined;
+      return { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) };
+    }
+
+    // Dynamic: a previous registration, if we have one. Returning `undefined`
+    // is what tells the SDK to register — and re-registering orphans the prior
+    // grant, so this must survive restarts.
+    return this.#read(this.#clientRef);
+  }
+
+  async saveClientInformation(information: ClientInformation): Promise<void> {
+    await this.#write(this.#clientRef, information);
+  }
+
+  async tokens(): Promise<Tokens | undefined> {
+    return this.#read(this.#tokensRef);
+  }
+
+  async saveTokens(tokens: Tokens): Promise<void> {
+    // Stamp an absolute expiry alongside the relative `expires_in` the server
+    // returns. Without it there is no way to tell a live access token from a
+    // stale one after a restart, so every cold start would force a refresh —
+    // and a refresh needs the network, which a serve path should not.
+    const lifetime = typeof tokens['expires_in'] === 'number' ? (tokens['expires_in'] as number) : 3600;
+
+    await this.#write(this.#tokensRef, {
+      ...tokens,
+      expires_at: Date.now() + lifetime * 1000,
+    });
+  }
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    if (!this.#options.openBrowser) {
+      throw new Error(
+        `Connection ${this.#options.manifest.id}.${this.#options.connectionId} needs re-authorisation, ` +
+          `which requires a browser. Run: lanes link connect ${this.#options.manifest.id}.${this.#options.connectionId}`,
+      );
+    }
+    this.#options.openBrowser(authorizationUrl);
+  }
+
+  /**
+   * The CSRF binding between the authorization request and the callback.
+   *
+   * The SDK sends a `state` only if we return one here — `state?()` is optional
+   * on its provider interface, and an absent method means the parameter is left
+   * off the authorization URL entirely. The value belongs to the listener in
+   * `captureOAuthCallback`, which is what compares it on the way back; this
+   * method only carries it outbound.
+   *
+   * Undefined during refresh, which has no callback leg. The SDK omits the
+   * parameter, which is correct: there is nothing to bind.
+   */
+  state(): string | undefined {
+    return this.#options.state;
+  }
+
+  /**
+   * SEP-2352: bind the callback leg to the authorization server discovered on
+   * the first leg.
+   *
+   * Held in memory beside the code verifier, and for the same reason — both are
+   * valid for exactly one exchange. Without it the SDK cannot check that the
+   * callback came back from the server it started with, which is an
+   * authorization-server mix-up defence worth having rather than a warning
+   * worth silencing.
+   */
+  saveDiscoveryState(state: unknown): void {
+    this.#discoveryState = state;
+  }
+
+  discoveryState(): unknown {
+    return this.#discoveryState;
+  }
+
+  saveCodeVerifier(codeVerifier: string): void {
+    // In memory only: it is valid for one exchange and is worthless afterwards,
+    // so persisting it would add a stored secret for no benefit.
+    this.#codeVerifier = codeVerifier;
+  }
+
+  codeVerifier(): string {
+    if (!this.#codeVerifier) throw new Error('No PKCE code verifier for this flow');
+    return this.#codeVerifier;
+  }
+
+  async invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void> {
+    if (scope === 'verifier') {
+      this.#codeVerifier = undefined;
+      return;
+    }
+    if (scope === 'discovery') {
+      this.#discoveryState = undefined;
+      return;
+    }
+    if (scope === 'tokens' || scope === 'all') {
+      await this.#options.credentials.delete(this.#tokensRef).catch(() => {});
+    }
+    if (scope === 'client' || scope === 'all') {
+      // Only ever a dynamically registered client. An operator-supplied one is
+      // theirs, and deleting it would silently break every other connection
+      // sharing that oauth_apps entry.
+      const auth = this.#options.manifest.auth;
+      const manual = auth.kind === 'oauth' && auth.registration === 'manual';
+      if (!manual) await this.#options.credentials.delete(this.#clientRef).catch(() => {});
+    }
+  }
+
+  // --- storage helpers ---------------------------------------------------
+
+  async #read<T>(ref: string): Promise<T | undefined> {
+    const raw = await this.#options.credentials.get(ref);
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      // Unparseable stored credential: treat as absent so the flow can recover
+      // by re-registering rather than failing permanently.
+      return undefined;
+    }
+  }
+
+  async #write(ref: string, value: unknown): Promise<void> {
+    await this.#options.credentials.set(ref, JSON.stringify(value));
+  }
+}
+
+/**
+ * Access tokens for upstream calls, cached in memory and never persisted.
+ *
+ * Short-lived by design, so storing one would add a credential to protect for
+ * no benefit. Keyed per connection, so two accounts never share a token, and a
+ * cold instance simply refreshes.
+ */
+const accessTokens = new Map<string, { token: string; expiresAt: number }>();
+
+export function clearUpstreamTokens(): void {
+  accessTokens.clear();
+}
+
+const EXPIRY_MARGIN_MS = 60_000;
+
+export async function upstreamAccessToken(options: {
+  connectionKey: string;
+  provider: CredentialOAuthProvider;
+  refresh: (provider: CredentialOAuthProvider) => Promise<Tokens | undefined>;
+  now?: () => number;
+}): Promise<string | null> {
+  const now = (options.now ?? Date.now)();
+  const cached = accessTokens.get(options.connectionKey);
+  if (cached && cached.expiresAt > now + EXPIRY_MARGIN_MS) return cached.token;
+
+  const stored = await options.provider.tokens();
+  const expiresAt = typeof stored?.['expires_at'] === 'number' ? (stored['expires_at'] as number) : 0;
+
+  if (stored?.access_token && expiresAt > now + EXPIRY_MARGIN_MS) {
+    accessTokens.set(options.connectionKey, { token: stored.access_token, expiresAt });
+    return stored.access_token;
+  }
+
+  // Only refresh when there is something to refresh with. Not every
+  // authorization server issues a refresh token — Notion's does not — and
+  // calling the SDK's `auth()` without one fails in a way that looks like a
+  // configuration bug rather than "this token simply cannot be renewed".
+  // Hand back what we have and let a 401 surface as "re-authorise", which is
+  // the truthful instruction.
+  if (!stored?.refresh_token) return stored?.access_token ?? null;
+
+  const refreshed = await options.refresh(options.provider);
+  if (!refreshed?.access_token) return stored?.access_token ?? null;
+
+  const lifetime = typeof refreshed['expires_in'] === 'number' ? (refreshed['expires_in'] as number) : 3600;
+  accessTokens.set(options.connectionKey, {
+    token: refreshed.access_token,
+    expiresAt: now + lifetime * 1000,
+  });
+
+  return refreshed.access_token;
+}