@lanes-sh/link 0.6.8 → 0.6.10

package/src/cli/commands/operate/desktop.ts

@@ -0,0 +1,220 @@
+import { ok, print, progress, style, warn } from '../../output.ts';
+import { confirm, isInteractive } from '../../prompt.ts';
+
+/**
+ * `lanes link desktop` — open the Lanes app, on its Lanes Link page.
+ *
+ * `lanes link dashboard` is the same command under its older name. That name
+ * used to mean a page this endpoint served at `/dashboard`, and ADR-053 retired
+ * it: the desktop app has a Lanes Link settings page that runs these same
+ * commands, so the served page was the second, weaker copy of one surface.
+ *
+ * It resolves no profile and opens no runtime, which is what lets it be `'none'`
+ * in `selection.ts` — nothing here depends on which profile or target you meant.
+ * The app holds its own selection, and a command that demanded two values it
+ * then discarded would only be asking out of habit.
+ */
+
+/**
+ * The scheme the released Lanes app registers with LaunchServices.
+ *
+ * `lanes-dev` and `lanes-stage` are separate builds registering separate
+ * schemes, so testing against either means naming it — see
+ * `LANES_LINK_APP_SCHEME` below.
+ */
+const SCHEME = 'lanes';
+
+/**
+ * The settings page id.
+ *
+ * A contract with another repository: it is `SETTINGS_PAGE_IDS` in the app's
+ * `src/settings/nav.ts`, and a test there pins this spelling precisely because
+ * renaming it would break this command with nothing on either side reporting a
+ * failure. The app opens Settings on its current page rather than refusing an
+ * id it does not have, so a mismatch degrades instead of dying — which also
+ * means it is invisible.
+ */
+const PAGE = 'integrations-link';
+
+/**
+ * How the app is installed, in the tap's own spelling.
+ *
+ * Homebrew rather than a download, for the same reason the app installs this
+ * CLI with `bun install -g` rather than sending someone to npm: an install a
+ * command performs has to be one an upgrade later finds. It is only ever
+ * reached on darwin, since the platform check turns everything else away first.
+ */
+const INSTALL = ['brew', 'install', '--cask', 'lanes-sh/lanes/lanes'] as const;
+
+/** Enough of the tail to explain an exit code, and no more. */
+const KEPT_STDERR = 4096;
+
+export interface DesktopFlags {
+  /** Print the URL instead of opening it. */
+  readonly print?: boolean | undefined;
+  /** Install without asking first. */
+  readonly yes?: boolean | undefined;
+}
+
+/** Injected in tests. Every field is the real thing when absent. */
+export interface DesktopDeps {
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly platform?: NodeJS.Platform | undefined;
+  /** Hand the URL to the OS. Resolves false when nothing claimed the scheme. */
+  readonly open?: ((url: string) => Promise<boolean>) | undefined;
+  /** Where `brew` is, or null. */
+  readonly brew?: (() => string | null) | undefined;
+  /** Run the install. Resolves an error tail, or null on success. */
+  readonly install?: ((brew: string) => Promise<string | null>) | undefined;
+  readonly interactive?: boolean | undefined;
+  readonly confirm?: ((question: string) => Promise<boolean>) | undefined;
+}
+
+/** The deep link, and the one env var that points it at another build. */
+export function settingsUrl(env: Record<string, string | undefined> = process.env): string {
+  // `||`, not `??`: an empty `LANES_LINK_APP_SCHEME` is someone unsetting it in
+  // a shell, and `://settings` is not a URL anything can open.
+  return `${env['LANES_LINK_APP_SCHEME'] || SCHEME}://settings?page=${PAGE}`;
+}
+
+/**
+ * Awaited, unlike `defaultOpenBrowser` in `oauth.ts`, and not the same function.
+ *
+ * That one is fire-and-forget because an OAuth consent has to outlive the
+ * command and `xdg-open` can block for as long as the browser it exec'd. This
+ * one runs on darwin only, where `open` hands off to LaunchServices and returns
+ * immediately — so the exit code is free, and it is the only thing that
+ * separates "the app is installed" from "nothing on this machine answers
+ * `lanes://`". Merging the two would give one of them the wrong behaviour.
+ */
+async function openUrl(url: string): Promise<boolean> {
+  try {
+    // An argument array, never a shell string: the URL carries a query.
+    const child = Bun.spawn(['open', url], { stdout: 'ignore', stderr: 'ignore' });
+    return (await child.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run the cask install, streaming it.
+ *
+ * Streamed rather than captured for the reason `runGcloud` is: a download of
+ * this size takes long enough that silence is indistinguishable from a hang.
+ * stderr is kept as well as shown, because "no such cask" and "the tap is
+ * unreachable" both exit 1 and need different answers.
+ */
+async function runInstall(brew: string): Promise<string | null> {
+  const child = Bun.spawn([brew, ...INSTALL.slice(1)], { stdout: 'inherit', stderr: 'pipe' });
+
+  let captured = '';
+  const decoder = new TextDecoder();
+  const reader = (child.stderr as ReadableStream<Uint8Array>).getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const text = decoder.decode(value, { stream: true });
+    process.stderr.write(text);
+    captured = (captured + text).slice(-KEPT_STDERR);
+  }
+
+  return (await child.exited) === 0 ? null : captured.trim();
+}
+
+/**
+ * Install the app, having established that nothing answers the scheme.
+ *
+ * It asks first. Everything else this CLI installs is a file in the workspace
+ * it already owns; this puts an application on the machine, which is the
+ * largest side effect any command here has and the one a person is most
+ * entitled to decline. `--yes` is for the run that already decided, and a
+ * pipe with no terminal is refused rather than assumed — the same split
+ * `knowledge use` makes (ADR-041).
+ */
+async function install(flags: DesktopFlags, deps: DesktopDeps): Promise<void> {
+  const line = INSTALL.join(' ');
+  const brew = (deps.brew ?? (() => Bun.which('brew')))();
+
+  if (!brew) {
+    // Nothing to offer: this is the one path where the command cannot finish
+    // the job, so it hands over the whole of it.
+    throw new Error(
+      'The Lanes app is not installed, and neither is Homebrew.\n' +
+        `  With Homebrew: ${line}\n` +
+        '  Without it, download the app: https://lanes.sh/desktop',
+    );
+  }
+
+  print(warn('the Lanes app is not installed'));
+  print(style.dim(`  ${line}`));
+
+  const interactive = deps.interactive ?? isInteractive();
+  if (!flags.yes) {
+    if (!interactive) {
+      // A script cannot answer, and installing an application because nobody
+      // was there to say no is the wrong way to resolve that.
+      throw new Error(
+        `Nothing here can answer a prompt. Run the line above, or pass --yes to install it.`,
+      );
+    }
+    if (!(await (deps.confirm ?? ((q: string) => confirm(q)))('Install it now?'))) {
+      throw new Error(`Not installed. When you want it: ${line}`);
+    }
+  }
+
+  progress(style.dim('  installing, which takes a minute the first time…'));
+  const failed = await (deps.install ?? runInstall)(brew);
+  if (failed !== null) {
+    throw new Error(`${line} failed.\n${failed || '  It printed nothing that explains why.'}`);
+  }
+  print(ok('installed Lanes'));
+}
+
+export async function desktop(flags: DesktopFlags, deps: DesktopDeps = {}): Promise<void> {
+  const url = settingsUrl(deps.env ?? process.env);
+
+  if (flags.print) {
+    // Alone on stdout, so `open "$(lanes link desktop --print)"` works. Unlike
+    // the URL this printed when it opened a served page, it carries no token
+    // and is the same string every time.
+    print(url);
+    return;
+  }
+
+  const platform = deps.platform ?? process.platform;
+  if (platform !== 'darwin') {
+    // The app is macOS-only; this CLI is not. Saying so beats spawning
+    // `xdg-open` at a scheme no Linux machine has ever registered.
+    throw new Error(
+      `The Lanes desktop app is macOS-only, and this is ${platform}.\n` +
+        `  What it would have opened: ${url}\n` +
+        '  Everything that page does is a command here — start with: lanes link status',
+    );
+  }
+
+  const open = deps.open ?? openUrl;
+  if (await open(url)) {
+    print(ok(`opened ${style.bold('Lanes')} → Settings → Integrations → Lanes Link`));
+    // The one failure this command cannot see. An older Lanes is still
+    // registered for `lanes://`, so `open` exits 0, and it then ignores an
+    // action it does not know — the app comes forward on whatever page it was
+    // already on. Not printed after an install below, where the version is
+    // whatever the tap just handed over.
+    print(style.dim('  needs Lanes 0.48.0 or newer; an older app ignores the link.'));
+    return;
+  }
+
+  await install(flags, deps);
+
+  if (!(await open(url))) {
+    // Installed, and the scheme still unclaimed. LaunchServices registers a
+    // cask's bundle as it lands, but not always before the next process asks.
+    throw new Error(
+      'Lanes is installed, but nothing answers a lanes:// link yet.\n' +
+        '  macOS registers the scheme a moment after the app lands. Try again: lanes link desktop',
+    );
+  }
+
+  print(ok(`opened ${style.bold('Lanes')} → Settings → Integrations → Lanes Link`));
+}

package/src/cli/commands/operate/findings.ts

@@ -1,53 +1,24 @@
 import { ownerPrincipal } from '#auth';
 import type { DiscoveredCapability } from '#connectivity';
-import { BROKERED } from '#connectivity/auth/index.ts';
 import { allowedConnections } from '#policy';
 import { toPolicyDocument } from '#registry';
 import { capabilityDiff, discoveryProbe } from '../../runtime/discovery.ts';
 import type { openRuntime } from '../../runtime.ts';
 
 /**
- * The two things `doctor` has to work out rather than simply read.
+ * The one thing `doctor` has to work out rather than simply read.
  *
  * Everything else in `inspect.ts` is a lookup — is the token there, does the
- * credential resolve, does the connection name a provider that exists — and
- * these two are analyses: one dates a credential from what the OAuth provider
- * stamped on it, and the other diffs what an upstream now offers against what
- * the endpoint is serving. They are the length in that file, and they are the
- * part that changes for reasons the gate order has nothing to do with.
- */
-
-/**
- * How old a stored OAuth credential is.
+ * connection name a provider that exists — and this is an analysis: it diffs
+ * what an upstream now offers against what the endpoint is serving. It is the
+ * length in that file, and it is the part that changes for reasons the gate
+ * order has nothing to do with.
  *
- * Derived from the `expires_at` the OAuth provider stamps when saving tokens.
- * Returns null for anything that is not a token blob — an app password has no
- * meaningful age, and guessing one would produce a confusing warning.
+ * `credentialAge` used to sit beside it and date a credential from the OAuth
+ * provider's stamp. It is gone: dating a credential answers "when did this last
+ * refresh", which is not the question anyone was asking. `operate/auth.ts`
+ * asks the real one by attempting the renewal.
  */
-export async function credentialAge(
-  credentials: { get(ref: string): Promise<string | null> },
-  ref: string,
-): Promise<{ days: number; brokered: boolean } | null> {
-  const raw = await credentials.get(ref);
-  if (!raw) return null;
-
-  try {
-    const parsed = JSON.parse(raw) as {
-      expires_at?: number;
-      expires_in?: number;
-      authorized_via?: string;
-    };
-    if (typeof parsed.expires_at !== 'number') return null;
-
-    const issued = parsed.expires_at - (parsed.expires_in ?? 3600) * 1000;
-    return {
-      days: Math.floor((Date.now() - issued) / 86_400_000),
-      brokered: parsed.authorized_via === BROKERED,
-    };
-  } catch {
-    return null;
-  }
-}
 
 /**
  * Capabilities the upstream has grown since you connected.

package/src/cli/commands/operate/inspect.ts

@@ -1,11 +1,12 @@
-import { credentialRefFor, formatPlan, planIsNoop, planReconcile } from '#registry';
+import { formatPlan, planIsNoop, planReconcile } from '#registry';
 import { DEFAULT_SURFACES } from '../../config-repair.ts';
 import { announce, announceProfile, emit, fail, ok, print, warn } from '../../output.ts';
 import { staleNudge } from '../../release.ts';
 import { openRuntime, resolveProfileOnly, type GlobalFlags, type Runtime } from '../../runtime.ts';
 import type { FetchLike } from '#deployments/knowledge.ts';
 import { unboundRotatableRefs } from '#deployments/bind.ts';
-import { credentialAge, reportCapabilityDrift } from './findings.ts';
+import { reportCapabilityDrift } from './findings.ts';
+import { probeConnections } from './auth.ts';
 import { migratedContract, migratedRenamedProviders } from './migrate.ts';
 
 /**
@@ -65,7 +66,16 @@ export interface DoctorFinding {
   readonly fix?: string;
 }
 
-/** Read-only external checks: credentials resolve, stores reachable. */
+/**
+ * External checks: credentials still authenticate, stores reachable.
+ *
+ * Not read-only, and that changed when the credential check stopped guessing
+ * from a stored date and started attempting the renewal. A refresh that
+ * succeeds persists the new token, which on a deployed target is a secret-store
+ * write. It is the same write serving a request makes, and it warms the token
+ * for the next real call — but `check` and `plan` above are still the two that
+ * touch nothing.
+ */
 export async function doctor(flags: DoctorFlags): Promise<void> {
   // The one check that cannot use a runtime, because it answers for the profiles
   // that cannot open one. A provider rename left in the config refuses at load,
@@ -108,47 +118,56 @@ export async function doctor(flags: DoctorFlags): Promise<void> {
       });
     }
 
-    for (const connection of runtime.config.connections) {
-      const key = `${connection.provider}.${connection.id}`;
-      const ref = credentialRefFor(connection, runtime.manifestFor(connection.provider));
-      if (!ref) {
-        checks.push(`${key} needs no credential`);
-        continue;
-      }
-      if (await runtime.credentials.has(ref)) {
-        const staleness = await credentialAge(runtime.credentials, ref);
+    // Whether each credential still works, asked rather than dated.
+    //
+    // This used to warn from the *age* of a stored credential, on the theory
+    // that a Google app left in "Testing" expires refresh tokens at seven days.
+    // The heuristic was wrong in both directions — it dated a credential from
+    // its last refresh, so an untouched healthy connection read as stale and a
+    // grant revoked an hour ago read as fresh — and its own guard made it worse:
+    // it skipped brokered credentials because "the hosted client is in
+    // production", which `providers/google/shared/oauth.ts` now says outright is
+    // not so. The hosted client is under review and carries the same weekly
+    // expiry, so the warning was silenced for exactly the population that has
+    // the problem.
+    //
+    // `probeConnections` answers it by attempting the renewal, which is the only
+    // thing that actually knows. Same classifier as `lanes link auth`, so the two
+    // cannot drift apart again.
+    const probed = await probeConnections(runtime, runtime.config.connections, forSelection);
 
-        // A Google project left in "Testing" expires refresh tokens after seven
-        // days. That is a policy setting rather than a fault, but it presents
-        // as an authentication failure mid-task — so say it before the call
-        // fails rather than after.
-        //
-        // Only for a client the operator registered. The hosted one is in
-        // production and does not expire refresh tokens weekly, so this warning
-        // would simply be false there — and a warning that is wrong once is a
-        // warning that gets scrolled past every time after.
-        if (staleness !== null && !staleness.brokered && staleness.days >= 7) {
+    for (const result of probed) {
+      switch (result.verdict) {
+        case 'reauth':
           warnings.push({
-            kind: 'stale_credential',
-            key,
+            kind: 'needs_reauth',
+            key: result.key,
             message:
-              `${key} credential is ${staleness.days} days old — a Google app in "Testing" expires at 7. ` +
-              `Run: lanes link connect ${key}`,
-            fix: forSelection(`lanes link connect ${key}`),
+              `${result.key} is signed out and cannot renew itself — run: lanes link connect ${result.key}` +
+              (result.detail ? `\n      ${result.detail}` : ''),
+            fix: forSelection(`lanes link connect ${result.key}`),
           });
-        } else {
-          const age = staleness
-            ? ` (${staleness.days}d old${staleness.brokered ? ', hosted client' : ''})`
-            : '';
-          checks.push(`${key} credential resolves${age}`);
-        }
-      } else {
-        problems.push({
-          kind: 'missing_credential',
-          key,
-          message: `${key} has no stored credential — run: lanes link connect ${key}`,
-          fix: forSelection(`lanes link connect ${key}`),
-        });
+          break;
+        case 'missing':
+          problems.push({
+            kind: 'missing_credential',
+            key: result.key,
+            message: `${result.key} has no stored credential — run: lanes link connect ${result.key}`,
+            fix: forSelection(`lanes link connect ${result.key}`),
+          });
+          break;
+        case 'none':
+          checks.push(`${result.key} needs no credential`);
+          break;
+        case 'unknown':
+          warnings.push({
+            kind: 'auth_uncheckable',
+            key: result.key,
+            message: `${result.key} could not be checked${result.detail ? `: ${result.detail}` : ''}`,
+          });
+          break;
+        default:
+          checks.push(`${result.key} credential resolves`);
       }
     }
 

package/src/cli/commands/operate/serve.ts

@@ -45,9 +45,6 @@ export async function start(
     port: flags.port,
     only: flags.only,
     mintToken: true,
-    // Local, so there is a browser and a person at it. `container.ts` does not
-    // pass this — see `#server/dashboard.ts`.
-    dashboard: true,
     // Stderr, not stdout: `--json` and `--raw` callers parse the other stream.
     // A refused credential is the event worth seeing while this runs in the
     // foreground, and until now nothing printed it.

package/src/cli/commands/operate.ts

@@ -2,13 +2,14 @@
  * Running an instance and looking at it — everything that is neither
  * `connect` nor the owner layer.
  *
- * Seven files, one per verb group, because every private helper here served
+ * Eight files, one per verb group, because every private helper here served
  * exactly one command and nothing crossed between them:
  *
  *   inspect.ts   check, plan, doctor — the gate order, cheapest failure first
+ *   auth.ts      whether each connection can still authenticate, by asking
  *   status.ts    connections, reachable capabilities, endpoint
  *   outputs.ts   what an agent harness needs, and proving the short form works
- *   dashboard.ts opening the page a local endpoint serves, with the key it needs
+ *   desktop.ts   opening the Lanes app, on the page that drives this CLI
  *   serve.ts     start
  *   audit.ts     audit tail and verify, and the Markdown rendering of tail
  *   token.ts     token show, token rotate
@@ -19,11 +20,12 @@
  */
 
 export { check, doctor, plan } from './operate/inspect.ts';
+export { auth, classifyOAuth, type AuthFlags, type AuthVerdict, type ConnectionAuth } from './operate/auth.ts';
 export { status } from './operate/status.ts';
 export { outputs, type OutputsFlags } from './operate/outputs.ts';
 export { tools, type ToolsFlags } from './operate/tools.ts';
 export { start } from './operate/serve.ts';
-export { dashboard, type DashboardFlags } from './operate/dashboard.ts';
+export { desktop, settingsUrl, type DesktopFlags } from './operate/desktop.ts';
 export { auditTail, auditVerify, markdownCell } from './operate/audit.ts';
 export { attachFile } from './operate/attach.ts';
 export { tokenRotate, tokenShow } from './operate/token.ts';

package/src/cli/main.ts

@@ -5,9 +5,10 @@ import {
   attachFile,
   auditTail,
   auditVerify,
+  auth,
   check,
   configShow,
-  dashboard,
+  desktop,
   doctor,
   outputs,
   plan,
@@ -282,6 +283,11 @@ export async function run(argv: readonly string[]): Promise<void> {
       return plan(global);
     case 'doctor':
       return doctor({ ...global, json, fix: flags['fix'] === true });
+
+    // Beside `doctor` because it answers half of what `doctor` used to guess at,
+    // and answers it by asking rather than by dating a credential.
+    case 'auth':
+      return auth({ ...global, json, connection: text(flags, 'connection') });
     case 'status':
       return status({ ...global, json });
     case 'outputs':
@@ -289,10 +295,19 @@ export async function run(argv: readonly string[]): Promise<void> {
 
     // Beside `outputs` for the same reason `tools` is: it answers the next
     // question a person has rather than the next one an agent has. `outputs`
-    // hands a harness a URL and a token; this opens the one page a person can
-    // read, and only a local endpoint serves it.
+    // hands a harness a URL and a token; this opens the app a person drives all
+    // of this from.
+    //
+    // Two spellings, one behaviour, as `skill` is for `mcp skill`. `dashboard`
+    // is what this was called when it opened a page the endpoint served, and
+    // that name is in a year of notes; `desktop` is what it does now (ADR-053).
+    // Both are in `USAGE`, unlike the `skill` alias, because nobody has learned
+    // the new one yet.
+    //
+    // No `...global`: this resolves nothing, so there is nothing to select.
     case 'dashboard':
-      return dashboard({ ...global, print: flags['print'] === true });
+    case 'desktop':
+      return desktop({ print: flags['print'] === true, yes: flags['yes'] === true });
 
     // Beside `outputs` because it answers the next question. `outputs` says
     // where the endpoint is; this says what it would hand a client that asked

package/src/cli/selection.ts

@@ -129,13 +129,18 @@ export const SELECTION: Record<string, Requires> = {
   secrets: 'profile+target',
   plan: 'profile+target',
   doctor: 'profile+target',
+  auth: 'profile+target',
   // Target-scoped: see the note above. `--profile` narrows each to one profile.
   status: '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',
+  // It resolves nothing and opens nothing — it hands macOS a URL (ADR-053).
+  // `target list` is the precedent for a `'none'` command that still takes a
+  // flag of its own. Both spellings need a row: `selection.test.ts` reads
+  // `main.ts` for `case` labels, and a label with no row here falls through to
+  // the `profile+target` default.
+  dashboard: 'none',
+  desktop: 'none',
   attach: 'profile+target',
   start: 'profile+target',
   deploy: 'target',
@@ -267,6 +272,9 @@ const ACCEPTS: Record<string, readonly string[]> = {
   // it undoes a provider rename this project shipped, and every other finding
   // there is something only the operator can decide.
   doctor: ['fix'],
+  // A filter, not a second subject: it narrows the answer to one connection so
+  // a caller can re-ask about the row it just repaired. Same shape as `attach`.
+  auth: ['connection'],
   relabel: [],
   'target list': ['urls', 'target'],
   'target show': ['target'],
@@ -281,7 +289,10 @@ const ACCEPTS: Record<string, readonly string[]> = {
   'mcp add': ['name', 'scope', 'token-env', 'dry-run', 'force', 'no-skill'],
   'mcp skill': ['print', 'force'],
   'mcp list': ['name', 'scope'],
-  dashboard: ['print'],
+  // `--yes` because it installs the app when nothing answers the scheme, and
+  // that is the one prompt in this CLI that puts an application on the machine.
+  dashboard: ['print', 'yes'],
+  desktop: ['print', 'yes'],
   skill: ['print', 'force'],
   deploy: ['dry-run', 'iam', 'access', 'service-account', 'tag', 'yes', 'non-interactive'],
   'secrets push': ['from', 'to', 'overwrite', 'dry-run'],

package/src/cli/usage.ts

@@ -37,7 +37,9 @@ ${style.bold('Everyday')}
                                         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} desktop [--print] [--yes]  open the Lanes app on its Lanes Link page,
+                                        installing it first if it is not there
+  ${PROGRAM} dashboard                  the older spelling of the line above
   ${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
@@ -129,6 +131,8 @@ ${style.bold('Inspection')}
   ${PROGRAM} doctor [--json]            credentials resolve, stores reachable
   ${PROGRAM} doctor --fix               apply a repair it can make itself, such as
                                         a provider this project renamed under you
+  ${PROGRAM} auth [--json]              whether each connection can still sign in
+  ${PROGRAM} auth --connection <key>    just this one
   ${PROGRAM} tools [--json]             what the endpoint advertises to a client
   ${PROGRAM} plan                       what reconcile would change
   ${PROGRAM} audit tail [--limit N] [--denied-only] [--format md]

package/src/connectivity/auth/index.ts

@@ -19,6 +19,7 @@
 
 export { credentialResolver, type ResolvedCredential } from './resolve.ts';
 export { requestAuthorizer } from './authorize.ts';
+export { ReauthRequired, statusMeansGrantIsDead } from './reauth.ts';
 export { basicCredential } from './basic/index.ts';
 export { bearerToken, bearerTokenAsStored } from './token.ts';
 export {

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

@@ -1,5 +1,6 @@
 import type { SecretStore } from '#secrets';
 import type { ProviderManifest } from '#connectivity';
+import { ReauthRequired } from '../reauth.ts';
 
 /**
  * The SDK's `OAuthClientProvider`, backed by our `SecretStore`.
@@ -69,6 +70,20 @@ export class CredentialOAuthProvider {
     return `${this.#options.manifest.id}/${this.#options.connectionId}`;
   }
 
+  /**
+   * Which connection this provider speaks for, as `provider.id`.
+   *
+   * Public because a refusal has to name it: `refresh.ts` builds the same key
+   * for a `ReauthRequired`, and a caller holding several connections needs to
+   * know which one to send someone to rather than parsing it back out of a
+   * sentence. Note the separator differs from `#tokensRef` on purpose — that
+   * one is a credential ref (`gmail/main`), this one is the addressing form
+   * (`gmail.main`).
+   */
+  get connectionId(): string {
+    return this.#options.connectionId;
+  }
+
   // --- OAuthClientProvider ----------------------------------------------
 
   get redirectUrl(): string | undefined {
@@ -131,7 +146,8 @@ export class CredentialOAuthProvider {
 
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
     if (!this.#options.openBrowser) {
-      throw new Error(
+      throw new ReauthRequired(
+        `${this.#options.manifest.id}.${this.#options.connectionId}`,
         `Connection ${this.#options.manifest.id}.${this.#options.connectionId} needs re-authorisation, ` +
           `which requires a browser. Connect ${this.#options.manifest.id}.${this.#options.connectionId} again for this profile and target.`,
       );