@lanes-sh/link 0.3.2 → 0.4.1

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

@@ -27,6 +27,7 @@ export async function settleIdentity(input: {
     credentials: SecretStore;
     registry: { manifest(id: string): ProviderManifest | undefined };
     connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+    authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
   };
   prompter?: Prompter;
 }): Promise<{ connectionId: string; account: string }> {
@@ -51,8 +52,24 @@ export async function settleIdentity(input: {
   if (!account) {
     const token = () => bearerTokenAsStored(manifest, provisionalId, runtime.credentials);
 
+    // Only where `accessToken` cannot answer: `requestAuthorizer` goes through
+    // `credentialResolver`, which may *refresh* an OAuth token, and
+    // `bearerTokenAsStored` is deliberately the connect-time variant that does
+    // not. Leaving oauth and bearer on the token keeps refresh behaviour
+    // exactly as it was; these three had no working path at all.
+    const carriesItsOwnHeader =
+      manifest.auth.kind === 'api_key' ||
+      manifest.auth.kind === 'header' ||
+      manifest.auth.kind === 'basic';
+
     account = await resolveAccount(manifest, {
       accessToken: token,
+      ...(carriesItsOwnHeader
+        ? {
+            authorize: (request: Request) =>
+              runtime.authorizeRequest(manifest.id, provisionalId, request),
+          }
+        : {}),
       // A protocol that authenticates by username has nothing to GET and no
       // tool to call — it knows, once the server has accepted the login.
       identify: async () =>

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

@@ -145,7 +145,15 @@ export async function ensureStaticCredential(input: {
   const { manifest, connectionId, credentials, replace, provisional } = input;
   const prompter = input.prompter ?? terminalPrompter;
   const auth = manifest.auth;
-  if (auth.kind === 'none' || auth.kind === 'oauth' || auth.kind === 'strategy') return;
+  // `strategy` used to be excluded here, from when no strategy existed and the
+  // kind was unreachable. It is exactly the wrong exclusion: a strategy
+  // provider's credential is *more* of a pasted value than most — bunq's API
+  // key is the input its handshake runs on — and skipping the prompt left
+  // `lanes link connect bunq` storing nothing and then failing inside the
+  // handshake with "no API key was stored", on the interactive path the setup
+  // documentation describes. Everything below is generic: the ref derives, the
+  // prompts come from the manifest.
+  if (auth.kind === 'none' || auth.kind === 'oauth') return;
 
   const ref = credentialRefForConnection(manifest, connectionId)!;
   const stored = await credentials.has(ref);

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

@@ -0,0 +1,87 @@
+import { credentialRefForConnection, strategyContextFrom, strategyFor } from '#connectivity';
+import type { ProviderManifest } from '#connectivity';
+import { createScopedStore, scopeNamespace } from '#dispatch';
+import { scopeSecrets } from '#secrets';
+import type { SecretStore } from '#secrets';
+import type { RuntimeState } from '#stores/state';
+import type { ProviderRegistry } from '#registry';
+import { progress, style } from '../../output.ts';
+
+/**
+ * The handshake a strategy provider needs before it can be called at all.
+ *
+ * Ordinary providers finish authenticating the moment the operator pastes
+ * something: the value *is* the credential. A strategy provider has only half
+ * of one at that point — bunq's API key is the input to an installation, not a
+ * token — so this runs the vendor's own setup between storing what was pasted
+ * and asking whose account it is.
+ *
+ * **Why it sits where it does in `connect`.** After the credential is stored,
+ * because the handshake's input is what was pasted. Before identity is settled
+ * and anything is written to the config, because a key the vendor rejects
+ * should fail here — with the vendor's own message — rather than leaving a
+ * connection row describing an account that cannot be reached. It runs under
+ * the *provisional* connection id for the same reason every other step does:
+ * the real one is not known yet, and `connect` moves the credential when it is.
+ *
+ * Here rather than in `index.ts` because that file is at its size budget, and
+ * because this is one self-contained step: everything it needs is a manifest
+ * and a runtime, and everything it produces is in the credential store.
+ */
+export async function runStrategySetup(
+  manifest: ProviderManifest,
+  /** The provisional id. `connect` renames the connection afterwards and the credential follows. */
+  connectionId: string,
+  /** Structurally the CLI `Runtime`, named as the parts this actually reaches. */
+  runtime: {
+    readonly registry: ProviderRegistry;
+    readonly credentials: SecretStore;
+    readonly state: RuntimeState;
+    readonly resolution: { readonly profile: string };
+  },
+): Promise<void> {
+  const { registry, credentials, state } = runtime;
+  const profile = runtime.resolution.profile;
+  if (manifest.auth.kind !== 'strategy') return;
+
+  const strategy = strategyFor(manifest, registry);
+  if (!strategy.setup) return;
+
+  // The one ref this connection may read, which is also the one the pasted
+  // value landed in and the one the handshake will rewrite.
+  const ref = credentialRefForConnection(manifest, connectionId)!;
+
+  const context = strategyContextFrom({
+    source: {
+      credentials: scopeSecrets(credentials, [ref]),
+      state: createScopedStore(state, scopeNamespace(manifest.id, connectionId)),
+      log: {
+        debug: () => {},
+        info: (message) => progress(style.dim(`  ${message}`)),
+        warn: (message) => progress(style.dim(`  ${message}`)),
+        error: (message) => progress(style.dim(`  ${message}`)),
+      },
+    },
+    manifest,
+    connectionId,
+    profile,
+    // Writable *only* here — the dispatch path passes nothing, so a per-request
+    // handshake cannot persist anything.
+    //
+    // Scoped to the same single ref the reads are. Handing over the raw store
+    // would leave the write side of this boundary open while the read side is
+    // shut, which is the asymmetry that makes a boundary decorative: a strategy
+    // could not *read* `google/main` and could quietly overwrite it.
+    write: async (reference, value) => {
+      if (reference !== ref) {
+        throw new Error(
+          `The ${manifest.name} strategy tried to write ${reference}, which is not its connection's credential (${ref}).`,
+        );
+      }
+      await credentials.set(reference, value);
+    },
+  });
+
+  progress(style.dim(`  Registering this device with ${manifest.name}…`));
+  await strategy.setup(context);
+}

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

@@ -0,0 +1,41 @@
+import { layout } from '#profile';
+import type { ProviderRegistry } from '#registry';
+import { PROGRAM } from '../../usage.ts';
+
+/**
+ * What to say when a name resolves to no provider.
+ *
+ * The one message that has to teach something, because a misspelling and a
+ * service nobody has integrated arrive here identically and want opposite
+ * answers. So it prints both lists — what is shipped, and what this profile has
+ * added — and then the command that adds another.
+ *
+ * It named `<root>/providers/` for a long time, which is not where manifests
+ * live and never was. The path comes from `layout` now, like every other
+ * profile-owned path, and the "add your own" line is printed whether or not the
+ * operator already has one: showing it only to somebody with none meant hiding
+ * it from everybody except the one person who could not yet know it existed.
+ */
+export function unknownProvider(input: {
+  readonly providerId: string;
+  readonly registry: ProviderRegistry;
+  readonly workspaceRoot: string;
+  readonly profile: string;
+  readonly target: string;
+}): Error {
+  const available = input.registry.list();
+  const builtin = available.filter((c) => c.origin === 'builtin').map((c) => c.manifest.id);
+  const yours = available.filter((c) => c.origin === 'workspace').map((c) => c.manifest.id);
+
+  const selection = `--profile ${input.profile} --target ${input.target}`;
+  const directory = `${input.workspaceRoot}/${layout.providers(input.profile)}`;
+
+  return new Error(
+    `Unknown provider "${input.providerId}".\n` +
+      `  built in: ${builtin.join(', ')}\n` +
+      (yours.length > 0 ? `  yours:    ${yours.join(', ')}\n` : '') +
+      `  add your own: ${PROGRAM} connect custom ${input.providerId}` +
+      ` --connector <kind> --auth <method> ${selection}\n` +
+      `                or a manifest in ${directory}\n`,
+  );
+}

package/src/cli/commands/mcp/list.ts

@@ -1,8 +1,46 @@
-import { heading, print, style } from '../../output.ts';
+import { emit, heading, print, style } from '../../output.ts';
 import { assetState, plannedAssets, readAsset } from './assets.ts';
 import { HARNESSES, type Harness } from './harnesses.ts';
 import { exists } from './register.ts';
 
+/** Why a document this harness can hold is not what we ship, if it is not. */
+export type DocumentState = 'current' | 'stale' | 'missing' | 'unreadable';
+
+export interface ListedDocument {
+  readonly label: string;
+  readonly path: string;
+  readonly state: DocumentState;
+  /** Only for `unreadable` — what went wrong reading the bundled copy. */
+  readonly detail?: string;
+}
+
+export interface ListedHarness {
+  readonly id: string;
+  readonly label: string;
+  readonly installed: boolean;
+  /** The resolved binary, so a caller can see *which* claude answered. */
+  readonly binary: string | null;
+  readonly registered: boolean;
+  /**
+   * Empty when the harness is not installed, matching what the text rendering
+   * says: with no binary there is nothing to register the documents against, and
+   * reporting them would describe a setup that does not exist.
+   */
+  readonly documents: readonly ListedDocument[];
+}
+
+export interface McpListing {
+  readonly name: string;
+  readonly scope: string;
+  readonly harnesses: readonly ListedHarness[];
+}
+
+export interface McpListFlags {
+  readonly name?: string | undefined;
+  readonly scope?: string | undefined;
+  readonly json?: boolean | undefined;
+}
+
 /**
  * `lanes link mcp list` — where this endpoint is registered, and whether what
  * each harness has been told about it is still what we ship.
@@ -11,58 +49,114 @@ import { exists } from './register.ts';
  * different fixes. A registration without the skill is a working endpoint
  * nobody reaches for; a skill against no registration is a document describing
  * tools that are not there.
+ *
+ * The listing is gathered before anything is printed, so `--json` and the text
+ * rendering describe the same snapshot rather than two probes taken a moment
+ * apart. `--json` exists because this is the one command another program has a
+ * reason to read: it is how a UI decides between "add" and "re-add", and the
+ * `stale` state is the only signal that a re-run would do something.
  */
-export async function mcpList(options: { name?: string | undefined; scope?: string | undefined }): Promise<void> {
+export async function mcpList(options: McpListFlags): Promise<void> {
   const name = options.name ?? 'lanes-link';
   const scope = options.scope ?? 'user';
 
-  heading(`Registered as ${style.bold(name)}`);
+  const listing = await listRegistrations(name, scope);
+
+  await emit(options.json, listing, () => render(listing));
+}
+
+/** The whole answer, gathered. No printing, so a caller can have it as data. */
+export async function listRegistrations(name: string, scope: string): Promise<McpListing> {
+  const harnesses: ListedHarness[] = [];
 
   for (const harness of HARNESSES) {
     const binary = Bun.which(harness.binary);
 
     if (!binary) {
-      print(`  ${harness.label.padEnd(14)} ${style.dim('not installed')}`);
+      harnesses.push({
+        id: harness.id,
+        label: harness.label,
+        installed: false,
+        binary: null,
+        registered: false,
+        documents: [],
+      });
       continue;
     }
 
-    print(
-      `  ${harness.label.padEnd(14)} ${
-        exists(binary, harness, name)
-          ? style.green('registered')
-          : style.dim(`not registered — lanes link mcp add ${harness.id}`)
-      }`,
-    );
-
-    for (const line of await documentLines(harness, scope)) print(`  ${' '.repeat(14)} ${line}`);
+    harnesses.push({
+      id: harness.id,
+      label: harness.label,
+      installed: true,
+      binary,
+      registered: exists(binary, harness, name),
+      documents: await documents(harness, scope),
+    });
   }
+
+  return { name, scope, harnesses };
 }
 
-/** One line per document this harness can hold, saying whether it is current. */
-async function documentLines(harness: Harness, scope: string): Promise<string[]> {
-  const lines: string[] = [];
+/** One entry per document this harness can hold, saying whether it is current. */
+async function documents(harness: Harness, scope: string): Promise<ListedDocument[]> {
+  const listed: ListedDocument[] = [];
 
   for (const plan of plannedAssets(harness, scope)) {
     try {
-      const state = await assetState(plan, await readAsset(plan.asset));
-
-      lines.push(
-        state === 'current'
-          ? style.dim(`${plan.asset.label}: `) + style.green('up to date')
-          : style.dim(
-              state === 'stale'
-                ? `${plan.asset.label}: out of date — lanes link mcp add ${harness.id}`
-                : `${plan.asset.label}: not installed — lanes link mcp add ${harness.id}`,
-            ),
-      );
+      listed.push({
+        label: plan.asset.label,
+        path: plan.path,
+        state: await assetState(plan, await readAsset(plan.asset)),
+      });
     } catch (error) {
       // A checkout without `instructions/` — a container image, say. Worth one
       // line rather than a thrown error that hides the registration column.
-      lines.push(style.dim(`${plan.asset.label}: ${message(error)}`));
+      listed.push({
+        label: plan.asset.label,
+        path: plan.path,
+        state: 'unreadable',
+        detail: message(error),
+      });
+    }
+  }
+
+  return listed;
+}
+
+function render(listing: McpListing): void {
+  heading(`Registered as ${style.bold(listing.name)}`);
+
+  for (const harness of listing.harnesses) {
+    if (!harness.installed) {
+      print(`  ${harness.label.padEnd(14)} ${style.dim('not installed')}`);
+      continue;
+    }
+
+    print(
+      `  ${harness.label.padEnd(14)} ${
+        harness.registered
+          ? style.green('registered')
+          : style.dim(`not registered — lanes link mcp add ${harness.id}`)
+      }`,
+    );
+
+    for (const document of harness.documents) {
+      print(`  ${' '.repeat(14)} ${documentLine(harness.id, document)}`);
     }
   }
+}
 
-  return lines;
+function documentLine(id: string, document: ListedDocument): string {
+  switch (document.state) {
+    case 'current':
+      return style.dim(`${document.label}: `) + style.green('up to date');
+    case 'stale':
+      return style.dim(`${document.label}: out of date — lanes link mcp add ${id}`);
+    case 'missing':
+      return style.dim(`${document.label}: not installed — lanes link mcp add ${id}`);
+    case 'unreadable':
+      return style.dim(`${document.label}: ${document.detail}`);
+  }
 }
 
 function message(error: unknown): string {

package/src/cli/identity.ts

@@ -29,9 +29,29 @@ export function pluck(value: unknown, path: string): string | null {
   return typeof current === 'string' && current.length > 0 ? current : null;
 }
 
+/** The header an OAuth or bearer provider's probe carries. */
+async function bearerHeaders(probe: IdentityProbe): Promise<RequestInit> {
+  const token = await probe.accessToken();
+  return { headers: token ? { authorization: `Bearer ${token}` } : {} };
+}
+
 export interface IdentityProbe {
   /** A valid upstream access token, if the provider authenticates. */
   readonly accessToken: () => Promise<string | null>;
+  /**
+   * Put this connection's credential on a request, whatever method it is.
+   *
+   * Supplied where `accessToken` cannot answer. A stored `api_key`, `header` or
+   * `basic` credential is not a bearer token and `bearerToken` throws for all
+   * three — under a comment calling the branch unreachable, which it is on an
+   * mcp connector and is not on an http one. The throw was caught by the
+   * catch-all below, so an `identity: { kind: http }` block on the commonest
+   * custom shape there is — a REST API behind an API key — never worked and
+   * never said so: the operator was asked to name the account by hand on every
+   * reconnect, and a different answer each time is a new row rather than a
+   * repair.
+   */
+  readonly authorize?: (request: Request) => Promise<Request>;
   /** Call a capability on the upstream MCP server. */
   readonly callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
   /** Ask the connector, for a protocol whose identity is not a URL away. */
@@ -52,11 +72,15 @@ export async function resolveAccount(
     }
 
     if (identity.kind === 'http') {
-      const token = await probe.accessToken();
-      const request = probe.fetch ?? globalThis.fetch;
-      const response = await request(identity.url, {
-        headers: token ? { authorization: `Bearer ${token}` } : {},
-      });
+      const send = probe.fetch ?? globalThis.fetch;
+
+      // `authorize` where the caller supplied one, because it is the same
+      // switch the dispatch path uses and knows every method. The token is the
+      // fallback rather than the other way round only because the OAuth
+      // providers reached here first; both end at the same header for them.
+      const response = probe.authorize
+        ? await send(await probe.authorize(new Request(identity.url)))
+        : await send(identity.url, await bearerHeaders(probe));
       if (!response.ok) return null;
 
       const body = await response.json();

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { connect } from './commands/connect/index.ts';
+import { connectCustom } from './commands/connect/custom/index.ts';
 import {
   attachFile,
   auditTail,
@@ -29,7 +30,7 @@ import { secretsList, secretsPush, secretsSet } from './commands/secrets.ts';
 import { knowledgeShow, knowledgeUse } from './commands/knowledge.ts';
 import { dispatchOwner } from './dispatch-owner.ts';
 import { update } from './commands/update.ts';
-import { all, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import { all, customFlags, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
 import { assertKnownFlags, requireSelection } from './selection.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
@@ -75,18 +76,41 @@ export async function run(argv: readonly string[]): Promise<void> {
 
   switch (first) {
     case 'connect':
-      if (!second) throw new Error(`Usage: ${PROGRAM} connect <provider>`);
-      return connect(second, {
-        ...global,
-        id: text(flags, 'id'),
-        displayName: text(flags, 'display-name'),
-        replace: flags['replace'] === true,
-        nonInteractive: flags['non-interactive'] === true,
-        acceptBroadScopes: flags['accept-broad-scopes'] === true,
-        ownClient: flags['own-client'] === true,
-        auth: text(flags, 'auth'),
-        json,
-      });
+      // A nested switch rather than an `if`, so `selection.test.ts` sees
+      // `connect custom` when it reads this file for `case` labels: it matches
+      // on eight-space indentation, and a command invisible to that check is a
+      // command that can default quietly.
+      switch (second) {
+        case 'custom':
+          return connectCustom(rest[0], {
+            ...global,
+            ...customFlags(flags, argv),
+            id: text(flags, 'id'),
+            displayName: text(flags, 'display-name'),
+            replace: flags['replace'] === true,
+            nonInteractive: flags['non-interactive'] === true,
+            acceptBroadScopes: flags['accept-broad-scopes'] === true,
+            json,
+          });
+
+        // Not a `case` label, so it adds no row to `SELECTION`: there is no
+        // command here to classify, only a usage error.
+        case undefined:
+          throw new Error(`Usage: ${PROGRAM} connect <provider>`);
+
+        default:
+          return connect(second, {
+            ...global,
+            id: text(flags, 'id'),
+            displayName: text(flags, 'display-name'),
+            replace: flags['replace'] === true,
+            nonInteractive: flags['non-interactive'] === true,
+            acceptBroadScopes: flags['accept-broad-scopes'] === true,
+            ownClient: flags['own-client'] === true,
+            auth: text(flags, 'auth'),
+            json,
+          });
+      }
 
     case 'setup':
       if (second !== 'plan' && second !== undefined) {
@@ -297,7 +321,11 @@ export async function run(argv: readonly string[]): Promise<void> {
           return mcpStdio({ ...global, ...(flags['only'] === true ? { only: true } : {}) });
         case 'list':
         case undefined:
-          return mcpList({ name: text(flags, 'name'), scope: text(flags, 'scope') });
+          return mcpList({
+            name: text(flags, 'name'),
+            scope: text(flags, 'scope'),
+            json: flags['json'] === true,
+          });
         default:
           throw new Error(`Unknown: ${PROGRAM} mcp ${second}`);
       }

package/src/cli/oauth.ts

@@ -66,6 +66,27 @@ export interface OAuthFlowOptions {
    * on the way back. What changes is only the address the vendor is told.
    */
   readonly relayRedirect?: string;
+  /**
+   * A redirect this machine listens on, named to the vendor exactly as written.
+   *
+   * The third answer to "where does the browser come back to", and the one the
+   * comment above did not anticipate. `relayRedirect` exists for a vendor that
+   * will take no loopback address at all; this is for a vendor that takes one
+   * happily but matches it *exactly*, port included — so the kernel-chosen port
+   * below can never match a URL registered in a console months earlier.
+   *
+   * That is not a rare shape. It is the reason `providers/github/index.ts`
+   * gives for using a pasted token rather than OAuth: "an OAuth App matches its
+   * callback URL exactly, including the port, and `connect` listens on a port
+   * the kernel picks."
+   *
+   * The whole URL rather than just a port, because the two must be identical
+   * strings and only one of them is ours to choose. A console that accepts
+   * `localhost` but not `127.0.0.1` — or insists on a trailing path — decides
+   * the spelling, and a manifest that could only name a number would have to
+   * guess the rest right.
+   */
+  readonly fixedRedirect?: string;
   /** What the completion page names as connected. A provider's display name. */
   readonly connectionLabel?: string;
   /** How long to wait for the operator to finish in the browser. */
@@ -130,48 +151,80 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
     rejectCode = reject;
   });
 
-  const server = Bun.serve({
-    hostname: '127.0.0.1',
-    port: 0, // let the OS choose; nothing outside this machine names this port
-    fetch(request) {
-      const url = new URL(request.url);
-      if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
-
-      const error = url.searchParams.get('error');
-      if (error) {
-        rejectCode(
-          new OAuthError(
-            error === 'access_denied'
-              ? 'Authorization was declined in the browser.'
-              : `Authorization failed: ${error}`,
-          ),
-        );
-        return failedPage('You can close this tab.');
-      }
+  // A fixed redirect is only fixed if we listen where it says. Parsed rather
+  // than configured separately so the two cannot disagree: the port the vendor
+  // was told is by construction the port this binds.
+  const fixed = options.fixedRedirect ? new URL(options.fixedRedirect) : undefined;
+  const fixedPort = fixed ? Number(fixed.port) : undefined;
 
-      const returnedState = url.searchParams.get('state');
-      if (!returnedState || !stateMatches(state, returnedState)) {
-        // A mismatched state means this callback did not come from the
-        // request we started. Refuse it rather than redeeming whatever code
-        // it carries.
-        rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
-        return failedPage('Unexpected callback.');
-      }
+  if (fixed && !fixedPort) {
+    throw new OAuthError(
+      `The redirect "${options.fixedRedirect}" names no port, so there is nothing for this machine to listen on. Register a redirect with an explicit port, such as http://127.0.0.1:8765/callback.`,
+    );
+  }
 
-      const code = url.searchParams.get('code');
-      if (!code) {
-        rejectCode(new OAuthError('The callback carried no authorization code.'));
-        return failedPage('No code returned.');
-      }
+  // Bun.serve throws synchronously when a port is taken. With a kernel-chosen
+  // port that cannot happen; with a fixed one it is the ordinary failure — a
+  // previous run still holding the socket, or another program on the port the
+  // vendor was told about. The raw EADDRINUSE names neither the provider nor
+  // the redirect, so it reads as a crash rather than as something to fix.
+  const server = ((): ReturnType<typeof Bun.serve> => {
+    try {
+    return Bun.serve({
+      hostname: '127.0.0.1',
+      // Zero lets the OS choose, which is right whenever nothing outside this
+      // machine names the port. A fixed redirect is exactly the case where
+      // something does.
+      port: fixedPort ?? 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
 
-      resolveCode(code);
-      return connectedPage(options.connectionLabel);
-    },
-  });
+        const error = url.searchParams.get('error');
+        if (error) {
+          rejectCode(
+            new OAuthError(
+              error === 'access_denied'
+                ? 'Authorization was declined in the browser.'
+                : `Authorization failed: ${error}`,
+            ),
+          );
+          return failedPage('You can close this tab.');
+        }
+
+        const returnedState = url.searchParams.get('state');
+        if (!returnedState || !stateMatches(state, returnedState)) {
+          // A mismatched state means this callback did not come from the
+          // request we started. Refuse it rather than redeeming whatever code
+          // it carries.
+          rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
+          return failedPage('Unexpected callback.');
+        }
+
+        const code = url.searchParams.get('code');
+        if (!code) {
+          rejectCode(new OAuthError('The callback carried no authorization code.'));
+          return failedPage('No code returned.');
+        }
+
+        resolveCode(code);
+        return connectedPage(options.connectionLabel);
+      },
+    });
+    } catch (cause) {
+      if (fixedPort) {
+        throw new OAuthError(
+          `Port ${fixedPort} is already in use, so the callback for this connection cannot be served. The redirect registered with the provider names that port exactly, so it cannot simply be moved — free the port and try again.`,
+        );
+      }
+      throw cause;
+    }
+  })();
 
   // Where the vendor is told to send the browser. The relay bounces it back
   // here; without one it comes here directly, which is every other provider.
-  const redirectUri = options.relayRedirect ?? `http://127.0.0.1:${server.port}/callback`;
+  const redirectUri =
+    options.relayRedirect ?? options.fixedRedirect ?? `http://127.0.0.1:${server.port}/callback`;
 
   /**
    * The CSRF binding, and — behind a relay — the only way home.