@lanes-sh/link 0.2.1 → 0.3.0

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);
+}

package/src/cli/commands/identity.ts

@@ -0,0 +1,258 @@
+import type { IdentityEntry, ProfileSelection, Resolution } from '#profile';
+import { ConfigDocument } from '../config-edit.ts';
+import { ensureIdentityConnection, repairLines, repaired } from '../config-repair.ts';
+import { announce, announceProfile, emit, ok, print, style, table, warn } from '../output.ts';
+import { resolveProfile, resolveProfileOnly, type GlobalFlags } from '../runtime.ts';
+import { nextAfterEdit, publishProfileEdit } from '../publish.ts';
+
+/**
+ * `lanes link identity` — who this profile's owner is, for anything written as them.
+ *
+ * A control-plane command under ADR-007, and the reason is sharper here than for
+ * most of them: an agent able to edit this could edit the one fact that stops it
+ * signing as the wrong person. So the surface it feeds is read-only and the
+ * editing is here.
+ *
+ * Not to be confused with `src/cli/identity.ts`, which is about a *connection's*
+ * identity — which account it is, as the provider reports it at connect time.
+ * This is the owner's, as they declare it.
+ *
+ * Each command is a data function plus a printing wrapper, for the reason given
+ * in `commands/profile.ts`: `--json` needs the facts without the rendering.
+ */
+
+/** What `add` did, including anything it provisioned to make it readable. */
+export interface IdentityAdded {
+  readonly profile: string;
+  readonly entry: IdentityEntry;
+  /** Config edits made so the surface is reachable at all. Usually empty. */
+  readonly provisioned: readonly string[];
+  readonly total: number;
+}
+
+export interface IdentityListing {
+  readonly profile: string;
+  readonly entries: readonly IdentityEntry[];
+  /** Whether an agent can read them, or only the file can. */
+  readonly reachable: boolean;
+}
+
+/** Whether a rule list puts `identity.*` in force, in either spelling. */
+function covers(rules: ReadonlyArray<{ capability: string }>): boolean {
+  return rules.some((rule) => rule.capability === '*' || rule.capability === 'identity.*');
+}
+
+/**
+ * Whether anything but the file can read this profile's identity.
+ *
+ * Reported rather than assumed, because a profile hand-edited to hold an
+ * `identity` block and nothing else is a real state and a likely one — and
+ * listing the entries without saying they are unreachable would be the most
+ * misleading thing this command could print.
+ */
+function readable(config: {
+  connections: ReadonlyArray<{ provider: string }>;
+  policy: { allow: ReadonlyArray<{ capability: string }>; deny: ReadonlyArray<{ capability: string }> };
+}): boolean {
+  return (
+    config.connections.some((connection) => connection.provider === 'identity') &&
+    covers(config.policy.allow) &&
+    !covers(config.policy.deny)
+  );
+}
+
+/**
+ * Declare one entry, and make sure something can read it.
+ *
+ * The provisioning is the part worth understanding. An `identity` block on its
+ * own is inert: `allowedConnections` finds no connection row for the provider
+ * and returns nothing *before* it consults policy, so the surface is absent from
+ * `tools/list` with nothing saying why — the same silent failure
+ * `ensureIdentityConnection` closes for `setup`. Writing the entry without it
+ * would leave an operator looking at a file that says exactly what they meant
+ * and an agent that cannot see a word of it.
+ *
+ * All three edits land in one `save()`, and that is not tidiness:
+ * `validateConfig` refuses a `policy.allow` rule naming a provider with no
+ * connection, so a run that wrote the rule and failed before the row would
+ * leave a profile that no longer loads. One save has no such middle.
+ */
+export async function addIdentity(
+  kind: string,
+  value: string,
+  options: { note?: string | undefined } & GlobalFlags,
+): Promise<{ resolution: Resolution; added: IdentityAdded; published: string }> {
+  const { resolution, config, target } = await resolveProfile(options);
+
+  if (config.identity.some((entry) => entry.kind === kind && entry.value === value)) {
+    throw new Error(
+      `Profile "${resolution.profile}" already declares ${kind} "${value}".\n` +
+        `  To change its note: lanes link identity remove ${kind} ${value}, then add it again.`,
+    );
+  }
+
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+
+  const entry: IdentityEntry = { kind, value, ...(options.note ? { note: options.note } : {}) };
+  document.addTo(['identity'], entry, { inline: true });
+
+  const repair = ensureIdentityConnection(document);
+  await document.save();
+
+  return {
+    resolution,
+    added: {
+      profile: resolution.profile,
+      entry,
+      provisioned: repaired(repair) ? repairLines(repair) : [],
+      total: config.identity.length + 1,
+    },
+    published: nextAfterEdit(await publishProfileEdit({ resolution, config, target })),
+  };
+}
+
+/**
+ * Read the block, without opening a target.
+ *
+ * `resolveProfileOnly`, deliberately: this reads one field of a YAML file that
+ * is declared once and applies to every target the profile has, so demanding
+ * `--target` would be the ceremony ADR-037 warns is how a required flag stops
+ * being a guard. `SELECTION` files it as `profile`, and this is the call that
+ * makes that true rather than merely stated.
+ */
+export async function readIdentity(
+  flags: GlobalFlags,
+): Promise<{ selection: ProfileSelection; listing: IdentityListing }> {
+  const { selection, config } = await resolveProfileOnly(flags);
+
+  return {
+    selection,
+    listing: {
+      profile: selection.profile,
+      entries: config.identity,
+      reachable: readable(config),
+    },
+  };
+}
+
+/**
+ * Drop one entry, leaving the connection row and the grant behind.
+ *
+ * Deliberately: removing the last entry would otherwise silently revoke the
+ * surface, and the next `identity add` would have to widen policy again. A
+ * command that quietly narrows what an agent may read, and a later one that
+ * quietly re-widens it, is worse than a surface that reports nothing declared.
+ */
+export async function removeIdentity(
+  kind: string,
+  value: string,
+  flags: GlobalFlags,
+): Promise<{
+  resolution: Resolution;
+  removed: IdentityEntry;
+  remaining: number;
+  published: string;
+}> {
+  const { resolution, config, target } = await resolveProfile(flags);
+
+  const index = config.identity.findIndex((entry) => entry.kind === kind && entry.value === value);
+  if (index === -1) {
+    throw new Error(
+      `Profile "${resolution.profile}" does not declare ${kind} "${value}".\n` +
+        `  Run: lanes link identity list`,
+    );
+  }
+
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+  document.removeFrom(['identity'], index);
+  await document.save();
+
+  return {
+    resolution,
+    removed: config.identity[index] as IdentityEntry,
+    remaining: config.identity.length - 1,
+    published: nextAfterEdit(await publishProfileEdit({ resolution, config, target })),
+  };
+}
+
+export async function identityAdd(
+  kind: string,
+  value: string,
+  options: { note?: string | undefined; json?: boolean } & GlobalFlags,
+): Promise<void> {
+  const { resolution, added, published } = await addIdentity(kind, value, options);
+
+  return emit(options.json, added, () => {
+    announce(resolution);
+    print(ok(`${added.entry.kind} ${style.bold(added.entry.value)}`));
+    if (added.entry.note) print(`      note    ${added.entry.note}`);
+
+    // Named rather than folded into the success line: this widened what an
+    // agent may read, and a command that broadens a grant says which grant.
+    for (const line of added.provisioned) print(`      ${style.dim(line)}`);
+    if (added.provisioned.length > 0) {
+      print(style.dim('      an agent can now read this profile’s identity'));
+    }
+
+    print(style.dim(`  ${published}`));
+  });
+}
+
+export async function identityList(options: { json?: boolean } & GlobalFlags): Promise<void> {
+  const { selection, listing } = await readIdentity(options);
+
+  return emit(options.json, listing, () => {
+    announceProfile(selection);
+
+    if (listing.entries.length === 0) {
+      print(style.dim('This profile declares no identity.'));
+      print(
+        style.dim('Declare one with: lanes link identity add name "Your Name" --note "when to use it"'),
+      );
+      return;
+    }
+
+    // Grouped by kind for the same reason the provider groups them: the mistake
+    // this exists to prevent is a name used where an address was wanted.
+    const kinds = [...new Set(listing.entries.map((entry) => entry.kind))];
+    const ordered = kinds.flatMap((kind) =>
+      listing.entries.filter((entry) => entry.kind === kind),
+    );
+
+    table(
+      ordered.map((entry) => [
+        `  ${style.dim(entry.kind)}`,
+        style.bold(entry.value),
+        entry.note ? style.dim(entry.note) : '',
+      ]),
+    );
+
+    if (!listing.reachable) {
+      print('');
+      print(warn('declared, but no agent can read it'));
+      print(
+        style.dim(
+          '      the identity surface needs a connection row and an identity.* allow rule;',
+        ),
+      );
+      print(style.dim('      adding an entry with this command writes both.'));
+    }
+  });
+}
+
+export async function identityRemove(
+  kind: string,
+  value: string,
+  options: { json?: boolean } & GlobalFlags,
+): Promise<void> {
+  const { resolution, removed, remaining, published } = await removeIdentity(kind, value, options);
+
+  return emit(options.json, { removed, remaining }, () => {
+    announce(resolution);
+    print(ok(`removed ${removed.kind} ${style.bold(removed.value)}`));
+    if (remaining === 0) {
+      print(style.dim('      the surface stays granted, and now reports nothing declared'));
+    }
+    print(style.dim(`  ${published}`));
+  });
+}