@lanes-sh/link 0.2.2 → 0.3.0

package/src/cli/selection.ts

@@ -0,0 +1,357 @@
+import {
+  ConfigError,
+  listProfiles,
+  loadProfileConfig,
+  noProfileNamed,
+  noTargetNamed,
+  resolveWorkspaceRoot,
+} from '#profile';
+import type { Flags } from './argv.ts';
+
+/**
+ * Which commands must name a profile and a target, and which flags each accepts.
+ *
+ * Two rules, in one file because they fail for the same reason and the fix for
+ * one makes the other legible.
+ *
+ * **A flag that is silently ignored is the defect.** `lanes link profile add
+ * work --target cloud` printed `ok` and dropped the flag: `main.ts` built a
+ * literal for that command and never spread the global flags into it. Nothing
+ * refused, because nothing had a list of what the command accepts. That is what
+ * `assertKnownFlags` is — and it matters more than the requirement, because
+ * required flags make a typo *worse* on their own. `--porfile work` used to
+ * fall through to a workspace default and mostly work; with a requirement and
+ * no allowlist it produces "--profile is required", naming a flag the operator
+ * believes they just passed.
+ *
+ * **A selection is named or the command does not run** (ADR-037). The table
+ * below is the whole rule, and `selection.test.ts` reads `main.ts` to check that
+ * every dispatched command appears in it — so a new command cannot quietly
+ * default to requiring nothing.
+ */
+
+/** What a command must be told before it can act. */
+export type Requires = 'none' | 'profile' | 'profile+target';
+
+/**
+ * The rule, per command path.
+ *
+ * `--profile` for anything that reads or writes a profile's config or stores.
+ * `--target` for anything that opens a target's adapters or acts against a
+ * target's endpoint. A command that names a target positionally or through
+ * `--from`/`--to` supplies it that way and is not asked twice.
+ *
+ * Three entries are worth defending, because uniformity would be wrong:
+ *
+ * `check`, `config show` and `policy list` take no `--target`. All three are
+ * target-independent — a YAML file, the whole of it, and a policy block that is
+ * declared once and applies everywhere. Demanding a target would be the
+ * ceremony that teaches people to type `--target local` without reading it,
+ * which is how a required flag stops being a guard.
+ *
+ * `target list` takes no required `--target` either, and that is not an
+ * oversight: it is the command you run to find out what to pass. Requiring the
+ * answer as input is circular, and it has to keep working in the state every
+ * other command fails in.
+ *
+ * `profile add` **rejects** both. The name is positional, and there is no
+ * profile to select before it exists.
+ */
+export const SELECTION: Record<string, Requires> = {
+  help: 'none',
+  version: 'none',
+  update: 'none',
+  skill: 'none',
+  'mcp skill': 'none',
+  'mcp list': 'none',
+  // The bare forms, which each dispatch to a `case undefined` in `main.ts`.
+  // `lanes link profile` is `profile list`, and needs the same as it.
+  profile: 'none',
+  mcp: 'none',
+  'profile list': 'none',
+  'profile add': 'none',
+  'profile default': 'none',
+  'target use': 'none',
+  'vault key': 'none',
+
+  check: 'profile',
+  config: 'profile',
+  policy: 'profile',
+  target: 'profile',
+  'config show': 'profile',
+  'policy list': 'profile',
+  'target list': 'profile',
+  'target show': 'profile',
+  'secrets push': 'profile',
+  'profile remove': 'profile',
+  // Target-independent for the same reason `policy list` is: the block is
+  // declared once in the YAML and applies to every target the profile has.
+  identity: 'profile',
+  'identity list': 'profile',
+
+  connect: 'profile+target',
+  setup: 'profile+target',
+  token: 'profile+target',
+  audit: 'profile+target',
+  secrets: 'profile+target',
+  plan: 'profile+target',
+  doctor: 'profile+target',
+  status: 'profile+target',
+  outputs: 'profile+target',
+  tools: 'profile+target',
+  // It reads which target it is rendering for before it decides anything: a
+  // deployed one has no page to open, and the refusal has to name it.
+  dashboard: 'profile+target',
+  attach: 'profile+target',
+  start: 'profile+target',
+  deploy: 'profile+target',
+  'policy allow': 'profile+target',
+  'policy deny': 'profile+target',
+  // Both, unlike `identity list`, and for the same reason the policy edits are:
+  // each publishes the edit, which opens the target's credential store and
+  // reaches that target's endpoint.
+  'identity add': 'profile+target',
+  'identity remove': 'profile+target',
+  'token show': 'profile+target',
+  'token rotate': 'profile+target',
+  'audit tail': 'profile+target',
+  'audit verify': 'profile+target',
+  'secrets set': 'profile+target',
+  'secrets list': 'profile+target',
+  'mcp add': 'profile+target',
+  'mcp stdio': 'profile+target',
+  memory: 'profile+target',
+  skills: 'profile+target',
+  vault: 'profile+target',
+  // Both halves open the target's adapters — `show` counts what is in the
+  // stores, and `use` migrates between them — and both edit the profile's
+  // config. Neither can be answered without being told which.
+  knowledge: 'profile+target',
+};
+
+/**
+ * The second words each command accepts.
+ *
+ * Only the commands that have subcommands appear. This exists for one reason:
+ * the checks below run before the switch, so without it `lanes link vault bogus`
+ * is refused for a missing `--profile` rather than for the subcommand that does
+ * not exist — a usage error reported as the wrong usage error, which is its own
+ * small version of the bug being fixed. `selection.test.ts` reads `main.ts` and
+ * asserts this stays true.
+ */
+const SUBCOMMANDS: Record<string, readonly string[]> = {
+  profile: ['add', 'list', 'default', 'remove'],
+  target: ['list', 'use', 'show'],
+  policy: ['list', 'allow', 'deny'],
+  identity: ['add', 'list', 'remove'],
+  token: ['show', 'rotate'],
+  audit: ['tail', 'verify'],
+  config: ['show'],
+  setup: ['plan'],
+  memory: ['list', 'get', 'write', 'forget'],
+  skills: ['list', 'show', 'add', 'remove'],
+  vault: ['list', 'get', 'set', 'remove', 'key'],
+  mcp: ['skill', 'add', 'stdio', 'list'],
+  secrets: ['push', 'set', 'list'],
+  knowledge: ['show', 'use'],
+};
+
+/**
+ * Whether the switch is going to refuse this command path anyway.
+ *
+ * When it is, these checks stay quiet and let it: "Unknown: lanes link vault
+ * bogus" is the useful sentence, and a complaint about `--profile` on a command
+ * that does not exist sends someone off to fix the wrong thing.
+ */
+function dispatchWillRefuse(first: string, second: string | undefined): boolean {
+  const known = SUBCOMMANDS[first];
+  if (!known || second === undefined) return false;
+  return !known.includes(second);
+}
+
+/**
+ * The key for a command, longest match first.
+ *
+ * `token show` before `token`, so a two-word command can differ from its
+ * siblings without every sibling having to be listed.
+ */
+export function selectionKey(first: string, second: string | undefined): string {
+  const pair = second ? `${first} ${second}` : first;
+  if (pair in SELECTION) return pair;
+  return first;
+}
+
+/** Whether this command needs a profile, a target, both, or neither. */
+export function requirementFor(first: string, second: string | undefined): Requires {
+  return SELECTION[selectionKey(first, second)] ?? 'profile+target';
+}
+
+/**
+ * Refuse before the command runs, naming what it wants and what there is.
+ *
+ * Async, and it reads the workspace — but only on the way to throwing. The
+ * useful half of "which profile did you mean" is the list of them, and the same
+ * for targets; a refusal that only restates the flag name leaves someone to go
+ * and look it up. Both messages come from `#profile` so this file and the
+ * resolver cannot describe the same refusal differently, and both name an
+ * exported variable that no longer counts — the shell still configured for the
+ * old world is the state hardest to diagnose from the inside.
+ */
+export async function requireSelection(
+  first: string,
+  second: string | undefined,
+  flags: Flags,
+  env?: Record<string, string | undefined>,
+): Promise<void> {
+  if (dispatchWillRefuse(first, second)) return;
+
+  const needs = requirementFor(first, second);
+  if (needs === 'none') return;
+
+  const profile = flags['profile'];
+  if (typeof profile !== 'string') {
+    const root = resolveWorkspaceRoot(env ? { env } : {});
+    throw noProfileNamed(root, await listProfiles(root), env);
+  }
+
+  if (needs !== 'profile+target' || typeof flags['target'] === 'string') return;
+
+  // The profile is known by here, so the target list is the one belonging to it
+  // rather than a guess. A profile that does not exist is a different refusal,
+  // and `resolveSelection` gives it a better one a moment later.
+  const root = resolveWorkspaceRoot(env ? { env } : {});
+  try {
+    const { config } = await loadProfileConfig(root, profile);
+    throw noTargetNamed(config, profile, env);
+  } catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError(`--target is required for "${[first, second].filter(Boolean).join(' ')}".`);
+  }
+}
+
+/**
+ * Flags every command accepts, whatever it does.
+ *
+ * `--help` short-circuits before dispatch, and `--json` is offered widely enough
+ * that listing it per command would be noise. `--quiet` is read by `announce`
+ * rather than by any one command.
+ */
+const UNIVERSAL = ['help', 'json', 'quiet'];
+
+/**
+ * What each command accepts beyond the universal set and its own selection.
+ *
+ * Only commands with flags of their own appear. Anything absent accepts the
+ * universal set plus whatever `SELECTION` says it must be told.
+ */
+const ACCEPTS: Record<string, readonly string[]> = {
+  // `own-client` is the older spelling of one of the routes `auth` names, kept
+  // because it is in scripts and a year of documentation (ADR-038).
+  connect: [
+    'id',
+    'display-name',
+    'replace',
+    'non-interactive',
+    'accept-broad-scopes',
+    'own-client',
+    'auth',
+  ],
+  setup: ['id'],
+  'profile add': ['target', 'non-interactive'],
+  'profile remove': ['dry-run', 'yes'],
+  'target list': ['urls', 'target'],
+  'target show': ['target'],
+  'token show': ['show', 'raw'],
+  'token rotate': ['show', 'raw', 'yes'],
+  'audit tail': ['limit', 'denied-only', 'format'],
+  'audit verify': ['limit', 'format'],
+  attach: ['connection'],
+  outputs: ['show'],
+  start: ['port', 'only'],
+  'mcp stdio': ['only'],
+  'mcp add': ['name', 'scope', 'token-env', 'dry-run', 'force', 'no-skill'],
+  'mcp skill': ['print', 'force'],
+  dashboard: ['print'],
+  skill: ['print', 'force'],
+  deploy: ['dry-run', 'iam', 'access', 'service-account', 'tag', 'yes', 'non-interactive'],
+  'secrets push': ['from', 'to', 'overwrite', 'dry-run'],
+  update: ['check'],
+  'identity add': ['note'],
+  memory: ['connection', 'title', 'description', 'file'],
+  skills: ['connection', 'title', 'description', 'file'],
+  vault: ['connection'],
+  // `no-migrate` is listed beside `migrate` because they are three states
+  // rather than two: neither one asks, and a run with no terminal has to be
+  // able to say which it meant (ADR-041).
+  knowledge: ['repo', 'branch', 'path', 'migrate', 'no-migrate', 'keep', 'allow-public', 'replace', 'yes'],
+};
+
+/**
+ * Refuse a flag this command does not read, and guess what was meant.
+ *
+ * This is the fix for the reported bug rather than a nicety. `profile add
+ * --target cloud` was accepted and dropped, and nothing could refuse it because
+ * `parseArgv` returns every `--anything` it sees and no command ever inspected
+ * the leftovers. A typo was swallowed the same way on every command in the CLI.
+ */
+export function assertKnownFlags(first: string, second: string | undefined, flags: Flags): void {
+  if (dispatchWillRefuse(first, second)) return;
+
+  const key = selectionKey(first, second);
+  const needs = SELECTION[key] ?? 'profile+target';
+
+  const allowed = new Set<string>([
+    ...UNIVERSAL,
+    ...(ACCEPTS[key] ?? []),
+    ...(needs === 'profile' || needs === 'profile+target' ? ['profile'] : []),
+    ...(needs === 'profile+target' ? ['target'] : []),
+  ]);
+
+  const named = [first, second].filter(Boolean).join(' ');
+
+  for (const given of Object.keys(flags)) {
+    if (allowed.has(given)) continue;
+
+    throw new ConfigError(
+      `Unknown flag "--${given}" for "lanes link ${named}".` +
+        (nearest(given, allowed) ? `\n  Did you mean --${nearest(given, allowed)}?` : '') +
+        `\n  Accepts: ${[...allowed].sort().map((name) => `--${name}`).join(' ')}`,
+    );
+  }
+}
+
+/**
+ * The closest accepted flag, when there is an obviously close one.
+ *
+ * One edit away, or one transposition — enough for `--porfile` and `--taget`,
+ * and short of guessing at something the operator did not mean. A wrong guess
+ * here costs more than no guess: it sends them to a flag that is not the answer.
+ */
+function nearest(given: string, allowed: ReadonlySet<string>): string | undefined {
+  for (const candidate of allowed) {
+    if (Math.abs(candidate.length - given.length) > 1) continue;
+    if (distance(given, candidate) <= 1) return candidate;
+    if (sorted(given) === sorted(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+const sorted = (text: string): string => [...text].sort().join('');
+
+function distance(a: string, b: string): number {
+  let row = Array.from({ length: b.length + 1 }, (_, index) => index);
+
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) {
+      next[j] = Math.min(
+        row[j]! + 1,
+        next[j - 1]! + 1,
+        row[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    row = next;
+  }
+
+  return row[b.length]!;
+}

package/src/cli/usage.ts

@@ -24,11 +24,13 @@ ${style.bold('Everyday')}
   ${PROGRAM} connect <provider>         add an account (run once per account)
   ${PROGRAM} connect <provider>.<id>    re-authorise one existing account
   ${PROGRAM} connect <...> --replace    ask for the stored password or key again
+  ${PROGRAM} connect <...> --auth <method>  pick how, where there is a choice
   ${PROGRAM} connect <...> --non-interactive [--json]
                                         answer nothing from a terminal: take every value
                                         from the credential store, or say what is missing
   ${PROGRAM} start [--only]             reconcile and serve every profile on one endpoint
   ${PROGRAM} outputs [--show] [--json]  the endpoint an agent needs
+  ${PROGRAM} dashboard [--print]        open the local endpoint's page in a browser
   ${PROGRAM} mcp add [claude|codex]     register this endpoint, and install the agent skill
   ${PROGRAM} mcp add --no-skill         register only, leaving the agent's own files alone
   ${PROGRAM} mcp list                   where it is registered, and whether the skill is current
@@ -37,16 +39,22 @@ ${style.bold('Everyday')}
   ${PROGRAM} status [--json]            connections, reachable capabilities, endpoint
 
 ${style.bold('Profiles')}
-  ${PROGRAM} profile add <name> [--default] [--json]
+  ${PROGRAM} profile add <name> --target <name> [--target <name>] [--json]
+                                 a target per place it runs; local is derived, the
+                                 rest are copied from a sibling profile
   ${PROGRAM} profile list [--json]
-  ${PROGRAM} profile default <name>
   ${PROGRAM} profile remove <name> [--target t] [--dry-run] [--yes] [--json]
                                  the profile, its credentials, and its data
 
 ${style.bold('Targets')}
-  ${PROGRAM} target list [--urls]      where this profile can run, and which one is in play
-  ${PROGRAM} target show [<name>]      one target's adapters, and the address it answers on
-  ${PROGRAM} target use <name>         make one the profile's default_target
+  ${PROGRAM} target list [--urls]      where this profile can run
+  ${PROGRAM} target show <name>        one target's adapters, and the address it answers on
+
+${style.bold('Who you are')}
+  ${PROGRAM} identity add <kind> <value> [--note text] [--json]
+                                 e.g. name, email, github — any kind you like
+  ${PROGRAM} identity list [--json]
+  ${PROGRAM} identity remove <kind> <value> [--json]
 
 ${style.bold('Permissions')}
   ${PROGRAM} policy list
@@ -66,6 +74,14 @@ ${style.bold('Your own context')}
   ${PROGRAM} skills add <name> [--file f]             document on stdin
   ${PROGRAM} skills remove <name>
 
+  ${PROGRAM} knowledge show            where memory and skills are kept, and how many
+  ${PROGRAM} knowledge use github --repo <owner/name> [--branch b] [--path p]
+                                 keep both in a private repository, over the GitHub API
+                                 [--migrate] moves what is already stored, in one commit
+                                 [--no-migrate] switches and leaves it where it is
+                                 [--keep] moves it, and leaves the local copies unread
+  ${PROGRAM} knowledge use local [--migrate]        bring them back onto this target
+
   ${PROGRAM} vault list                 names only, never values
   ${PROGRAM} vault get <id> [--show|--raw]
   ${PROGRAM} vault set <id> [--description d]         value on stdin
@@ -96,9 +112,13 @@ ${style.bold('Attachments')}
   ${PROGRAM} attach <file> --connection <provider>.<account>
                                         stage a file, print a handle to send it by
 
-${style.bold('Global flags')}
-  --profile <name>               overrides LANES_LINK_PROFILE and the workspace default
-  --target <name>                overrides LANES_LINK_TARGET and instance.default_target
+${style.bold('Naming what a command acts on')}
+  --profile <name>               required by every command that reads or writes a profile
+  --target <name>                required by every command that opens a target's stores.
+                                 There is no default and no environment variable: a
+                                 command that names neither refuses and lists what exists.
+
+${style.bold('Other flags')}
   --connection <id>              which memory/skills/vault connection, if a profile has several
   --yes                          skip the confirmation a destructive command would ask for
   --json                         machine-readable output, where a command offers it
@@ -107,7 +127,10 @@ ${style.bold('Global flags')}
   --accept-broad-scopes          agree in advance to scopes broader than a provider needs
   --own-client                   register your own OAuth client instead of using the
                                  one this project operates (connect only)
+  --auth <method>                which way in, where a provider offers two (connect
+                                 only). "oauth" is the browser; the other is named
+                                 in the choice connect prints
   --port <n>                     override the configured port (start only)
 
-Every command prints the resolved profile and target before acting.
+Every command prints the profile and target it is acting on, before it acts.
 `;

package/src/connectivity/auth/README.md

@@ -14,6 +14,7 @@ transport asks when it has a token to send and no request to attach it to.
 | `api-key/` | `api_key` | a key, in a header or the query string |
 | `basic/` | `basic` | `username:password`, RFC 7617's own encoding |
 | `oauth-authcode/` | `oauth` | a refresh token, exchanged on every use |
+| `oauth-jwt/` | `oauth` + `assertion` | a private key, signed into an assertion per exchange |
 | `strategy/` | `strategy` | the escape hatch — per-vendor code, none registered |
 
 ## Adding one
@@ -22,13 +23,18 @@ A folder, a member of `authSchema` in `../manifest/auth.ts`, and a case in
 `resolve.ts` (plus `authorize.ts` if it touches the request). Nothing else in
 the codebase learns about it — that is the point of the split.
 
+`oauth-jwt/` is the exception that proves the shape rather than breaking it. It
+is not a `kind`, because it is a second way into a provider that already has
+one, so it hangs off the OAuth block as `auth.assertion` and is selected by the
+shape of the stored credential. Everything else about it is an ordinary folder
+here.
+
 These are named in the credential-type list this design is measured against and
 are **not built**:
 
 - `sigv4/` — AWS SigV4 request signing
 - `gcp-token/` — service account → GCP access token
 - `gcp-iap/` — service account → an IAP-signed JWT
-- `oauth-jwt/` — OAuth 2.0 JWT bearer (RFC 7523)
 - `oauth-client-creds/` — OAuth 2.0 client credentials
 - `body-param/` — the credential as a request body parameter
 

package/src/connectivity/auth/basic/index.ts

@@ -15,7 +15,7 @@ export function resolveBasic(value: string, ref: string, providerId: string): Re
   if (colon === -1) {
     throw new Error(
       `The credential at ${ref} is not a "username:password" pair, which basic auth requires. ` +
-        `Re-run: lanes link connect ${providerId}`,
+        `Connect "${providerId}" again for this profile and target.`,
     );
   }
 

package/src/connectivity/auth/index.ts

@@ -7,6 +7,10 @@
  * know the whole set: `resolve.ts` and `authorize.ts` for anything HTTP-shaped,
  * and `token.ts` for a transport that takes a bare token instead of a request.
  *
+ * `oauth-jwt/` is the one folder that is not a `kind`: it is a second way into
+ * a provider that already declares `oauth`, selected by the shape of what is
+ * stored rather than by the manifest. Its own README says why.
+ *
  * This is the axis the manifest's `auth:` block selects, and it is deliberately
  * independent of `../transports/` — which is why iCloud can speak IMAP with a
  * password while Gmail speaks HTTP with OAuth, and neither costs the other any
@@ -24,9 +28,19 @@ export {
   type OAuthProviderOptions,
 } from './oauth-authcode/provider.ts';
 export { resolveUpstreamToken } from './oauth-authcode/index.ts';
+export {
+  ASSERTION_GRANT,
+  clearMintedTokens,
+  isStoredAssertion,
+  resolveAssertionToken,
+  storedAssertionFor,
+  type StoredAssertion,
+} from './oauth-jwt/index.ts';
+export { assertionKeySchema, parseAssertionKey, signAssertion, type AssertionKey } from './oauth-jwt/key.ts';
 export {
   BROKER_ORIGIN_ENV,
   BROKERED,
+  PASTED,
   BrokerError,
   brokerConfig,
   brokerExchange,

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

@@ -20,6 +20,17 @@
  */
 export const BROKERED = 'broker';
 
+/**
+ * Stamped on a credential nobody here minted — the operator pasted it.
+ *
+ * The third answer, and the one that is not a client at all. It matters for the
+ * same reason as the other two and one more: a pasted token cannot be
+ * refreshed, cannot be attributed to a registration, and cannot be re-obtained
+ * by re-running a flow. `doctor` reads it to say so rather than offering a
+ * re-authorisation that would not apply.
+ */
+export const PASTED = 'pasted';
+
 /** What the broker will authorise, and whether it is currently doing so. */
 export interface BrokerConfig {
   readonly clientId: string;
@@ -27,6 +38,20 @@ export interface BrokerConfig {
   readonly scopesSupported: readonly string[];
   /** Added to every request so the exchange returns an identity assertion. */
   readonly identityScopes: readonly string[];
+  /**
+   * Where the vendor sends the browser back, when it will not send it here.
+   *
+   * Absent for a vendor that accepts a loopback redirect, which is all of them
+   * but Slack: the listener names itself and the broker is only asked to
+   * redeem. Present where the vendor demands HTTPS — then the redirect lands on
+   * the broker's own origin and is bounced down to the listener, and this is
+   * the URL both legs of the flow have to agree on.
+   *
+   * Published rather than derived, because which URL is correct depends on
+   * which deployment answered `/config` — and a broker running on loopback for
+   * a test would otherwise need a flag of its own.
+   */
+  readonly redirectUri: string | undefined;
   readonly open: boolean;
   /** Why it is closed, or near capacity. The broker's words, printed verbatim. */
   readonly notice: string | undefined;
@@ -217,6 +242,7 @@ export async function brokerConfig(
     clientId,
     scopesSupported: strings(data['scopes_supported']),
     identityScopes: strings(data['identity_scopes']),
+    redirectUri: str(data['redirect_uri']),
     open: data['status'] !== 'closed',
     notice: str(data['notice']),
     docsUrl: str(data['docs_url']),

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

@@ -1,6 +1,7 @@
 import { auth } from '@modelcontextprotocol/client';
 import type { ProviderManifest } from '#connectivity';
 import type { SecretStore } from '#secrets';
+import { resolveAssertionToken, storedAssertionFor } from '../oauth-jwt/index.ts';
 import { CredentialOAuthProvider, upstreamAccessToken } from './provider.ts';
 import { refreshDirectly } from './refresh.ts';
 
@@ -12,8 +13,11 @@ import { refreshDirectly } from './refresh.ts';
  * trip at connect time, a refresh on every use, and two different ways to run
  * that refresh depending on whether the provider has a metadata document.
  *
- * The other flows the credential-type list names — JWT bearer, client
- * credentials — are sibling folders that do not exist yet. See ../README.md.
+ * The other flows the credential-type list names — client credentials, SigV4 —
+ * are sibling folders that do not exist yet. See ../README.md. JWT bearer now
+ * does exist, in `../oauth-jwt/`, and is reached from here rather than from
+ * `resolve.ts`: a provider offering both declares one `auth.kind`, so the fork
+ * belongs at the point where the stored credential is first read.
  */
 
 export async function resolveUpstreamToken(
@@ -23,6 +27,16 @@ export async function resolveUpstreamToken(
 ): Promise<string | null> {
   if (manifest.auth.kind !== 'oauth') return null;
 
+  // Before anything is built, because the two arrangements share a ref and only
+  // what is stored there tells them apart. A `CredentialOAuthProvider` over an
+  // assertion pointer would find no `access_token`, conclude the connection was
+  // never authorised, and advise a browser flow the operator deliberately
+  // declined.
+  const assertion = await storedAssertionFor(manifest, connectionId, credentials);
+  if (assertion) {
+    return resolveAssertionToken({ manifest, connectionId, stored: assertion, credentials });
+  }
+
   const provider = new CredentialOAuthProvider({
     manifest,
     connectionId,

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

@@ -133,7 +133,7 @@ export class CredentialOAuthProvider {
     if (!this.#options.openBrowser) {
       throw new Error(
         `Connection ${this.#options.manifest.id}.${this.#options.connectionId} needs re-authorisation, ` +
-          `which requires a browser. Run: lanes link connect ${this.#options.manifest.id}.${this.#options.connectionId}`,
+          `which requires a browser. Connect ${this.#options.manifest.id}.${this.#options.connectionId} again for this profile and target.`,
       );
     }
     this.#options.openBrowser(authorizationUrl);

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

@@ -24,7 +24,7 @@ export async function refreshDirectly(
 
   if (!refreshToken) {
     throw new Error(
-      `No refresh token stored for ${manifest.id}. Run: lanes link connect ${manifest.id}`,
+      `No refresh token stored for ${manifest.id}. Connecting it again for this profile and target would store one.`,
     );
   }
 
@@ -72,7 +72,7 @@ async function viaBroker(
     const notice = cause instanceof BrokerError && cause.notice ? `\n${cause.notice}` : '';
     throw new Error(
       `The credential for ${manifest.id} could not be refreshed. ` +
-        `Re-authorise with: lanes link connect ${manifest.id}\n${String(
+        `Re-authorise ${manifest.id} for this profile and target.\n${String(
           cause instanceof Error ? cause.message : cause,
         ).slice(0, 200)}${notice}`,
     );
@@ -110,7 +110,7 @@ async function viaStoredClient(
     // is always the same, so say it rather than surfacing the raw grant error.
     throw new Error(
       `The credential for ${manifest.id} could not be refreshed (${response.status}). ` +
-        `Re-authorise with: lanes link connect ${manifest.id}\n${text.slice(0, 200)}`,
+        `Re-authorise ${manifest.id} for this profile and target.\n${text.slice(0, 200)}`,
     );
   }
 

package/src/connectivity/auth/oauth-jwt/README.md

@@ -0,0 +1,33 @@
+# OAuth 2.0 JWT bearer (RFC 7523)
+
+A key the operator holds, signed into a short-lived assertion and exchanged for
+an access token. No browser, and **no refresh token** — there is nothing to
+refresh, because a new assertion is signed whenever the last token ages out.
+That is the point: an authorization-code refresh token lives or dies by the
+issuer's policy, and a key does not.
+
+Not a `kind` of its own. It is declared as `auth.assertion` on an existing
+`oauth` block, because it is a second arrangement for the same provider rather
+than a different provider — so `credentialRefForConnection`, `setupRequirements`
+and the deploy grants all stay as they were. Which arrangement a connection uses
+is decided by the *shape* of what is stored at `<provider>/<connection>`:
+`isStoredAssertion` is that test, and `resolve.ts` asks it before building an
+authorization-code provider.
+
+| File | What it owns |
+|---|---|
+| `key.ts` | the key file's layout, PEM to DER, and the signed claim set — no I/O |
+| `index.ts` | reading the pointer, the exchange, the process-lifetime token cache |
+
+The endpoint comes from `token_uri` **inside the key file**, never from a
+constant here, which is what keeps this folder free of any vendor. A second
+vendor offering the same grant is a manifest and no code.
+
+## What it cannot do
+
+An assertion authenticates the key, and a key is not a person. It reaches only
+what has been shared with its address — unless the identity provider is
+configured to let it act as someone, which is an administrator's grant and not
+the operator's. `auth.assertion.delegation` says which of the two a provider is,
+and `cli/commands/connect/method.ts` is where that becomes a sentence someone
+reads before choosing.