@lanes-sh/link 0.2.2 → 0.3.1

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,27 @@ ${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
+  ${PROGRAM} sync targets --target t [--from gs://bucket] [--discover]
+                                 [--prefer local|remote] [--dry-run]
+                                 reconcile this workspace with the copy the
+                                 deployment reads; recovers a target a profile
+                                 has lost
+
+${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 +79,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
@@ -73,10 +94,13 @@ ${style.bold('Your own context')}
   ${PROGRAM} vault key generate         a fresh LANES_LINK_VAULT_KEY, printed once
 
 ${style.bold('Deploying')}
-  ${PROGRAM} deploy [--dry-run]         set up, build, and roll a revision
+  ${PROGRAM} deploy --target t [--dry-run]
+                                 set up, build, and roll one revision serving
+                                 every profile that declares the target
+  ${PROGRAM} deploy --target t --profile a --profile b
+                                 only these; the first owns the endpoint token
   ${PROGRAM} deploy --non-interactive   take the stored answers, never prompt
   ${PROGRAM} deploy --access iam|public who gets past the platform's own door
-  ${PROGRAM} deploy --target <name>     deploy a second one, under its own name
   ${PROGRAM} secrets list               credential references in this target
   ${PROGRAM} secrets set <ref>          store one value, read from stdin
   ${PROGRAM} secrets push --from local --to cloud
@@ -96,9 +120,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 +135,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.

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

@@ -0,0 +1,237 @@
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { credentialRefForConnection } from '../../manifest/credential-ref.ts';
+import { parseAssertionKey, signAssertion } from './key.ts';
+
+/**
+ * OAuth 2.0 JWT bearer (RFC 7523) — a key the operator holds, in place of a
+ * person approving a consent screen.
+ *
+ * The one property that earns this its own folder: there is no refresh token,
+ * because there is nothing to refresh. A fresh assertion is signed whenever the
+ * last access token ages out, so nothing an issuer can expire sits between the
+ * operator and their data. An authorization-code refresh token is subject to
+ * whatever policy the issuer applies to it — one such policy expires them after
+ * seven days, and re-approving a browser screen every week is the failure this
+ * folder exists to remove.
+ *
+ * What it costs is reach. An assertion authenticates the *key*, and a key is
+ * not a person: it holds only what has been shared with it, unless the identity
+ * provider has been configured to let it act as someone, which is an
+ * administrator's grant rather than the operator's. `auth.assertion.delegation`
+ * on the manifest is which of the two a provider is, and the CLI is where that
+ * becomes a sentence.
+ */
+
+/** RFC 7523's grant type, and the marker that identifies a stored credential as one. */
+export const ASSERTION_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+
+/**
+ * What a connection stores when it authenticates this way.
+ *
+ * A pointer and not the key itself. One key covers every provider of a vendor,
+ * so it lives at a profile-shared ref and each connection records where to find
+ * it plus the one thing that genuinely differs per connection — who it acts as.
+ * Copying the key into seven connections would mean seven things to rotate.
+ */
+export interface StoredAssertion {
+  readonly grant: typeof ASSERTION_GRANT;
+  readonly key_ref: string;
+  readonly subject?: string;
+}
+
+/**
+ * Whether a stored credential is one of these.
+ *
+ * Both methods write to the same ref — `<provider>/<connection>` — and this is
+ * what tells them apart. Shape rather than a flag in config, because
+ * `credentialResolver` is handed a registry and a store and never a connection
+ * row, so a declaration in config would be invisible exactly where the decision
+ * has to be made.
+ */
+export function isStoredAssertion(value: unknown): value is StoredAssertion {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { grant?: unknown }).grant === ASSERTION_GRANT &&
+    typeof (value as { key_ref?: unknown }).key_ref === 'string'
+  );
+}
+
+/**
+ * The stored credential for this connection, if it is an assertion pointer.
+ *
+ * `null` covers both "nothing stored" and "stored, but an authorization-code
+ * blob" — the caller wants the same thing in either case, which is to carry on
+ * down the path it was already on. Asked through `credentialRefForConnection`
+ * rather than by assembling the ref here, because two files deriving that
+ * separately is exactly the disagreement that function was extracted to end.
+ */
+export async function storedAssertionFor(
+  manifest: ProviderManifest,
+  connectionId: string,
+  credentials: SecretStore,
+): Promise<StoredAssertion | null> {
+  const ref = credentialRefForConnection(manifest, connectionId);
+  if (!ref) return null;
+
+  const raw = await credentials.get(ref);
+  if (!raw) return null;
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isStoredAssertion(parsed) ? parsed : null;
+  } catch {
+    // A credential that is not JSON at all is a pasted token, which is somebody
+    // else's case entirely. Not an error here.
+    return null;
+  }
+}
+
+/**
+ * Minted tokens, for as long as this process lives.
+ *
+ * In memory rather than in the store, and that is a deliberate difference from
+ * the authorization-code path. There, the refresh token is the credential and
+ * persisting the rotation is the whole point. Here the credential is the key,
+ * which nothing at request time modifies — so writing the token back would make
+ * this ref rotatable, which a deployed revision would then need write access to
+ * bind, to cache something that costs one signature and one POST to remake.
+ */
+const minted = new Map<string, { token: string; expiresAt: number }>();
+
+/** Re-mint slightly early: a token that expires mid-flight fails the call it was fetched for. */
+const EXPIRY_SKEW_MS = 60_000;
+
+/**
+ * Emptied when a reload lands, and by tests.
+ *
+ * The cache key is `<provider>.<connection>` with no subject in it, so a
+ * connection re-connected to act as somebody else — or re-connected to a route
+ * that is not this one at all — would otherwise keep serving the token minted
+ * for who it used to be, for up to an hour after the config said otherwise.
+ * `server/generations.ts` clears this beside `clearUpstreamTokens`, which
+ * exists for the same reason on the other path.
+ */
+export function clearMintedTokens(): void {
+  minted.clear();
+}
+
+interface TokenResponse {
+  readonly access_token?: string;
+  readonly expires_in?: number;
+  readonly error?: string;
+  readonly error_description?: string;
+}
+
+/**
+ * An access token for a connection that authenticates with a key.
+ *
+ * Reads the pointer, reads the key it names, signs, exchanges, caches. The
+ * manifest supplies the scopes and nothing else — where to exchange comes from
+ * the key file, so this stays a protocol implementation rather than a vendor's.
+ */
+export async function resolveAssertionToken(input: {
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly stored: StoredAssertion;
+  readonly credentials: SecretStore;
+  readonly fetch?: typeof globalThis.fetch;
+}): Promise<string> {
+  const { manifest, connectionId, stored, credentials } = input;
+  const cacheKey = `${manifest.id}.${connectionId}`;
+
+  const cached = minted.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now() + EXPIRY_SKEW_MS) return cached.token;
+
+  const raw = await credentials.get(stored.key_ref);
+  if (!raw) {
+    throw new Error(
+      `No key stored at ${stored.key_ref}, which ${manifest.id}.${connectionId} authenticates with. ` +
+        `Run: lanes link connect ${manifest.id} --replace`,
+    );
+  }
+
+  const key = parseAssertionKey(raw, stored.key_ref);
+  const scopes = manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [];
+
+  const assertion = await signAssertion({
+    key,
+    scopes,
+    ...(stored.subject ? { subject: stored.subject } : {}),
+  });
+
+  const response = await (input.fetch ?? globalThis.fetch)(key.token_uri, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ grant_type: ASSERTION_GRANT, assertion }),
+  });
+
+  const body = (await response.json().catch(() => ({}))) as TokenResponse;
+
+  if (!response.ok || !body.access_token) {
+    throw new Error(refusalMessage(manifest, stored, body, response.status));
+  }
+
+  minted.set(cacheKey, {
+    token: body.access_token,
+    expiresAt: Date.now() + (body.expires_in ?? 3600) * 1000,
+  });
+
+  return body.access_token;
+}
+
+/**
+ * Why the exchange was refused, in terms of what the operator can act on.
+ *
+ * Three of these are the whole population in practice and each has a different
+ * fix in a different console, so the raw `invalid_grant` is worth translating.
+ * An operator who reads only the error code goes looking in the wrong place —
+ * most often at the key, when the actual gap is a grant an administrator has
+ * not made yet.
+ */
+function refusalMessage(
+  manifest: ProviderManifest,
+  stored: StoredAssertion,
+  body: TokenResponse,
+  status: number,
+): string {
+  const detail = body.error_description ?? body.error ?? `HTTP ${status}`;
+  const scopes = manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [];
+
+  const lines = [`${manifest.name} refused the key at ${stored.key_ref}: ${detail}`];
+
+  if (body.error === 'unauthorized_client') {
+    lines.push(
+      '',
+      stored.subject
+        ? `  The key is not permitted to act as ${stored.subject}. An administrator of that` +
+            '\n  domain has to authorise this key for these scopes, all of them, exactly:'
+        : '  The key is not authorised for these scopes:',
+      ...scopes.map((scope) => `    ${scope}`),
+      '',
+      '  A partial list is refused the same way a missing one is.',
+    );
+  } else if (body.error === 'invalid_grant') {
+    // Listed rather than diagnosed. This one code covers an account that does
+    // not exist, a key that was deleted, a clock that is wrong, and a missing
+    // subject — and the description above is the only thing that distinguishes
+    // them. Asserting one of the four would send the reader to the wrong
+    // console three times in four, which is worse than naming all of them.
+    lines.push(
+      '',
+      '  The description above is the part that identifies which of these it is:',
+      '  - the account in the key no longer exists, or the key was deleted or disabled;',
+      "  - this machine's clock is wrong by more than a few minutes, and an assertion is",
+      '    signed with a timestamp;',
+      ...(stored.subject
+        ? [`  - ${stored.subject} is not an account the key may act as.`]
+        : [
+            '  - this account has to be reached by acting as someone, and this connection acts',
+            `    as nobody. Re-run and name one: lanes link connect ${manifest.id} --replace`,
+          ]),
+    );
+  }
+
+  return lines.join('\n');
+}