@lanes-sh/link 0.1.0

package/src/cli/commands/connect/scopes-gate.ts

@@ -0,0 +1,146 @@
+import { discoverOAuthProtectedResourceMetadata } from '@modelcontextprotocol/client';
+import type { ProviderManifest } from '#connectivity';
+import { progress, style, warn } from '../../output.ts';
+import type { Prompter } from '../../prompt.ts';
+import { describeScopes, shortScope } from '../../scopes.ts';
+
+/**
+ * Saying what a grant will be able to do, while declining still costs nothing.
+ *
+ * Its own file because both halves of `authorise` run it — the SDK path and the
+ * direct one — and because the file it came out of had grown past the budget.
+ * The seam is real: everything here happens before any client is chosen and
+ * before any listener is opened.
+ */
+
+/**
+ * Warn when a manifest's pinned scopes have drifted from the server's.
+ *
+ * Pinning is deliberate — it stops a vendor widening a grant by editing its own
+ * metadata — but a pinned list is a list that can go stale, and both directions
+ * of staleness are worth different words:
+ *
+ * - the server declares a scope we do not request → calls fail, and Google's
+ *   servers say only "The caller does not have permission", which points
+ *   nowhere near the cause. This is the failure that cost an afternoon.
+ * - we request one it no longer declares → probably harmless, possibly a scope
+ *   that has been withdrawn; worth seeing, not worth stopping for.
+ *
+ * Advisory in both directions. Discovery failing must not block a connect that
+ * would otherwise work, so a broken probe is silent.
+ */
+async function reportScopeDrift(pinned: readonly string[], serverUrl: string): Promise<void> {
+  let advertised: readonly string[] = [];
+
+  try {
+    const metadata = await discoverOAuthProtectedResourceMetadata(serverUrl);
+    advertised = (metadata as { scopes_supported?: string[] }).scopes_supported ?? [];
+  } catch {
+    return;
+  }
+
+  if (advertised.length === 0) return;
+
+  const missing = advertised.filter((scope) => !pinned.includes(scope));
+  const extra = pinned.filter((scope) => !advertised.includes(scope));
+
+  if (missing.length > 0) {
+    progress('');
+    progress(
+      style.dim(
+        `${new URL(serverUrl).host} advertises ${missing.length} scope(s) not requested: ` +
+          `${missing.map(shortScope).join(', ')}.`,
+      ),
+    );
+    progress(
+      style.dim(
+        '  Deliberate — an advertised scope is not necessarily a required one, and these are broader than the docs ask for. Worth revisiting only if calls fail on permission.',
+      ),
+    );
+  }
+
+  if (extra.length > 0) {
+    progress('');
+    progress(style.dim(`Note: ${extra.map(shortScope).join(', ')} is no longer declared by the server.`));
+  }
+}
+
+/**
+ * Show what is about to be granted, and stop on the broad ones.
+ *
+ * The consent screen that follows lists the same scopes in the vendor's own
+ * wording, where "Read, compose, send, and permanently delete all your email"
+ * sits in a list of five and reads like boilerplate. This is the same
+ * information a step earlier, in our words, with the account still unconnected
+ * — the last point where declining costs nothing.
+ */
+export async function confirmScopes(
+  manifest: ProviderManifest,
+  serverUrl: string,
+  prompter: Prompter,
+  acceptBroadScopes: boolean,
+  /**
+   * What will actually be asked for, which is not always what the manifest
+   * declares: a brokered flow appends the broker's identity scopes. Showing the
+   * manifest's set instead would put a scope on the vendor's screen that this
+   * gate never mentioned, which is precisely the surprise it exists to prevent.
+   */
+  scopes: readonly string[] = manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [],
+): Promise<boolean> {
+  if (manifest.auth.kind !== 'oauth' || scopes.length === 0) return true;
+
+  await reportScopeDrift(scopes, serverUrl);
+
+  const described = describeScopes(scopes);
+
+  progress('');
+  progress(`${manifest.name} will be granted:`);
+  for (const { scope, meaning, broad } of described) {
+    const name = broad ? style.bold(shortScope(scope)) : shortScope(scope);
+    progress(`  ${broad ? '!' : '·'} ${name}${meaning ? style.dim(`  — ${meaning}`) : ''}`);
+  }
+
+  if (!described.some((entry) => entry.broad)) {
+    progress('');
+    return true;
+  }
+
+  // Why the broad ones cannot simply be dropped — otherwise the obvious next
+  // question is why we ask instead of asking for less.
+  progress('');
+  progress(
+    warn(
+      'The marked scopes are broader than this provider needs. Grant them only if you ' +
+        'mean to — policy can restrict what an agent calls, but it cannot un-grant a token.',
+    ),
+  );
+  progress(
+    style.dim(
+      '  Policy still applies: only capabilities you allow are reachable, and every call is audited.',
+    ),
+  );
+  progress('');
+
+  // Answered ahead of time, by a person, in their own shell. The flag is long
+  // enough that repeating it is a deliberate act, and it lands in the history of
+  // whoever typed it — which is the property that matters, since the point of
+  // this gate is that the decision does not originate with the agent.
+  if (acceptBroadScopes) {
+    progress(style.dim('Broad scopes accepted with --accept-broad-scopes.'));
+    return true;
+  }
+
+  // Fail closed rather than defaulting to no. A non-interactive run cannot
+  // answer, and inventing an answer here would remove the last point at which
+  // declining is free — the vendor's own consent screen is next, where the same
+  // sentence sits in a list of five and reads like boilerplate.
+  if (!prompter.interactive) {
+    throw new Error(
+      `${manifest.name} asks for scopes broader than it needs, and this run is non-interactive.\n` +
+        `  Nothing was authorised. Re-run in a terminal, or add --accept-broad-scopes if you mean to grant them.`,
+    );
+  }
+
+  return prompter.confirm('Authorise with these scopes?', false);
+}
+

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

@@ -0,0 +1,136 @@
+import { createMcpConnector } from '#connectivity/transports';
+import type { SecretStore } from '#secrets';
+import type { Config } from '#profile';
+import type { AnyConnector, ProviderManifest } from '#connectivity';
+import { idFromAccount, resolveAccount } from '../../identity.ts';
+import { style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { accountSiblings } from './accounts.ts';
+import { oauthProviderFor } from './authorise.ts';
+
+/**
+ * Settle which connection this is, and whose account it belongs to.
+ *
+ * The order matters. An explicit `--id` wins, because someone who named it
+ * meant it. Otherwise the provider is asked who authorised — and if an existing
+ * connection already holds that account, we reuse *its* id, which is what turns
+ * a re-run of `connect` into a repair rather than a duplicate. Only when
+ * identity cannot be resolved at all do we ask.
+ */
+export async function settleIdentity(input: {
+  manifest: ProviderManifest;
+  provisionalId: string;
+  explicitId: string | undefined;
+  account: string | undefined;
+  runtime: {
+    config: Config;
+    credentials: SecretStore;
+    registry: { manifest(id: string): ProviderManifest | undefined };
+    connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+  };
+  prompter?: Prompter;
+}): Promise<{ connectionId: string; account: string }> {
+  const { manifest, provisionalId, explicitId, runtime } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+
+  // Siblings across the whole vendor account, not just this provider — so
+  // connecting iCloud Calendar after iCloud Mail lands on the same id, and
+  // therefore the same credential, rather than a second `will2`.
+  const siblings = accountSiblings(manifest, runtime.config, runtime.registry);
+
+  let account = input.account ?? null;
+
+  // A connector-resolved identity is also the credential check — it is the name
+  // the server *accepted* — so it is called outside `resolveAccount`, whose
+  // catch-all would turn a rejected password into a polite "which account is
+  // this?" and hand you a connection that cannot work.
+  if (!account && manifest.identity?.kind === 'connector') {
+    account = (await runtime.connectorFor(manifest.id, provisionalId)?.identify?.()) ?? null;
+  }
+
+  if (!account) {
+    account = await resolveAccount(manifest, {
+      accessToken: async () => {
+        const provider = oauthProviderFor(manifest, provisionalId, runtime.credentials);
+        const tokens = (await provider.tokens()) as { access_token?: string } | undefined;
+        return tokens?.access_token ?? null;
+      },
+      // A protocol that authenticates by username has nothing to GET and no
+      // tool to call — it knows, once the server has accepted the login.
+      identify: async () =>
+        (await runtime.connectorFor(manifest.id, provisionalId)?.identify?.()) ?? null,
+      ...(manifest.connector.kind === 'mcp'
+        ? {
+            callTool: async (name: string, args: Record<string, unknown>) => {
+              const connector = createMcpConnector({
+                endpoint: (manifest.connector as { endpoint: string }).endpoint,
+                accessToken: async () => {
+                  const provider = oauthProviderFor(manifest, provisionalId, runtime.credentials);
+                  const tokens = (await provider.tokens()) as { access_token?: string } | undefined;
+                  return tokens?.access_token ?? null;
+                },
+              });
+              return connector.invoke({ name, inputSchema: {}, description: '' } as never, args, {
+                manifest,
+                provider: undefined as never,
+                authorize: async (request) => request,
+              });
+            },
+          }
+        : {}),
+    });
+  }
+
+  // A provider that authenticates to nothing has no account to name, so asking
+  // is a question with no answer — and one that needs a terminal, which makes an
+  // otherwise scriptable connect interactive for no reason.
+  //
+  // The *label* is the provider's name; the *id* is `main`, like every other
+  // first connection. Deriving the id from the label gave `memory.memory`,
+  // `skills.skills`, `vault.vault` — and, on disk, a memory entry at
+  // `memory/memory/…`. `memory.main` reads the way `gmail.main` does.
+  const unaccounted = !account && manifest.auth.kind === 'none';
+  if (unaccounted) account = manifest.name;
+
+  if (!account) {
+    // Nothing to go on. Asking beats inventing `main2`, and the answer is the
+    // one piece of information the file cannot reconstruct later — which is
+    // also why a non-interactive run refuses rather than making one up. An
+    // invented label is the row an operator reads in `status` forever.
+    if (!prompter.interactive) {
+      throw new Error(
+        `${manifest.name} could not report whose account this is, and this run is non-interactive.\n` +
+          `  Nothing was written. Pass --display-name "<label>" to name it yourself.`,
+      );
+    }
+
+    account =
+      (await prompter.ask(`Which account is this? ${style.dim('(label for this connection)')}`)) ||
+      `${manifest.name} ${provisionalId}`;
+  }
+
+  if (explicitId) return { connectionId: explicitId, account };
+
+  if (unaccounted) {
+    return {
+      connectionId: idFromAccount(
+        'main',
+        siblings.map((candidate) => candidate.id),
+      ),
+      account: account!,
+    };
+  }
+
+  const already = siblings.find(
+    (candidate) => candidate.account.toLowerCase() === account.toLowerCase(),
+  );
+  if (already) return { connectionId: already.id, account };
+
+  return {
+    connectionId: idFromAccount(
+      account,
+      siblings.map((candidate) => candidate.id),
+    ),
+    account,
+  };
+}

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

@@ -0,0 +1,276 @@
+import type { SecretStore } from '#secrets';
+import type { ProviderManifest, SetupPrompt } from '#connectivity';
+import { credentialRefForConnection } from '#connectivity';
+import { ConfigDocument } from '../../config-edit.ts';
+import { ok, progress, style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+
+/**
+ * The console work a provider needs done, and the values it needs handed over.
+ *
+ * The only part of `connect` that talks to the operator about a vendor's own
+ * setup — which is why the prompts live here and nowhere else.
+ */
+
+/**
+ * Print a provider's setup block, asking for nothing.
+ *
+ * Separate from `askForSetup` because the instructions and the prompt have
+ * different audiences. The prompt is needed once per profile — the OAuth client
+ * is shared, so a second Google provider has nothing to be asked for. The
+ * *instructions* are per product: each one names APIs to enable and scopes to
+ * add under DATA ACCESS, and those are console work nobody has done yet.
+ *
+ * Bundled together, the second provider silently got neither. Connecting
+ * `sheets` on a profile that already had Gmail skipped straight to the browser,
+ * and the two ways that fails are the two this repository keeps warning about —
+ * an unregistered scope is refused at consent, and a disabled API consents
+ * cleanly and then 403s on every call.
+ */
+export function printSetup(manifest: ProviderManifest, note: string): void {
+  const setup = manifest.setup;
+  if (!setup) return;
+
+  progress();
+  progress(style.bold(`Setting up ${manifest.name}`));
+  if (setup.summary) progress(setup.summary);
+  if (setup.docs_url) progress(style.dim(setup.docs_url));
+  progress();
+  setup.steps.forEach((step, index) => progress(`  ${index + 1}. ${step}`));
+  progress();
+  progress(style.dim(note));
+  progress();
+}
+
+/**
+ * Render a provider's setup block, then ask for what it declares.
+ *
+ * Shared by the OAuth-client path and the static-credential path, because they
+ * are the same conversation: show the operator where to generate something, then
+ * take it and put it in the store. The only difference is where it lands, which
+ * the caller decides.
+ */
+export async function askForSetup(
+  manifest: ProviderManifest,
+  prompts: readonly SetupPrompt[],
+  note: string,
+  prompter: Prompter = terminalPrompter,
+): Promise<Map<string, string>> {
+  const setup = manifest.setup;
+  if (!setup) {
+    throw new Error(
+      `Provider "${manifest.id}" needs a credential but declares no setup, so there is no way to learn what to ask you for. Add a setup block to its manifest.`,
+    );
+  }
+
+  printSetup(manifest, note);
+
+  const answers = new Map<string, string>();
+  for (const prompt of prompts) {
+    const value = prompt.secret
+      ? await prompter.askSecret(`  ${prompt.label}`)
+      : await prompter.ask(`  ${prompt.label}`);
+    if (!value) throw new Error(`${prompt.label} is required.`);
+    answers.set(prompt.key, value);
+  }
+
+  return answers;
+}
+
+/**
+ * Whether the credential already in the store may stand, or has to be asked for
+ * again.
+ *
+ * Extracted because the two reasons to ask again are easy to state and were
+ * impossible to test: `ensureStaticCredential` reaches a terminal, and the
+ * property worth holding — that a re-run of `connect` can always correct a
+ * credential — is a property of this decision rather than of the prompting.
+ *
+ * `provisional` is the one that made `connect` unrecoverable. A credential
+ * under the provisional connection id exists only because an earlier `connect`
+ * stored one and then failed before settling whose account it was, so no server
+ * has ever accepted it — and treating it as established meant a mistyped
+ * app-specific password could not be corrected by any spelling of the command
+ * that stored it.
+ */
+export function reuseStoredCredential(input: {
+  readonly stored: boolean;
+  readonly replace: boolean;
+  readonly provisional: boolean;
+}): boolean {
+  return input.stored && !input.replace && !input.provisional;
+}
+
+/**
+ * Ask for a static credential — an API key, or an app-specific password.
+ *
+ * This did not exist, which meant the custom-provider path `docs/detailed/creating-a-provider.md`
+ * documents did not work: a manifest declaring `auth: {kind: header}` connected
+ * with no complaint, never asked for the key, and then reported itself
+ * unauthorized forever — with `doctor` advising the very command that had just
+ * declined to help.
+ *
+ * Idempotent where that is load-bearing rather than tidy: iCloud is three
+ * providers sharing one app-specific password, so the second and third
+ * `connect` must find it already there and say nothing. `reuseStoredCredential`
+ * holds the exceptions.
+ *
+ * Asking is not discarding. The stored value is read but never deleted here,
+ * and the write below happens only once every prompt has been answered — so
+ * Ctrl-C, or an empty answer, leaves a working credential exactly as it was.
+ * A command that threw away a secret the operator typed and then failed before
+ * replacing it would be worse than the trap it was fixing.
+ */
+export async function ensureStaticCredential(input: {
+  manifest: ProviderManifest;
+  connectionId: string;
+  credentials: SecretStore;
+  /** The operator asked for this one again — `--replace`, or naming the connection. */
+  replace: boolean;
+  /** The connection id is still the placeholder, so nothing has accepted this credential. */
+  provisional: boolean;
+  prompter?: Prompter;
+}): Promise<void> {
+  const { manifest, connectionId, credentials, replace, provisional } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  const auth = manifest.auth;
+  if (auth.kind === 'none' || auth.kind === 'oauth' || auth.kind === 'strategy') return;
+
+  const ref = credentialRefForConnection(manifest, connectionId)!;
+  const stored = await credentials.has(ref);
+
+  if (reuseStoredCredential({ stored, replace, provisional })) {
+    progress(ok(`credential already stored (${ref})`));
+    return;
+  }
+
+  // Asked for where "already stored" was expected, so say which of the two
+  // reasons it is. Only when something is actually there: on a first connect
+  // this line would describe a state that does not exist.
+  if (stored) {
+    progress(
+      style.dim(
+        provisional && !replace
+          ? `An earlier connect left a credential at ${ref} without finishing, so it was never accepted. ` +
+              'Asking again — what is stored is replaced only once you have entered a new one.'
+          : `Replacing ${ref} — what is stored is overwritten only once you have entered a new one.`,
+      ),
+    );
+  }
+
+  const prompts = (manifest.setup?.prompts ?? []).filter((p) => p.scope === 'connection');
+  if (prompts.length === 0) {
+    throw new Error(
+      `Provider "${manifest.id}" authenticates with a stored credential but declares no per-account setup prompts, ` +
+        `so there is nothing to ask you for. Either add prompts with "scope: connection", or place the value at ${ref} yourself.`,
+    );
+  }
+
+  const answers = await askForSetup(
+    manifest,
+    prompts,
+    `Stored at ${ref}, in the credential store — never in config.`,
+    prompter,
+  );
+
+  if (auth.kind === 'basic') {
+    // RFC 7617's own encoding. Stored as the header carries it, so nothing
+    // downstream has to agree about a JSON shape.
+    const username = answers.get(prompts.find((p) => p.field === 'username')!.key)!;
+    const password = answers.get(prompts.find((p) => p.field === 'password')!.key)!;
+    await credentials.set(ref, `${username}:${password}`);
+  } else {
+    await credentials.set(ref, answers.get(prompts[0]!.key)!);
+  }
+
+  progress(ok('credential stored'));
+}
+
+/** Prompt once per profile for a vendor-supplied client, and record only refs. */
+export async function ensureOAuthApp(input: {
+  manifest: ProviderManifest;
+  credentials: SecretStore;
+  document: ConfigDocument;
+  changes: string[];
+  firstForProvider: boolean;
+  prompter?: Prompter;
+}): Promise<void> {
+  const { manifest, credentials, document, changes } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  if (manifest.auth.kind !== 'oauth' || !manifest.auth.app) return;
+
+  const app = manifest.auth.app;
+  const [existingId, existingSecret] = await Promise.all([
+    credentials.get(`${app}/client_id`),
+    credentials.get(`${app}/client_secret`),
+  ]);
+
+  if (existingId && existingSecret) {
+    // The client is stored, so there is nothing to ask for — but if this is the
+    // profile's first connection *of this provider*, its console setup has not
+    // been done. Show it, once. Gated on the provider being new rather than on
+    // the client being present, because refresh tokens on an unpublished Google
+    // app expire weekly and reprinting this on every re-authorisation would
+    // train someone to scroll past it.
+    if (input.firstForProvider) {
+      printSetup(
+        manifest,
+        `The ${app} OAuth client is already set up, so nothing is asked for here — but the ` +
+          'APIs and scopes above are per product, and this is the first connection of this one.',
+      );
+    }
+    declareOwnClient(document, manifest, changes);
+    return;
+  }
+
+  const setup = manifest.setup;
+  if (!setup) throw new Error(`Provider "${manifest.id}" needs a client but declares no setup.`);
+
+  const shared = setup.prompts.filter((p) => p.scope === 'shared');
+  const answers = await askForSetup(
+    manifest,
+    shared,
+    'Asked once per profile. Values go to the credential store, never to config.',
+    prompter,
+  );
+
+  for (const prompt of shared) {
+    await credentials.set(prompt.credential_ref!, answers.get(prompt.key)!);
+  }
+
+  declareOwnClient(document, manifest, changes);
+}
+
+/**
+ * Record that this profile uses a client of its own.
+ *
+ * The entry is not merely a pair of pointers — it is the switch. A provider
+ * that can also authorise against a broker reads its presence as "this profile
+ * registered a client, use it", so writing it is what makes `--own-client`
+ * stick without a second flag to remember. Which is also why it is called on
+ * both of `ensureOAuthApp`'s exits: someone whose credentials were already in
+ * the store but whose config lost the block would otherwise be moved onto the
+ * hosted client at the next connect.
+ */
+export function declareOwnClient(
+  document: ConfigDocument,
+  manifest: ProviderManifest,
+  changes: string[],
+): void {
+  if (manifest.auth.kind !== 'oauth' || !manifest.auth.app) return;
+  const app = manifest.auth.app;
+
+  const shared = (manifest.setup?.prompts ?? []).filter((p) => p.scope === 'shared');
+  const idPrompt = shared.find((p) => p.key === 'client_id');
+  const secretPrompt = shared.find((p) => p.key === 'client_secret');
+
+  if (idPrompt && secretPrompt && document.getIn(['oauth_apps', app]) === undefined) {
+    document.setIn(['oauth_apps', app], {
+      client_id_ref: idPrompt.credential_ref,
+      client_secret_ref: secretPrompt.credential_ref,
+    });
+    // No back-pointer from the provider: the manifest already says which app it
+    // uses, and a second copy in config could only ever disagree with it.
+    changes.push(`oauth_apps.${app} declared`);
+  }
+}