@lanes-sh/link 0.2.2 → 0.3.0

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

@@ -0,0 +1,237 @@
+import { hasOwnClientPath, type AuthAssertion, type ProviderManifest } from '#connectivity';
+import { progress, style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+
+/**
+ * Which way in, where a provider offers more than one.
+ *
+ * Two questions that used to be asked in two different places and are one
+ * question to the person answering: what kind of credential, and — for the
+ * browser — whose OAuth client. The second was a flag, `--own-client`, which is
+ * to say it was a choice nobody discovered unless they already knew it existed.
+ *
+ * Most providers offer exactly one route and this file is inert for them:
+ * `options` returns a single entry, nothing is printed, and nothing is asked.
+ * That is the property worth protecting — adding routes to Google must not put
+ * a question, or a warning, in front of somebody connecting GitHub.
+ */
+
+export type ChosenMethod =
+  | {
+      readonly kind: 'assertion';
+      /** How `--auth` spells this route, for reporting what the connection became. */
+      readonly id: string;
+      readonly assertion: AuthAssertion;
+    }
+  /**
+   * The browser, and which client the exchange runs through.
+   *
+   * `undefined` means "whatever this profile already decided", which is the
+   * precedence `resolveOAuthClient` has always applied: a declared `oauth_apps`
+   * entry wins, otherwise the broker. It is what a provider with only one
+   * browser route resolves to, so nothing about those changes.
+   *
+   * `id` is unset for exactly those synthesised cases — `--auth oauth`,
+   * `--own-client`, and a provider with one route — because there was no choice
+   * to report. A provider that never offered two reads as it always did.
+   */
+  | { readonly kind: 'oauth'; readonly id?: string; readonly client: 'own' | 'hosted' | undefined }
+  /**
+   * A credential the operator already holds, for a provider that does OAuth.
+   *
+   * Offered where an OAuth manifest still declares a per-connection prompt,
+   * which is a thing to be only where the browser route can be closed by
+   * somebody who is not in the room: a Slack workspace on Enterprise Grid needs
+   * an admin to approve an app before it can authenticate anyone, and the
+   * person running `connect` may not be that admin.
+   */
+  | { readonly kind: 'pasted'; readonly id?: string };
+
+interface Option {
+  /** What `--auth` accepts, and how a chosen route is named back. */
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly chosen: ChosenMethod;
+}
+
+
+/**
+ * Every route this provider actually has, in the order they are offered.
+ *
+ * The key first, because it is the one that removes a recurring chore and the
+ * one nobody would guess at. Then the hosted client, which is the default and
+ * the thing "as it works today" means. Then a client of your own, which is
+ * twenty minutes in a console and is what an organisation forbidding
+ * third-party clients needs.
+ */
+export function options(manifest: ProviderManifest): readonly Option[] {
+  if (manifest.auth.kind !== 'oauth') return [];
+
+  const { assertion, broker } = manifest.auth;
+  const found: Option[] = [];
+
+  if (assertion) {
+    found.push({
+      id: assertion.method,
+      label: assertion.label,
+      detail: assertion.reach,
+      chosen: { kind: 'assertion', id: assertion.method, assertion },
+    });
+  }
+
+  if (broker) {
+    found.push({
+      id: 'hosted_client',
+      label: `Sign in through a browser, using the OAuth client ${broker.operator} operates`,
+      detail:
+        'nothing to register and no client secret on this machine. The exchange is performed by ' +
+        `${broker.operator}, and the connection is re-authorised whenever its token expires.`,
+      chosen: { kind: 'oauth', id: 'hosted_client', client: 'hosted' },
+    });
+  }
+
+  if (!broker || hasOwnClientPath(manifest)) {
+    found.push({
+      id: 'own_client',
+      label: 'Sign in through a browser, using an OAuth client you register',
+      detail: broker
+        ? 'a console walkthrough once per profile, after which nothing leaves this machine but ' +
+          'the browser. What an organisation that forbids third-party clients needs.'
+        : 'the whole account, and the connection is re-authorised whenever its token expires.',
+      // Undefined `client` rather than 'own' where it is the only browser route:
+      // there is nothing to override, and forcing it would write an `oauth_apps`
+      // entry for a provider whose manifest already says it is the only way.
+      chosen: { kind: 'oauth', id: 'own_client', client: broker ? 'own' : undefined },
+    });
+  }
+
+  // Last, always. It is the way in when the others are refused, not one anyone
+  // should be reaching for first: what it stores is the credential itself
+  // rather than a means of obtaining one, so rotating it is manual, and nothing
+  // can show what it is allowed to do.
+  const pasted = (manifest.setup?.prompts ?? []).filter((prompt) => prompt.scope === 'connection');
+  if (pasted.length > 0) {
+    found.push({
+      id: 'pasted_token',
+      label: `Paste a ${pasted.map((prompt) => prompt.label).join(', then ')} you already hold`,
+      detail:
+        'no browser, for a workspace that has not approved this app — which an admin decides, ' +
+        'not you. The credential is stored as given, so rotating it is manual and nothing can ' +
+        'say what it is allowed to do.',
+      chosen: { kind: 'pasted', id: 'pasted_token' },
+    });
+  }
+
+  return found;
+}
+
+/** What `--auth` will accept for this provider, for a message that lists them. */
+export function methodsFor(manifest: ProviderManifest): readonly string[] {
+  return options(manifest).map((option) => option.id);
+}
+
+/**
+ * Choose, from the flag or from the operator — and from nothing else.
+ *
+ * Nothing is inferred from what this account authenticates with today, which is
+ * a decision rather than an omission. A connection authenticates one way at a
+ * time: whichever route this run picks replaces the credential the account has
+ * now, and re-running `connect` is how somebody switches. Defaulting to the
+ * stored route would mean reading a credential to answer a question that is the
+ * operator's on every run, and would hide the replacement behind a default that
+ * reads as a no-op.
+ *
+ * It used to try. The route was read from the *provisional* connection id,
+ * which is `pending` until identity is settled — so it found nothing every
+ * time, fell back to the browser, and performed the silent swap it existed to
+ * prevent on anyone who pressed Enter. Saying what the choice does is the part
+ * that was actually missing.
+ */
+export async function chooseAuthMethod(input: {
+  readonly manifest: ProviderManifest;
+  /** `--auth <method>`, if it was given. */
+  readonly requested: string | undefined;
+  /** `--own-client`, which is the older spelling of one of these. */
+  readonly ownClient?: boolean;
+  readonly prompter?: Prompter;
+}): Promise<ChosenMethod> {
+  const { manifest, requested } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  const available = options(manifest);
+
+  if (requested !== undefined) {
+    // `oauth` is not an option id. It is the older, coarser spelling — "the
+    // browser, however this profile already resolves it" — and dropping it
+    // would break a scripted `--auth oauth` for no gain.
+    if (requested === 'oauth') return { kind: 'oauth', client: undefined };
+
+    const picked = available.find((option) => option.id === requested);
+    if (picked) return picked.chosen;
+
+    throw new Error(
+      `${manifest.name} cannot authenticate with "${requested}". ` +
+        `--auth accepts: ${['oauth', ...methodsFor(manifest)].join(', ')}.`,
+    );
+  }
+
+  if (input.ownClient === true) return { kind: 'oauth', client: 'own' };
+
+  // One route, or none this file knows about: decide nothing and say nothing.
+  if (available.length < 2) return { kind: 'oauth', client: undefined };
+
+  // Nobody to ask. The flag above is the non-interactive answer, deliberately —
+  // guessing picks which credential gets overwritten (ADR-038).
+  if (!prompter.interactive) return { kind: 'oauth', client: undefined };
+
+  return ask(manifest, available, prompter);
+}
+
+async function ask(
+  manifest: ProviderManifest,
+  available: readonly Option[],
+  prompter: Prompter,
+): Promise<ChosenMethod> {
+  // "As it works today" for anyone who has not chosen otherwise: the hosted
+  // client where there is one, and otherwise the browser. Never the key — it is
+  // listed first because it is the one worth knowing about, and defaulting to
+  // the first entry would make Enter mean "the route with a console visit in
+  // it" for someone who was not reading.
+  const hosted = available.findIndex((option) => option.id === 'hosted_client');
+  const fallback =
+    hosted !== -1 ? hosted : Math.max(available.findIndex((option) => option.chosen.kind === 'oauth'), 0);
+  const preferred = String(fallback + 1);
+
+  progress();
+  progress(style.bold(`${manifest.name} can authenticate ${count(available.length)} ways`));
+  progress();
+  for (const [index, option] of available.entries()) {
+    progress(`  ${index + 1}. ${option.label}`);
+    progress(style.dim(`     ${option.detail}`));
+  }
+  progress();
+  // Printed whether or not this account is already connected, because it is a
+  // statement about what the command does rather than a reading of what is
+  // stored — and on a first connect it is true with nothing to replace.
+  progress(style.dim('  Whichever you pick becomes the only way in for this account. It replaces'));
+  progress(
+    style.dim('  whatever is stored for it now — a connection authenticates one way at a time.'),
+  );
+  progress();
+
+  const answer = await prompter.ask(`  Which ${style.dim(`[${preferred}]`)}`);
+  const picked = answer.length === 0 ? preferred : answer;
+
+  const byNumber = available[Number(picked) - 1];
+  if (/^\d+$/.test(picked) && byNumber) return byNumber.chosen;
+
+  const byName = available.find((option) => option.id === picked);
+  if (byName) return byName.chosen;
+
+  throw new Error(
+    `"${picked}" is not one of the choices. Answer 1 to ${available.length}.`,
+  );
+}
+
+const WORDS = ['no', 'one', 'two', 'three', 'four', 'five'];
+const count = (total: number): string => WORDS[total] ?? String(total);

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

@@ -17,6 +17,10 @@ export interface ConnectOutcome {
   readonly ok: boolean;
   readonly key?: string;
   readonly account?: string;
+  /** The profile written to, for a caller that cannot see the announce line. */
+  readonly profile?: string;
+  /** The target written to — which credential store now holds this account. */
+  readonly target?: string;
   readonly changes: readonly string[];
   readonly granted: readonly string[];
   /**
@@ -45,6 +49,35 @@ export const NOTHING = { changes: [], granted: [], discovered: 0 } as const;
 
 export const ALREADY = 'Already connected — nothing changed.';
 
+/**
+ * One result for an account that turned out to be several services.
+ *
+ * The whole account succeeded only if every service did. A partial result is the
+ * case worth surfacing: one member blocked on a value leaves an account half
+ * connected, which `status` shows and prose does not.
+ */
+export function familyOutcome(members: readonly ConnectOutcome[]): ConnectOutcome {
+  const blocked = members.find((outcome) => !outcome.ok);
+
+  return {
+    ...NOTHING,
+    ok: members.every((outcome) => outcome.ok),
+    members,
+    ...(blocked?.reason ? { reason: blocked.reason } : {}),
+  };
+}
+
+/**
+ * Which store an account landed in, for the caller not reading the terminal.
+ *
+ * `announceConnectTarget` fixes the human channel. A `--json` caller had the
+ * same blindness the operator did — and an agent is exactly the reader who
+ * cannot see the line printed above it.
+ */
+export function where(runtime: { resolution: { profile: string; target: string } }) {
+  return { profile: runtime.resolution.profile, target: runtime.resolution.target };
+}
+
 /**
  * What `connect` says last.
  *
@@ -101,7 +134,15 @@ export function renderOutcome(outcome: ConnectOutcome): void {
  */
 function renderBlocked(outcome: ConnectOutcome): void {
   progress();
-  print(fail(outcome.reason === 'needs_browser' ? 'a browser is needed' : 'more is needed first'));
+  print(
+    fail(
+      outcome.reason === 'needs_browser'
+        ? 'a browser is needed'
+        : outcome.reason === 'needs_terminal'
+          ? 'a terminal is needed'
+          : 'more is needed first',
+    ),
+  );
 
   for (const line of (outcome.message ?? '').split('\n')) print(`      ${line}`);
 

package/src/cli/commands/connect/pasted-token.ts

@@ -0,0 +1,66 @@
+import { PASTED } from '#connectivity/auth/index.ts';
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { ok, progress } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { askForSetup } from './setup.ts';
+
+/**
+ * `--auth pasted_token`: a credential the operator already holds.
+ *
+ * The escape hatch, and it exists because the flow above can be refused by
+ * somebody who is not in the room. A Slack workspace on Enterprise Grid
+ * requires an admin to approve an app before it can authenticate anyone, so an
+ * operator whose admin has not approved the Lanes app cannot connect at all —
+ * while a user token from an app their workspace already trusts works
+ * perfectly. Removing the paste would take Slack away from exactly the people
+ * who have the least ability to do anything about it.
+ *
+ * Written in the blob shape the OAuth path writes, into the same ref, which is
+ * what makes it cost nothing downstream: no refresh token means
+ * `upstreamAccessToken` hands the stored value back untouched, and no
+ * `expires_at` means nothing calls it stale. `auth.kind` stays `oauth` because
+ * it describes what the vendor offers, not how this one connection was filled.
+ */
+export async function authorisePastedToken(input: {
+  manifest: ProviderManifest;
+  connectionId: string;
+  credentials: SecretStore;
+  prompter?: Prompter;
+}): Promise<void> {
+  const { manifest, connectionId, credentials } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  if (manifest.auth.kind !== 'oauth') return;
+
+  const prompts = (manifest.setup?.prompts ?? []).filter((prompt) => prompt.scope === 'connection');
+  if (prompts.length === 0) {
+    throw new Error(
+      `${manifest.name} has no pasted-credential path: it does not describe a token to ask you ` +
+        'for. Authorise in a browser instead — drop --auth, or pass --auth oauth.',
+    );
+  }
+
+  const ref = `${manifest.id}/${connectionId}`;
+  const answers = await askForSetup(
+    manifest,
+    prompts,
+    `Stored at ${ref}, in the credential store — never in config.`,
+    prompter,
+  );
+
+  await credentials.set(
+    ref,
+    JSON.stringify({
+      access_token: answers.get(prompts[0]!.key)!,
+      token_type: 'Bearer',
+      // What the token can do was decided wherever it was minted and cannot be
+      // read back, so this records what was asked for and no more. The scope
+      // gate the browser path runs has nothing to show here — recorded as a
+      // weaker guarantee in security.md rather than papered over.
+      scope: manifest.auth.scopes.join(' '),
+      authorized_via: PASTED,
+    }),
+  );
+
+  progress(ok('token stored'));
+}

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

@@ -32,7 +32,12 @@ export async function missingRequirements(
   return missing;
 }
 
-export type BlockedReason = 'needs_id' | 'needs_browser' | 'missing_credentials';
+export type BlockedReason =
+  | 'needs_id'
+  | 'needs_browser'
+  /** A question only a person can answer, on a run with nobody to ask. */
+  | 'needs_terminal'
+  | 'missing_credentials';
 
 export interface Blocked {
   readonly reason: BlockedReason;
@@ -60,14 +65,53 @@ export async function preflight(input: {
   readonly manifest: ProviderManifest;
   readonly connectionId: string | undefined;
   readonly profile: string;
-  readonly credentials: { has(ref: string): Promise<boolean> };
-  /** How the operator spelled the target — `icloud`, or `gmail.main`. */
+  /** Which target's credential store the values have to be in. */
   readonly target: string;
+  readonly credentials: { has(ref: string): Promise<boolean> };
+  /**
+   * How the operator spelled the provider — `icloud`, or `gmail.main`.
+   *
+   * Called `spec` and not `target`, which is what it was: this file holds the
+   * only two meanings of that word in one scope, and the Lanes target is the one
+   * that decides which credential store a suggested command writes into. A
+   * transposition here produces a command that runs and stores a credential
+   * somewhere nobody looks.
+   */
+  readonly spec: string;
+  /**
+   * Which way in the operator chose, for a provider offering two.
+   *
+   * The whole reason this parameter exists is that the OAuth refusal below is
+   * about a *browser*, and the key route opens none. Without it a scripted
+   * `connect --auth <key method>` would be turned away by a message describing
+   * a step it does not perform.
+   */
+  readonly method?: 'oauth' | 'assertion' | 'pasted';
 }): Promise<Blocked | null> {
-  const { manifest, connectionId, profile, target } = input;
-  const rerun = `lanes link connect ${target} --profile ${profile}`;
+  const { manifest, connectionId, profile, target, spec } = input;
+  const method = input.method ?? 'oauth';
+  const rerun = `lanes link connect ${spec} --profile ${profile} --target ${target}`;
+  const assertion = manifest.auth.kind === 'oauth' ? manifest.auth.assertion : undefined;
 
-  if (manifest.auth.kind === 'oauth') {
+  if (method === 'assertion' && assertion) {
+    // The key can be placed ahead of time; who it acts as cannot. That value
+    // lives inside the pointer `connect` writes, so where it is mandatory this
+    // run has a question and nobody to ask — and refusing here is better than
+    // storing a credential that reads every mailbox as empty.
+    if (assertion.delegation === 'required') {
+      return {
+        reason: 'needs_terminal',
+        message:
+          `${manifest.name} can only reach an account by acting as someone, and who that is has ` +
+          `to be typed.\n  Nothing was written. Run this in a terminal:`,
+        needs: [],
+        then: `${rerun} --auth ${assertion.method}`,
+      };
+    }
+  } else if (manifest.auth.kind === 'oauth' && method !== 'pasted') {
+    // `pasted` opens no browser, so the refusal below does not describe it. It
+    // needs a value instead, which *can* be placed ahead of time — so it falls
+    // through to the requirement check and gets the `secrets set` line.
     return {
       reason: 'needs_browser',
       message:
@@ -78,7 +122,12 @@ export async function preflight(input: {
     };
   }
 
-  const { requirements, needsId } = setupRequirements(manifest, connectionId, profile);
+  const { requirements, needsId } = setupRequirements(
+    manifest,
+    connectionId,
+    { profile, target },
+    { method },
+  );
 
   if (needsId) {
     return {
@@ -98,6 +147,9 @@ export async function preflight(input: {
     reason: 'missing_credentials',
     message: `${manifest.name} needs ${missing.length} value(s) in the credential store first.`,
     needs: missing,
-    then: `${rerun}${connectionId ? ` --id ${connectionId}` : ''} --non-interactive`,
+    then:
+      `${rerun}${connectionId ? ` --id ${connectionId}` : ''}` +
+      `${method === 'assertion' && assertion ? ` --auth ${assertion.method}` : ''}` +
+      `${method === 'pasted' ? ' --auth pasted_token' : ''} --non-interactive`,
   };
 }

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

@@ -1,5 +1,5 @@
 import type { SecretStore } from '#secrets';
-import type { ProviderManifest, SetupPrompt } from '#connectivity';
+import type { ProviderManifest, SetupDeclaration, SetupPrompt } from '#connectivity';
 import { credentialRefForConnection } from '#connectivity';
 import { ConfigDocument } from '../../config-edit.ts';
 import { ok, progress, style } from '../../output.ts';
@@ -27,8 +27,18 @@ import { terminalPrompter, type Prompter } from '../../prompt.ts';
  * 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;
+export function printSetup(
+  manifest: ProviderManifest,
+  note: string,
+  /**
+   * Which walkthrough. Defaults to the provider's own, and is passed explicitly
+   * by a provider that has more than one way in — those steps are a different
+   * console doing a different job, and printing the browser-flow instructions
+   * to someone who chose a key would be worse than printing nothing.
+   */
+  declaration: SetupDeclaration | undefined = manifest.setup,
+): void {
+  const setup = declaration;
   if (!setup) return;
 
   progress();
@@ -55,15 +65,16 @@ export async function askForSetup(
   prompts: readonly SetupPrompt[],
   note: string,
   prompter: Prompter = terminalPrompter,
+  declaration: SetupDeclaration | undefined = manifest.setup,
 ): Promise<Map<string, string>> {
-  const setup = manifest.setup;
+  const setup = declaration;
   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);
+  printSetup(manifest, note, setup);
 
   const answers = new Map<string, string>();
   for (const prompt of prompts) {

package/src/cli/commands/connect/target-note.ts

@@ -0,0 +1,34 @@
+import type { Config, Resolution } from '#profile';
+import { announce } from '../../output.ts';
+
+/**
+ * The line `connect` prints before it acts.
+ *
+ * Split from the five steps for the reason `outcome.ts` gives: the orchestration
+ * is about vendors and credentials, this is about what a caller is told. It buys
+ * the same thing too — no runtime, no config file and no credential store are
+ * needed to check that the line appears and that `--json` stays parseable.
+ *
+ * `connect` was the only mutating command that never said which target it wrote
+ * to, and the only one that writes a credential into a real store.
+ *
+ * This file also *held* a warning, for the case where a bare `connect` resolved
+ * to a local target while the profile declared a deployed one. ADR-037 removed
+ * the case rather than the warning: a target is named on the command line or the
+ * command does not run, so there is no longer a selection the operator did not
+ * make. What replaced it sits one step earlier — `deployments/servable.ts`
+ * refuses a *deploy* that would send a profile the revision cannot open, which
+ * is the same mistake caught where it is still cheap.
+ */
+export function announceConnectTarget(
+  runtime: { readonly resolution: Resolution; readonly config: Pick<Config, 'targets'> },
+  json?: boolean | undefined,
+): void {
+  // `emit`'s early return only protects lines printed *at* the emit, and this
+  // one has to precede the browser — so it carries its own guard, the one
+  // `audit.ts` and `owner/shared.ts` already use. `output.ts` gives the reason
+  // beside `emit`: a line of prose in front of a JSON document corrupts it.
+  if (json === true) return;
+
+  announce(runtime.resolution);
+}