@lanes-sh/link 0.1.0

package/src/cli/commands/connect/accounts.ts

@@ -0,0 +1,94 @@
+import type { SecretStore } from '#secrets';
+import type { Config, ConnectionConfig } from '#profile';
+import type { ProviderManifest } from '#connectivity';
+
+/**
+ * Which connections belong to the same vendor account, and moving a credential
+ * when a provisional id turns out to be the wrong one.
+ *
+ * All of it is about one problem: a vendor is not a provider. iCloud is three
+ * providers on one Apple Account, so "the connections like this one" cannot be
+ * answered by comparing provider ids.
+ */
+
+/** The credential group a provider belongs to, when it shares one with siblings. */
+export function credentialApp(manifest: ProviderManifest): string | undefined {
+  const auth = manifest.auth;
+  return auth.kind === 'bearer' ||
+    auth.kind === 'api_key' ||
+    auth.kind === 'header' ||
+    auth.kind === 'basic'
+    ? auth.app
+    : undefined;
+}
+
+/**
+ * Connections belonging to the same vendor account as this provider would.
+ *
+ * `icloud_calendar` is a different provider from `icloud_mail` but the same
+ * Apple Account, so its connection id has to match — that is what makes both
+ * derive `icloud/<id>` and share the one app-specific password. Filtering on
+ * provider id alone would miss it and ask for the password three times.
+ */
+export function accountSiblings(
+  manifest: ProviderManifest,
+  config: Config,
+  registry: { manifest(id: string): ProviderManifest | undefined },
+): ConnectionConfig[] {
+  const app = credentialApp(manifest);
+
+  return config.connections.filter((connection) => {
+    if (connection.provider === manifest.id) return true;
+    if (!app) return false;
+    const sibling = registry.manifest(connection.provider);
+    return sibling ? credentialApp(sibling) === app : false;
+  });
+}
+
+/**
+ * The one account a sibling provider already holds, if there is exactly one.
+ *
+ * Adopting its id is what turns the second and third `connect` of a family into
+ * "already stored" rather than a third identical password prompt. With two
+ * accounts in play there is nothing to infer, so it declines rather than
+ * guessing — the operator is asked, or names one with `--id`.
+ */
+export function siblingAccountId(
+  manifest: ProviderManifest,
+  config: Config,
+  registry: { manifest(id: string): ProviderManifest | undefined },
+): string | undefined {
+  if (!credentialApp(manifest)) return undefined;
+
+  // Asked of the registry, not inferred from the id: `app` is a manifest field,
+  // and a provider is free to declare `app: icloud` under any name it likes.
+  const ids = new Set(
+    accountSiblings(manifest, config, registry)
+      .filter((connection) => connection.provider !== manifest.id)
+      .map((connection) => connection.id),
+  );
+
+  return ids.size === 1 ? [...ids][0] : undefined;
+}
+
+/** Whether an existing allow rule already covers the one we were about to add. */
+export function matchesRule(existing: string, wanted: string): boolean {
+  return existing === '*' || existing === wanted;
+}
+
+/**
+ * Move a credential when a provisional id turns out to be the wrong one.
+ *
+ * Copy before delete: a crash between the two leaves the credential readable
+ * under the old name, where `doctor` will flag it, rather than gone.
+ */
+export async function moveCredential(
+  credentials: SecretStore,
+  from: string,
+  to: string,
+): Promise<void> {
+  const value = await credentials.get(from);
+  if (value === null) return;
+  await credentials.set(to, value);
+  await credentials.delete(from);
+}

package/src/cli/commands/connect/authorise.ts

@@ -0,0 +1,298 @@
+import { auth, discoverOAuthProtectedResourceMetadata } from '@modelcontextprotocol/client';
+import { CredentialOAuthProvider } from '#connectivity/auth/index.ts';
+import type { SecretStore } from '#secrets';
+import type { ProviderManifest } from '#connectivity';
+import { ConfigDocument } from '../../config-edit.ts';
+import { captureOAuthCallback, defaultOpenBrowser, runOAuthFlow } from '../../oauth.ts';
+import { ok, progress, style, warn } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { describeScopes, shortScope } from '../../scopes.ts';
+import { BROKERED, BrokerError } from '#connectivity/auth/index.ts';
+import { brokerExchangeVia } from '../../oauth-exchange.ts';
+import { brokeredScopes, hostedClientRefusal, resolveOAuthClient } from './client.ts';
+import { confirmScopes } from './scopes-gate.ts';
+import { ensureOAuthApp } from './setup.ts';
+
+/**
+ * Getting a token, and saying what it will be able to do first.
+ *
+ * Two paths, because two kinds of upstream: an MCP server publishes metadata
+ * worth discovering and the SDK drives it, while a plain REST API announces
+ * nothing and the manifest has to name its endpoints.
+ */
+
+export function oauthProviderFor(
+  manifest: ProviderManifest,
+  connectionId: string,
+  credentials: SecretStore,
+  redirectUrl?: string,
+  openBrowser?: (url: URL) => void,
+  state?: string,
+): CredentialOAuthProvider {
+  return new CredentialOAuthProvider({
+    manifest,
+    connectionId,
+    credentials,
+    scopes: manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [],
+    ...(redirectUrl ? { redirectUrl } : {}),
+    ...(openBrowser ? { openBrowser } : {}),
+    ...(state ? { state } : {}),
+  });
+}
+
+/**
+ * Drive the SDK's OAuth flow over a loopback callback.
+ *
+ * The SDK does discovery, registration, PKCE, and the exchange. We supply
+ * storage and a browser — and, for a manual registration, the client the vendor
+ * insists the operator supplies.
+ */
+export async function authorise(input: {
+  manifest: ProviderManifest;
+  connectionId: string;
+  credentials: SecretStore;
+  document: ConfigDocument;
+  changes: string[];
+  /** No connection of this provider exists yet, so its console setup is undone. */
+  firstForProvider: boolean;
+  /** How the operator spelled the target, so a refusal names a command they typed. */
+  target?: string;
+  profile: string;
+  /** `--own-client`: register a client rather than using the one a broker runs. */
+  ownClient?: boolean;
+  prompter?: Prompter;
+  /** The operator has already said yes to scopes broader than the provider needs. */
+  acceptBroadScopes?: boolean;
+  /** Injected for tests. The broker is the only thing `connect` fetches. */
+  fetch?: typeof globalThis.fetch;
+}): Promise<void> {
+  const { manifest, connectionId, credentials, document, changes } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  const acceptBroadScopes = input.acceptBroadScopes === true;
+  if (manifest.auth.kind !== 'oauth') return;
+
+  // `authoriseDirect` owns the client decision now: a brokered provider has
+  // nothing to prompt for, and asking first would ask for what it does not need.
+  //
+  // A non-MCP connector has nothing to discover auth from: a REST API is a base
+  // URL, and where its authorization server lives is not something it
+  // announces. So the manifest names the endpoints and we run the flow
+  // directly — the same loopback listener, PKCE, and exchange, minus the
+  // discovery the SDK would otherwise do for us.
+  if (manifest.connector.kind !== 'mcp') {
+    await authoriseDirect(input);
+    return;
+  }
+
+  // An MCP provider is always bring-your-own: `defineProvider` refuses a broker
+  // on one, because the SDK owns the exchange and there is no seam to route it.
+  if (manifest.auth.registration === 'manual') {
+    await ensureOAuthApp(input);
+  }
+
+  const serverUrl = manifest.connector.endpoint;
+
+  const callback = captureOAuthCallback({ label: manifest.name });
+
+  try {
+    const provider = oauthProviderFor(
+      manifest,
+      connectionId,
+      credentials,
+      callback.redirectUri,
+      (url) => {
+        progress(style.dim('Opening your browser to authorise…'));
+        progress(style.dim(`If it did not open: ${url.href}`));
+        defaultOpenBrowser(url.href);
+      },
+      callback.state,
+    );
+
+    // Request exactly the scopes the manifest declares, and say what they are.
+    //
+    // Pinning the set matters: left alone the SDK asks for the union of
+    // everything the resource advertises, so a vendor could widen a grant by
+    // editing its own metadata. But pinning is not the same as narrowing —
+    // Google's servers reject a subset of what they advertise, which is why
+    // the Gmail and Drive manifests carry the full set rather than the two
+    // scopes their docs name. Where we cannot reduce the grant we can at least
+    // refuse to make it quietly.
+    if (!(await confirmScopes(manifest, serverUrl, prompter, acceptBroadScopes))) {
+      throw new Error('Cancelled — nothing was authorised.');
+    }
+
+    const scope = manifest.auth.scopes.length > 0 ? manifest.auth.scopes.join(' ') : undefined;
+
+    const first = await auth(provider as never, {
+      serverUrl,
+      ...(scope ? { scope } : {}),
+    });
+
+    if (first === 'AUTHORIZED') {
+      progress(ok('already authorised'));
+      return;
+    }
+
+    const { code, iss } = await callback.wait();
+
+    // `iss` is forwarded for RFC 9207 issuer validation: it is what lets the
+    // SDK detect an authorization-server mix-up before redeeming the code.
+    // Capturing it and dropping it would silently give up that defence.
+    await auth(provider as never, {
+      serverUrl,
+      authorizationCode: code,
+      ...(scope ? { scope } : {}),
+      ...(iss ? { iss } : {}),
+    });
+
+    if (manifest.auth.registration === 'dynamic') {
+      // Worth saying out loud: this is the setup that did not happen.
+      changes.push(`registered with ${new URL(serverUrl).host} automatically`);
+    }
+
+    progress(ok('authorised'));
+  } finally {
+    await callback.close();
+  }
+
+  void document;
+}
+
+/**
+ * OAuth against a plain REST API, where there is nothing to discover.
+ *
+ * `runOAuthFlow` is the M1 path, kept because it turns out to be exactly what a
+ * non-MCP provider needs: give it endpoints, a client, and scopes, and it does
+ * the loopback listener, PKCE, and the exchange. The MCP branch above uses the
+ * SDK instead only because MCP servers publish metadata worth discovering.
+ *
+ * The token blob is written in the same shape `CredentialOAuthProvider` reads,
+ * so refresh, expiry, and staleness reporting all work the same afterwards —
+ * a connection should not behave differently at runtime because of how it was
+ * authorised.
+ */
+async function authoriseDirect(input: {
+  manifest: ProviderManifest;
+  connectionId: string;
+  credentials: SecretStore;
+  document: ConfigDocument;
+  changes: string[];
+  firstForProvider: boolean;
+  target?: string;
+  profile: string;
+  ownClient?: boolean;
+  prompter?: Prompter;
+  acceptBroadScopes?: boolean;
+  fetch?: typeof globalThis.fetch;
+}): Promise<void> {
+  const { manifest, connectionId, credentials } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  if (manifest.auth.kind !== 'oauth') return;
+
+  const { authorize_url: authorizeUrl, token_url: tokenUrl, app } = manifest.auth;
+  if (!authorizeUrl || !tokenUrl) {
+    throw new Error(
+      `Provider "${manifest.id}" uses a ${manifest.connector.kind} connector, which cannot discover ` +
+        'its authorization server. Its manifest must set auth.authorize_url and auth.token_url.',
+    );
+  }
+
+  const client = await resolveOAuthClient({
+    manifest,
+    credentials,
+    document: input.document,
+    changes: input.changes,
+    firstForProvider: input.firstForProvider,
+    ownClient: input.ownClient === true,
+    target: input.target ?? manifest.id,
+    profile: input.profile,
+    ...(input.prompter ? { prompter: input.prompter } : {}),
+    ...(input.fetch ? { fetch: input.fetch } : {}),
+  });
+
+  const scopes =
+    client.kind === 'brokered'
+      ? brokeredScopes(manifest.auth.scopes, client.config).scopes
+      : manifest.auth.scopes;
+
+  if (
+    !(await confirmScopes(
+      manifest,
+      authorizeUrl,
+      prompter,
+      input.acceptBroadScopes === true,
+      scopes,
+    ))
+  ) {
+    throw new Error('Cancelled — nothing was authorised.');
+  }
+
+  let tokens;
+  try {
+    tokens = await runOAuthFlow({
+      authorizeUrl,
+      clientId: client.kind === 'own' ? client.clientId : client.config.clientId,
+      ...(client.kind === 'own'
+        ? { tokenUrl, clientSecret: client.clientSecret }
+        : {
+            exchange: brokerExchangeVia({
+              url: client.url,
+              ...(input.fetch ? { fetch: input.fetch } : {}),
+            }),
+          }),
+      scopes,
+      connectionLabel: manifest.name,
+      ...(manifest.auth.authorize_params
+        ? { authorizeParams: manifest.auth.authorize_params }
+        : {}),
+      onPrompt: (url) => {
+        progress(style.dim('Opening your browser to authorise…'));
+        progress(style.dim(`If it did not open: ${url}`));
+      },
+    });
+  } catch (cause) {
+    // A broker refusal after consent is worth its own sentence: the operator
+    // has already approved the screen, and "nothing was stored" is the fact
+    // they need before they decide whether to try again.
+    if (cause instanceof BrokerError && client.kind === 'brokered') {
+      throw hostedClientRefusal({
+        manifest,
+        target: input.target ?? manifest.id,
+        profile: input.profile,
+        operator: manifest.auth.broker?.operator ?? 'this project',
+        cause: cause.message,
+        ...(cause.notice ? { notice: cause.notice } : {}),
+        ...(cause.docsUrl ? { docsUrl: cause.docsUrl } : {}),
+        afterConsent: true,
+        // A replayed code is not solved by an hour in a console, and the broker
+        // is the one that knows which of its refusals are.
+        ownClient: cause.ownClient,
+      });
+    }
+    throw cause;
+  }
+
+  await credentials.set(
+    `${manifest.id}/${connectionId}`,
+    JSON.stringify({
+      access_token: tokens.accessToken,
+      refresh_token: tokens.refreshToken,
+      token_type: 'Bearer',
+      expires_in: tokens.expiresIn,
+      expires_at: Date.now() + tokens.expiresIn * 1000,
+      scope: tokens.scope,
+      issuer: new URL(authorizeUrl).origin,
+      ...(tokens.idToken ? { id_token: tokens.idToken } : {}),
+      // Which client issued this, stamped once at connect.
+      //
+      // A property of the token, not of the profile: a refresh token minted by
+      // one client is refused by another, so an operator who registers a client
+      // of their own six months from now must not drag existing connections
+      // onto it. Absent means "the profile's own", which every credential
+      // written before this feature already is.
+      ...(client.kind === 'brokered' ? { authorized_via: BROKERED } : {}),
+    }),
+  );
+
+  progress(ok('authorised'));
+}

package/src/cli/commands/connect/client.ts

@@ -0,0 +1,284 @@
+import {
+  BROKER_ORIGIN_ENV,
+  BrokerError,
+  brokerConfig,
+  brokerOriginOverride,
+  type BrokerConfig,
+} from '#connectivity/auth/index.ts';
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { ConfigDocument } from '../../config-edit.ts';
+import { progress, style, warn } from '../../output.ts';
+import type { Prompter } from '../../prompt.ts';
+import { shortScope } from '../../scopes.ts';
+import { declareOwnClient, ensureOAuthApp } from './setup.ts';
+
+/**
+ * Which OAuth client this authorisation uses, and whether it can be used.
+ *
+ * Two arrangements, and the manifest does not pick between them — the profile
+ * does. Declaring an `oauth_apps` entry means "I registered a client, use it";
+ * leaving it out means "use the one the broker operates". So a profile that has
+ * already taken the trouble to register one is never moved off it, and everyone
+ * else gets the path with no console in it.
+ *
+ * Everything here happens *before the browser opens*. A refusal after consent
+ * has been given is a refusal the operator has already paid for, so the
+ * checks that can be made early are made early.
+ */
+
+export type OAuthClient =
+  | { readonly kind: 'own'; readonly clientId: string; readonly clientSecret: string }
+  | { readonly kind: 'brokered'; readonly url: string; readonly config: BrokerConfig };
+
+export interface ClientChoice {
+  readonly manifest: ProviderManifest;
+  readonly credentials: SecretStore;
+  readonly document: ConfigDocument;
+  readonly changes: string[];
+  /** No connection of this provider exists yet, so its console setup is undone. */
+  readonly firstForProvider: boolean;
+  /** `--own-client`: register one rather than using the client the broker runs. */
+  readonly ownClient: boolean;
+  /** How the operator spelled the target, so a refusal names a command they typed. */
+  readonly target: string;
+  readonly profile: string;
+  readonly prompter?: Prompter | undefined;
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}
+
+export async function resolveOAuthClient(input: ClientChoice): Promise<OAuthClient> {
+  const { manifest, credentials, document } = input;
+  if (manifest.auth.kind !== 'oauth') {
+    throw new Error(`Provider "${manifest.id}" does not use OAuth.`);
+  }
+
+  const { app, broker } = manifest.auth;
+
+  if (!broker || (await profileHasOwnClient(app, document, credentials)) || input.ownClient) {
+    if (input.ownClient && broker && !hasClientPrompts(manifest)) {
+      // `defineProvider` permits a broker with no prompts — a provider with no
+      // bring-your-own path is a legal thing to be. This is where that absence
+      // becomes a sentence rather than a prompt for a value nothing collects.
+      throw new Error(
+        `${manifest.name} has no bring-your-own client path: it does not describe what to ` +
+          `register. Drop --own-client to authorise against the client ${broker.operator} operates.`,
+      );
+    }
+    await ensureOAuthApp({
+      manifest,
+      credentials,
+      document,
+      changes: input.changes,
+      firstForProvider: input.firstForProvider,
+      ...(input.prompter ? { prompter: input.prompter } : {}),
+    });
+    if (input.ownClient) declareOwnClient(document, manifest, input.changes);
+
+    const [clientId, clientSecret] = app
+      ? await Promise.all([
+          credentials.get(`${app}/client_id`),
+          credentials.get(`${app}/client_secret`),
+        ])
+      : [null, null];
+
+    if (!clientId || !clientSecret) {
+      throw new Error(
+        `No OAuth client stored for "${app}". Run: lanes link connect ${manifest.id}`,
+      );
+    }
+    return { kind: 'own', clientId, clientSecret };
+  }
+
+  // Before the fetch, so it is said even when the broker cannot be reached.
+  // The danger is not someone who set this deliberately; it is the variable
+  // still exported in a shell three days later, quietly sending a real
+  // authorization code somewhere other than where the operator believes.
+  const overridden = brokerOriginOverride();
+  if (overridden) {
+    progress(
+      warn(
+        `${BROKER_ORIGIN_ENV} is set — the authorization code will be exchanged at ${overridden}, ` +
+          `not by ${broker.operator}.`,
+      ),
+    );
+  }
+
+  let config: BrokerConfig;
+  try {
+    config = await brokerConfig(broker.url, input.fetch ?? globalThis.fetch);
+  } catch (cause) {
+    throw hostedClientRefusal({
+      manifest,
+      target: input.target,
+      profile: input.profile,
+      operator: broker.operator,
+      cause: cause instanceof Error ? cause.message : String(cause),
+      ...(cause instanceof BrokerError && cause.notice ? { notice: cause.notice } : {}),
+      docsUrl: broker.docs_url,
+    });
+  }
+
+  if (!config.open) {
+    throw hostedClientRefusal({
+      manifest,
+      target: input.target,
+      profile: input.profile,
+      operator: broker.operator,
+      cause: 'it is not accepting new connections.',
+      ...(config.notice ? { notice: config.notice } : {}),
+      docsUrl: config.docsUrl ?? broker.docs_url,
+    });
+  }
+
+  const { unsupported } = brokeredScopes(manifest.auth.scopes, config);
+  if (unsupported.length > 0) {
+    throw hostedClientRefusal({
+      manifest,
+      target: input.target,
+      profile: input.profile,
+      operator: broker.operator,
+      cause:
+        `it is not registered for ${unsupported.length === 1 ? 'a scope' : `${unsupported.length} scopes`} ` +
+        `${manifest.name} needs:\n      ${unsupported.map(shortScope).join('\n      ')}`,
+      docsUrl: config.docsUrl ?? broker.docs_url,
+    });
+  }
+
+  if (config.capacity && config.capacity.cap > 0) {
+    const left = config.capacity.cap - config.capacity.accounts;
+    // Advisory, never a refusal. The vendor is the authority on its own cap and
+    // still admits accounts that have already granted once, so refusing here
+    // would lock out exactly the people it would still let through.
+    if (left <= 10) {
+      // `warn` formats; `progress` is what puts it on the stream. Called bare it
+      // builds the sentence and drops it, which is how this one went unsaid.
+      progress(
+        warn(
+          `The ${broker.operator} client is near capacity (${config.capacity.accounts} of ${config.capacity.cap} accounts).`,
+        ),
+      );
+    }
+  }
+
+  progress(
+    style.dim(
+      `Authorising against the OAuth client ${broker.operator} operates — nothing to register.`,
+    ),
+  );
+
+  return { kind: 'brokered', url: broker.url, config };
+}
+
+/**
+ * Whether this profile holds a client of its own.
+ *
+ * The config entry is the declaration, but the store is consulted too: someone
+ * who placed the two values by hand and whose config lost the block keeps their
+ * client rather than being quietly moved onto a different one, where every
+ * existing refresh token would stop working.
+ */
+async function profileHasOwnClient(
+  app: string | undefined,
+  document: ConfigDocument,
+  credentials: SecretStore,
+): Promise<boolean> {
+  if (!app) return false;
+  if (document.getIn(['oauth_apps', app]) !== undefined) return true;
+
+  const [id, secret] = await Promise.all([
+    credentials.get(`${app}/client_id`),
+    credentials.get(`${app}/client_secret`),
+  ]);
+  return Boolean(id && secret);
+}
+
+function hasClientPrompts(manifest: ProviderManifest): boolean {
+  return (manifest.setup?.prompts ?? []).some((prompt) => prompt.scope === 'shared');
+}
+
+/**
+ * What is actually asked for, and what the broker cannot grant.
+ *
+ * The identity scopes are appended rather than assumed: they are what lets the
+ * broker tell one caller's refresh from another's, and the broker says which
+ * ones it wants so it can change them without a new CLI. They are added *only*
+ * on this path — for a client the operator registered there is nobody to
+ * identify to, and asking would cost them a re-consent and two extra lines in
+ * their own console for no benefit at all.
+ */
+export function brokeredScopes(
+  wanted: readonly string[],
+  config: BrokerConfig,
+): { readonly scopes: readonly string[]; readonly unsupported: readonly string[] } {
+  // An empty `scopes_supported` means the broker did not say, not that it
+  // supports nothing. Treating silence as refusal would break every connection
+  // against a broker that simply does not advertise.
+  const unsupported =
+    config.scopesSupported.length > 0
+      ? wanted.filter((scope) => !config.scopesSupported.includes(scope))
+      : [];
+
+  const scopes = [...wanted];
+  for (const scope of config.identityScopes) if (!scopes.includes(scope)) scopes.push(scope);
+
+  return { scopes, unsupported };
+}
+
+/** The refusal that names the way out, with the command already filled in. */
+export function hostedClientRefusal(input: {
+  manifest: ProviderManifest;
+  target: string;
+  profile: string;
+  operator: string;
+  cause: string;
+  notice?: string | undefined;
+  docsUrl?: string | undefined;
+  /** Consent has already been given, so say so before saying nothing was kept. */
+  afterConsent?: boolean | undefined;
+  /**
+   * Whether registering a client of your own is the way past this.
+   *
+   * The broker knows and this does not: a spent capacity and a replayed
+   * authorization code are both a 4xx, and offering an hour in a cloud console
+   * as the fix for the second is worse than offering nothing. Defaults to true
+   * because the refusals raised before the browser opens are all of the first
+   * kind — a broker that is closed, unreachable, or short a scope.
+   */
+  ownClient?: boolean | undefined;
+}): Error {
+  const lines = [
+    `${input.manifest.name} could not be authorised against the OAuth client ${input.operator} operates.`,
+    '',
+  ];
+
+  if (input.afterConsent) {
+    lines.push(
+      '  You approved the consent screen, but the token exchange was refused, so nothing',
+      '  was stored.',
+      '',
+    );
+  }
+
+  // The reason is the broker's to word, so a spent capacity, a suspension and a
+  // maintenance window can read differently without shipping a new CLI.
+  lines.push(`  ${input.notice ?? input.cause}`, '');
+  if (input.notice) lines.push(`  (${input.cause})`, '');
+
+  lines.push('  Nothing was written and no account was connected.');
+
+  if (input.ownClient !== false) {
+    lines.push(
+      '',
+      '  Register your own OAuth client instead:',
+      `    lanes link connect ${input.target} --profile ${input.profile} --own-client`,
+      '',
+      '  That walks through the vendor’s console once and then covers every account on',
+      '  this profile.',
+    );
+  }
+
+  if (input.docsUrl) lines.push(`  ${input.docsUrl}`);
+
+  return new Error(lines.join('\n'));
+}