@lanes-sh/link 0.2.2 → 0.3.0

package/src/cli/callback-page.ts

@@ -1,32 +1,33 @@
 /**
- * The page the browser lands on when a connect flow ends.
+ * The two pages a browser reaches on its way through an authorization.
  *
- * It is the only HTML this repository serves to a human, and for a few seconds
- * it is the whole product — so it is the product's own page rather than a
- * bespoke one. The design is lifted from the pages the Lanes API serves after
- * someone authorises something (the workspace invite and the email
- * verification): an outline-only card, a Lora heading, native text softened
- * with opacity, and the shared one-row footer.
+ * `approvalPage` is the consent screen a remote MCP client stops at;
+ * `completionPage` is where a provider connect flow lands. For a few seconds
+ * each of them is the whole product, so both are the product's own page: the
+ * dashed card, the Lora heading, and the shared one-row footer that the Lanes
+ * API serves after a workspace invite or an email verification.
  *
- * Two decisions are worth keeping:
+ * Everything visual now comes from `brand.ts`. Two decisions this file used to
+ * record have been settled the other way by the design system, and are worth
+ * naming because both look like regressions otherwise:
  *
- * - **Nothing is painted.** `color-scheme: light dark` plus a transparent
- *   background means the browser supplies its own canvas, so the page is
- *   correct in either mode without a theme switch, a media query per colour, or
- *   a preference to read. It replaced a hardcoded `#0d1117`, which was a black
- *   rectangle on a light machine.
- * - **Colour is reserved for status.** Not for emphasis, and not for the
- *   heading — a green *word* said nothing the word "Connected" did not, and
- *   that is why it went. A check is different: it is the glyph the Lanes app
- *   already puts against a connected integration, so a reader arriving from the
- *   app meets the mark they left it with. Both outcomes carry one now, the
- *   check on success and the red heading on failure, and nothing else does.
+ * - **The canvas is painted.** This used to be transparent under
+ *   `color-scheme: light dark`, so the browser supplied its own — a fix for a
+ *   hardcoded `#0d1117` that read as a black rectangle on a light machine. The
+ *   system names a background per mode, so the fix is now to paint the right
+ *   one. `color-scheme` stays, for form controls and scrollbars.
+ * - **The success mark is gold, not green.** It was lucide's `check` at
+ *   `#059669`, chosen to match the tick the Lanes app puts against a connected
+ *   integration. The design system is explicit that gold is the only accent and
+ *   "gold for positive, neutral tokens otherwise", so the green was the odd one
+ *   out rather than the match it was meant to be.
  *
- * Lora is fetched from Google Fonts, as the API pages do; the fallback stack
- * carries the page on a machine with no network, which is the state a failed
- * authorisation is sometimes in.
+ * What has not changed is that colour is reserved for status and spent nowhere
+ * else — not on emphasis, and not on the heading.
  */
 
+import { escapeHtml, FONTS, FOOTER, PAGE_CSP, PAGE_HEADERS, TOKENS } from './brand.ts';
+
 export interface CallbackPage {
   /** The focal line, set in Lora. A provider name, or the outcome itself. */
   readonly heading: string;
@@ -38,69 +39,29 @@ export interface CallbackPage {
 }
 
 /**
- * Escape text for an HTML body.
- *
- * `escapeXml` in `connectivity/transports/dav/xml.ts` would do, and `cli` is
- * allowed to import `connectivity` — but a page renderer reaching into a DAV
- * transport for a string function is a dependency nobody would defend. Five
- * lines is cheaper than the coupling.
- *
- * This is load-bearing: `heading` carries a provider's `manifest.name`, and a
- * custom provider supplies that from a YAML file of its own.
- */
-function escapeHtml(value: string): string {
-  return value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-}
-
-/**
- * Harmonised with the Lanes API's public pages, which are themselves harmonised
- * with the transactional emails — same dashed card, same Lora, same footer, so
- * the end of a connect flow reads as the same product as the invite that
- * preceded it.
+ * The card, centred. Everything else is `brand.ts`.
  */
 const STYLE = `
-:root { color-scheme: light dark; }
-* { box-sizing: border-box; }
-body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-       display: flex; align-items: center; justify-content: center;
-       min-height: 100vh; margin: 0; background: transparent; padding: 24px; }
+body { display: flex; align-items: center; justify-content: center;
+       min-height: 100vh; padding: 24px; }
 .wrap { width: 100%; max-width: 460px; text-align: center; }
-.card { background: transparent; border: 1px dashed rgba(120,113,108,0.35); border-radius: 10px;
-        padding: 48px 36px; }
-.label { margin: 0 0 6px; font-size: 15px; font-weight: 500; letter-spacing: 0.01em; opacity: 0.6; }
-h1 { font-family: "Lora", Georgia, "Times New Roman", serif; font-size: 28px; font-weight: 500;
-     letter-spacing: -0.01em; line-height: 1.3; margin: 0 0 18px; }
-.detail { margin: 0; font-size: 15px; line-height: 1.6; opacity: 0.75; }
-.icon { display: block; margin: 0 auto 18px; color: #059669; }
-.footer { margin: 24px 0 0; }
-.footer p { margin: 0; font-size: 12px; line-height: 1.5; opacity: 0.5; }
-.footer a { color: inherit; text-decoration: underline; }
-.err h1 { color: #A06060; }
-@media (prefers-color-scheme: dark) {
-  .err h1 { color: #C08080; }
-  .icon { color: #34D399; }
-}
+.card { padding: 48px 36px; }
+.label { margin: 0 0 6px; font-size: 15px; font-weight: 500; color: var(--muted-foreground); }
+h1 { margin: 0 0 18px; }
+.detail { margin: 0; font-size: 15px; line-height: 1.6; color: var(--muted-foreground); }
+.icon { display: block; margin: 0 auto 18px; color: var(--accent-gold); }
+.err h1 { color: var(--destructive); }
 `.trim();
 
-/** The one-row footer below the card, identical to the one the API pages carry. */
-const FOOTER =
-  '<div class="footer"><p>Your unfair advantage in parallel AI coding. ' +
-  '<a href="https://lanes.sh/">lanes.sh</a></p></div>';
-
 /**
  * The success mark, above the label.
  *
- * The glyph and the emerald are the Lanes app's, so a connected provider looks
- * the same wherever it is reported — lucide's `check` at #059669, lightened to
- * #34D399 on a dark canvas because the darker green does not survive it.
+ * lucide's `check`, in `--accent-gold` — which is what "gold for positive"
+ * means when the positive thing is a connection that now works. It carries no
+ * colour of its own; `.icon` sets it, so it follows the token if the token moves.
  *
- * `aria-hidden` because the word underneath is the announcement; a screen
- * reader hearing "Connected" does not also need to hear about a tick.
+ * `aria-hidden` because the word underneath is the announcement; a screen reader
+ * hearing "Connected" does not also need to hear about a tick.
  */
 const ICON =
   '<svg class="icon" xmlns="http://www.w3.org/2000/svg" width="28" height="28" ' +
@@ -158,49 +119,70 @@ ${hidden}
 <input class="field" type="password" name="token" placeholder="Endpoint token" autocomplete="off" autofocus required>
 <button class="go" type="submit">Approve</button>
 </form>
-<p class="detail small">Printed by <code>lanes link outputs --show --target ${escapeHtml(page.target)}</code>.</p>`;
+<p class="small"><code>lanes link outputs --show --target ${escapeHtml(page.target)}</code></p>`;
 
-  return page.retry ? shell(body, 'Authorise', 401) : shell(body, 'Authorise', 200);
+  return shell(body, 'Authorise', page.retry ? 401 : 200, '', SUBMIT_SPINNER);
 }
 
-function shell(inner: string, title: string, status: number): Response {
+/**
+ * What runs while the approval is in flight.
+ *
+ * Approving is a round trip to an authorization server, and until it returns the
+ * page looks exactly as it did before the click — so the honest reading is that
+ * nothing happened, and the second click is the one that produces a duplicated
+ * request. The button disables itself, which is the part that matters; the
+ * spinner is what says why.
+ *
+ * The cost is real and worth naming: this is the one page that asks for the
+ * endpoint token, and an inline listener means its policy admits inline script.
+ * It is the minimum that does the job — one listener, no interpolation, nothing
+ * read from the page — and the alternative, a static file, is an asset pipeline
+ * this repository does not have.
+ */
+const SUBMIT_SPINNER = `
+document.querySelector('form').addEventListener('submit', function (event) {
+  var button = event.currentTarget.querySelector('.go');
+  button.classList.add('busy');
+  button.disabled = true;
+});
+`.trim();
+
+function shell(
+  inner: string,
+  title: string,
+  status: number,
+  cardClass = '',
+  script = '',
+): Response {
   return new Response(
     `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<link rel="preconnect" href="https://fonts.googleapis.com">
-<link href="https://fonts.googleapis.com/css2?family=Lora:wght@400;500&amp;display=swap" rel="stylesheet">
+${FONTS}
 <title>${escapeHtml(title)}</title>
 <style>
+${TOKENS}
 ${STYLE}
 ${FORM_STYLE}
 </style>
 </head>
 <body>
 <div class="wrap">
-<div class="card">
+<div class="card surface${cardClass}">
 ${inner}
 </div>
 ${FOOTER}
 </div>
+${script ? `<script>\n${script}\n</script>` : ''}
 </body>
 </html>`,
     {
       status,
       headers: {
-        'content-type': 'text/html; charset=utf-8',
-        // One of these pages asks for the endpoint token in a password field.
-        // Framing it is the cheap half of a UI-redress attack, and nothing here
-        // is ever meant to be embedded — so refuse it in both spellings, since
-        // `frame-ancestors` is the one that is actually specified and
-        // `X-Frame-Options` is the one older browsers obey.
-        'content-security-policy': "frame-ancestors 'none'",
-        'x-frame-options': 'DENY',
-        // The URL carries a `client_id` and a `redirect_uri`; neither belongs in
-        // a Referer sent to whatever the page links out to.
-        'referrer-policy': 'no-referrer',
+        ...PAGE_HEADERS,
+        ...(script ? { 'content-security-policy': `${PAGE_CSP}; script-src 'unsafe-inline'` } : {}),
       },
     },
   );
@@ -208,17 +190,30 @@ ${FOOTER}
 
 const FORM_STYLE = `
 .field { width: 100%; margin: 20px 0 12px; padding: 11px 13px; font: inherit; font-size: 15px;
-         color: inherit; background: transparent; border: 1px solid rgba(120,113,108,0.45);
-         border-radius: 7px; }
-.field:focus { outline: none; border-color: rgba(120,113,108,0.9); }
+         color: inherit; background: var(--background); border: 1px solid var(--border);
+         border-radius: 6px; }
+.field:focus { outline: none; border-color: var(--accent-gold); }
 .go { width: 100%; padding: 11px 13px; font: inherit; font-size: 15px; font-weight: 500;
-      color: inherit; background: transparent; border: 1px solid rgba(120,113,108,0.55);
-      border-radius: 7px; cursor: pointer; }
-.go:hover { border-color: rgba(120,113,108,0.95); }
-.small { margin-top: 14px; font-size: 12px; opacity: 0.55; }
+      color: var(--foreground); background: transparent; border: 1px solid var(--border);
+      border-radius: 6px; cursor: pointer; }
+.go:hover { background: var(--muted); }
+.small { margin-top: 16px; font-size: 12px; color: var(--muted-foreground); opacity: 0.8; }
 .small code { font-size: 12px; }
-.err-text { color: #A06060; opacity: 1; }
-@media (prefers-color-scheme: dark) { .err-text { color: #C08080; } }
+.err-text { color: var(--destructive); }
+
+/* The button, mid-flight. The label goes transparent rather than away, so the
+   button keeps the width it had and the card does not reflow under the cursor. */
+.go.busy { color: transparent; position: relative; pointer-events: none; }
+.go.busy::after { content: ''; position: absolute; inset: 0; margin: auto;
+                  width: 15px; height: 15px; border-radius: 50%;
+                  border: 2px solid var(--border); border-top-color: var(--foreground);
+                  animation: spin 0.6s linear infinite; }
+@keyframes spin { to { transform: rotate(360deg); } }
+/* Monochrome deliberately: gold says a thing turned out well, and a request in
+   flight has not turned out yet. */
+@media (prefers-reduced-motion: reduce) {
+  .go.busy::after { animation-duration: 2.4s; }
+}
 `.trim();
 
 export function completionPage(page: CallbackPage): Response {
@@ -226,31 +221,16 @@ export function completionPage(page: CallbackPage): Response {
 
   // The tab strip truncates to a few characters, and the word that has to
   // survive that is the outcome — not the name of what was connected.
-  const title = escapeHtml(label ?? heading);
+  const title = label ?? heading;
 
-  return new Response(
-    `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<link rel="preconnect" href="https://fonts.googleapis.com">
-<link href="https://fonts.googleapis.com/css2?family=Lora:wght@400;500&amp;display=swap" rel="stylesheet">
-<title>${title}</title>
-<style>
-${STYLE}
-</style>
-</head>
-<body>
-<div class="wrap">
-<div class="card${ok ? '' : ' err'}">
-${ok ? `${ICON}\n` : ''}${label ? `<p class="label">${escapeHtml(label)}</p>\n` : ''}<h1>${escapeHtml(heading)}</h1>
-<p class="detail">${escapeHtml(detail)}</p>
-</div>
-${FOOTER}
-</div>
-</body>
-</html>`,
-    { status: ok ? 200 : 400, headers: { 'content-type': 'text/html; charset=utf-8' } },
-  );
+  const body =
+    `${ok ? `${ICON}\n` : ''}` +
+    `${label ? `<p class="label">${escapeHtml(label)}</p>\n` : ''}` +
+    `<h1>${escapeHtml(heading)}</h1>` +
+    `<p class="detail">${escapeHtml(detail)}</p>`;
+
+  // Through the same shell as the consent screen, rather than a second copy of
+  // the document. They were already meant to be one page; only the error class
+  // on the card differs.
+  return shell(body, title, ok ? 200 : 400, ok ? '' : ' err');
 }

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

@@ -92,3 +92,8 @@ export async function moveCredential(
   await credentials.set(to, value);
   await credentials.delete(from);
 }
+
+/** What a spec that named an account rather than a provider turned out to mean. */
+export function familyNote(providerId: string, family: readonly string[]): string {
+  return `${providerId} is ${family.length} services on one account: ${family.join(', ')}`;
+}

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

@@ -0,0 +1,187 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { ASSERTION_GRANT, parseAssertionKey } from '#connectivity/auth/index.ts';
+import { credentialRefForConnection, type AuthAssertion, type ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { ok, progress, style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { askForSetup, printSetup } from './setup.ts';
+
+/**
+ * The counterpart to `authorise.ts`, for a provider authenticated by a key.
+ *
+ * The same conversation, minus the browser: show the console work, take what it
+ * produced, put it in the store. What differs is that there are two halves and
+ * they have different lifetimes — the key is one file covering every provider
+ * of a vendor, and the account it acts as is per connection. So the key is
+ * asked for once per profile and the subject once per account, and re-running
+ * `connect` for a second provider asks for neither.
+ */
+
+/**
+ * Take a path, or the file's contents.
+ *
+ * A key arrives as a downloaded file, and a downloaded file is a path — asking
+ * someone to open it and paste several hundred characters of PEM into a
+ * terminal is asking for a truncated key and an error two steps later. Pasting
+ * still works for anyone who would rather, which is why this looks at the shape
+ * of the answer rather than at a flag.
+ *
+ * What is *stored* is always the contents. A path is a fact about one machine
+ * and this credential outlives it: the same profile is read by a deployed
+ * revision that has no such file, and a store holding a path would fail there
+ * with an error about the filesystem rather than about the credential.
+ */
+async function contentsOf(answer: string): Promise<string> {
+  if (answer.startsWith('{')) return answer;
+
+  const expanded = answer.startsWith('~/') ? resolve(homedir(), answer.slice(2)) : answer;
+  const path = isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded);
+
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    throw new Error(
+      `No file at ${path}. Give the path to the key the console downloaded, or paste its contents.`,
+    );
+  }
+}
+
+/**
+ * Ensure the profile holds the key, and this connection holds a pointer to it.
+ *
+ * Idempotent on the key for the same reason `ensureStaticCredential` is: seven
+ * providers share one file, and the second `connect` must find it already there
+ * and say so rather than asking again. The subject is not idempotent in the
+ * same way — it is per connection, and every connection is a first one.
+ */
+export async function authoriseWithKey(input: {
+  readonly manifest: ProviderManifest;
+  readonly assertion: AuthAssertion;
+  readonly connectionId: string;
+  readonly credentials: SecretStore;
+  readonly changes: string[];
+  /** The operator asked to be asked again — a rotated key, or the wrong account. */
+  readonly replace: boolean;
+  readonly prompter?: Prompter;
+}): Promise<void> {
+  const { manifest, assertion, connectionId, credentials, changes, replace } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+
+  const keyPrompt = assertion.setup.prompts.find((prompt) => prompt.scope === 'shared');
+  if (!keyPrompt) {
+    throw new Error(
+      `Provider "${manifest.id}" declares auth.assertion with no shared prompt, so there is no key to ask for.`,
+    );
+  }
+
+  const stored = await credentials.has(assertion.key_ref);
+
+  // `stored && !replace`, and deliberately not `reuseStoredCredential` — which
+  // also asks whether the connection id is still provisional. That question is
+  // right for a per-connection credential, where a provisional id means an
+  // earlier connect stored something no server ever accepted. It is wrong here:
+  // this key is shared across the whole profile, so a *first* connect of a
+  // second provider is provisional by definition while the key it finds was
+  // stored deliberately and may already be in use. Asking again there made a
+  // stored key unusable — the preflight said it had everything it needed, and
+  // the run that followed immediately asked for it.
+  if (stored && !replace) {
+    // The walkthrough still prints. The key is shared and already held, but the
+    // *sharing* is per resource and per product: whoever connects Sheets after
+    // Drive has a key that works and a spreadsheet nobody has shared with it
+    // yet, and that failure looks exactly like a broken credential.
+    printSetup(
+      manifest,
+      `The key is already stored at ${assertion.key_ref}, so it is not asked for again — but what ` +
+        'it can reach is granted per resource, and this is the first connection of this one.',
+      assertion.setup,
+    );
+    progress(ok(`key already stored (${assertion.key_ref})`));
+    // Named because this is the only way past a key that is stored and wrong,
+    // and a well-formed key for the wrong project is refused by the token
+    // endpoint rather than here.
+    progress(style.dim(`  To replace it: lanes link connect ${manifest.id} --replace`));
+  } else {
+    if (stored) {
+      progress(
+        style.dim(
+          `Replacing ${assertion.key_ref} — what is stored is overwritten only once you have entered a new one.`,
+        ),
+      );
+    }
+
+    const answers = await askForSetup(
+      manifest,
+      [keyPrompt],
+      `Stored at ${assertion.key_ref}, in the credential store — never in config.`,
+      prompter,
+      assertion.setup,
+    );
+
+    const contents = await contentsOf(answers.get(keyPrompt.key)!);
+
+    // Parsed before it is written, so the wrong file is caught here rather than
+    // at the token endpoint. The two candidates live on adjacent pages of the
+    // same console and `parseAssertionKey` knows how to tell them apart.
+    const key = parseAssertionKey(contents, assertion.key_ref);
+
+    await credentials.set(assertion.key_ref, contents);
+    changes.push(`${assertion.key_ref} stored`);
+    progress(ok(`key stored — it acts as ${key.client_email}`));
+  }
+
+  const subject = await askForSubject(assertion, prompter);
+
+  await credentials.set(
+    credentialRefForConnection(manifest, connectionId)!,
+    JSON.stringify({
+      grant: ASSERTION_GRANT,
+      key_ref: assertion.key_ref,
+      ...(subject ? { subject } : {}),
+    }),
+  );
+
+  progress(ok(subject ? `authenticated as ${subject}` : 'authenticated'));
+}
+
+/**
+ * Who the key acts as, where it acts as anyone.
+ *
+ * Blank is a real answer when delegation is `optional` — the key is then an
+ * identity in its own right. It is refused when delegation is `required`,
+ * because the alternative is a credential that authenticates perfectly and
+ * finds nothing: there is no mailbox or contact list belonging to a key, so
+ * every call would return an empty result rather than an error, which is the
+ * worst way for this to be wrong.
+ */
+async function askForSubject(
+  assertion: AuthAssertion,
+  prompter: Prompter,
+): Promise<string | undefined> {
+  const optional = assertion.delegation === 'optional';
+
+  if (!prompter.interactive) {
+    if (optional) return undefined;
+    throw new Error(
+      `This provider can only reach an account by acting as someone, and this run is ` +
+        `non-interactive so there is nobody to ask who. Re-run in a terminal.`,
+    );
+  }
+
+  progress();
+  const answer = await prompter.ask(
+    `  ${assertion.subject_label}${optional ? style.dim(' [none]') : ''}`,
+  );
+
+  if (answer.length > 0) return answer;
+
+  if (optional) return undefined;
+
+  throw new Error(
+    `${assertion.subject_label} is required here: this provider has nothing that belongs to a ` +
+      'key, so a connection that acts as nobody would authenticate and then find every ' +
+      'mailbox, list and calendar empty.',
+  );
+}

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

@@ -16,9 +16,14 @@ import { ensureOAuthApp } from './setup.ts';
 /**
  * Getting a token, and saying what it will be able to do first.
  *
- * Two paths, because two kinds of upstream: an MCP server publishes metadata
- * worth discovering and the SDK drives it, while a plain REST API announces
- * nothing and the manifest has to name its endpoints.
+ * Two paths, and what chooses between them is not the kind of upstream but
+ * whether the manifest names its own endpoints. Without them there is nothing
+ * to authorise against but what the server advertises, so the SDK discovers it
+ * and drives the flow. With them there is nothing left to discover, and the
+ * flow is ours — which is the only arrangement in which a client somebody else
+ * holds can redeem the code. A REST API never announces an authorization
+ * server, so it is always on the second path; an MCP server may be on either.
+ * See ADR-040.
  */
 
 /**
@@ -65,8 +70,8 @@ export async function authorise(input: {
   /** How the operator spelled the target, so a refusal names a command they typed. */
   target?: string;
   profile: string;
-  /** `--own-client`: register a client rather than using the one a broker runs. */
-  ownClient?: boolean;
+  /** Which OAuth client, when the operator chose one. `undefined` keeps today's precedence. */
+  client?: 'own' | 'hosted' | undefined;
   prompter?: Prompter;
   /** The operator has already said yes to scopes broader than the provider needs. */
   acceptBroadScopes?: boolean;
@@ -86,13 +91,24 @@ export async function authorise(input: {
   // announces. So the manifest names the endpoints and we run the flow
   // directly — the same loopback listener, PKCE, and exchange, minus the
   // discovery the SDK would otherwise do for us.
-  if (manifest.connector.kind !== 'mcp') {
+  //
+  // An MCP connector takes that path too when it names both endpoints, and that
+  // is the *only* thing declaring them means. The SDK's flow ends by posting to
+  // the token endpoint with whatever `clientInformation()` returned, which is
+  // fine for a client the operator holds and impossible for one held by a
+  // broker — so a provider whose client lives somewhere else opts out here
+  // rather than discovering it after consent. Nothing is lost by opting out:
+  // discovery is all the SDK was doing that this does not, and a manifest that
+  // names its endpoints has nothing left to discover. Notion, Linear, and
+  // Google's two MCP servers name neither and are untouched. See ADR-040.
+  if (
+    manifest.connector.kind !== 'mcp' ||
+    (manifest.auth.authorize_url !== undefined && manifest.auth.token_url !== undefined)
+  ) {
     await authoriseDirect(input);
     return;
   }
 
-  // An MCP provider is always bring-your-own: `defineProvider` refuses a broker
-  // on one, because the SDK owns the exchange and there is no seam to route it.
   if (manifest.auth.registration === 'manual') {
     await ensureOAuthApp(input);
   }
@@ -187,7 +203,7 @@ async function authoriseDirect(input: {
   firstForProvider: boolean;
   target?: string;
   profile: string;
-  ownClient?: boolean;
+  client?: 'own' | 'hosted' | undefined;
   prompter?: Prompter;
   acceptBroadScopes?: boolean;
   fetch?: typeof globalThis.fetch;
@@ -210,7 +226,7 @@ async function authoriseDirect(input: {
     document: input.document,
     changes: input.changes,
     firstForProvider: input.firstForProvider,
-    ownClient: input.ownClient === true,
+    client: input.client,
     target: input.target ?? manifest.id,
     profile: input.profile,
     ...(input.prompter ? { prompter: input.prompter } : {}),
@@ -234,19 +250,39 @@ async function authoriseDirect(input: {
     throw new Error('Cancelled — nothing was authorised.');
   }
 
+  // What a response carrying no refresh token means, which only the manifest
+  // knows: Google omitting one is a failure worth stopping for, Slack omitting
+  // one is the ordinary success. See `RefreshTokenPolicy`.
+  const refreshToken = {
+    required: manifest.auth.refresh_token === 'required',
+    vendor: manifest.name,
+    ...(manifest.auth.revoke_url ? { revokeUrl: manifest.auth.revoke_url } : {}),
+  };
+
   let tokens;
   try {
     tokens = await runOAuthFlow({
       authorizeUrl,
-      clientId: client.kind === 'own' ? client.clientId : client.config.clientId,
-      ...(client.kind === 'own'
-        ? { tokenUrl, clientSecret: client.clientSecret }
-        : {
+      clientId: client.kind === 'brokered' ? client.config.clientId : client.clientId,
+      ...(client.kind === 'brokered'
+        ? {
             exchange: brokerExchangeVia({
               url: client.url,
+              refreshToken,
               ...(input.fetch ? { fetch: input.fetch } : {}),
             }),
+          }
+        : {
+            tokenUrl,
+            clientSecret: client.clientSecret,
           }),
+      refreshToken,
+      // Only where the broker published one, which means only where the vendor
+      // refuses a loopback redirect. The broker owns the URL because the
+      // correct value depends on which deployment answered `/config`.
+      ...(client.kind === 'brokered' && client.config.redirectUri
+        ? { relayRedirect: client.config.redirectUri }
+        : {}),
       scopes,
       connectionLabel: manifest.name,
       ...(manifest.auth.authorize_params
@@ -283,10 +319,18 @@ async function authoriseDirect(input: {
     `${manifest.id}/${connectionId}`,
     JSON.stringify({
       access_token: tokens.accessToken,
-      refresh_token: tokens.refreshToken,
+      // Both omitted rather than defaulted where the vendor issues neither.
+      //
+      // A long-lived token has no refresh token and states no lifetime, and
+      // inventing an hour for it would have `doctor` reporting a healthy
+      // connection as stale forever while telling the operator to re-run a
+      // command that changes nothing. Absent is what `upstreamAccessToken`
+      // already reads as "hand back what is stored", which is correct here.
+      ...(tokens.refreshToken ? { refresh_token: tokens.refreshToken } : {}),
       token_type: 'Bearer',
-      expires_in: tokens.expiresIn,
-      expires_at: Date.now() + tokens.expiresIn * 1000,
+      ...(tokens.expiresIn !== undefined
+        ? { expires_in: tokens.expiresIn, expires_at: Date.now() + tokens.expiresIn * 1000 }
+        : {}),
       scope: tokens.scope,
       issuer: new URL(authorizeUrl).origin,
       ...(tokens.idToken ? { id_token: tokens.idToken } : {}),