@lanes-sh/link 0.7.2 → 0.9.0

package/src/server/mcp/visibility.ts

@@ -1,10 +1,11 @@
 import { isTool } from '#connectivity';
 import type { Principal } from '#auth';
-import type { Config } from '#profile';
+import type { Config, SelectedConnection } from '#profile';
 import type { ProviderRegistry } from '#registry';
 import type { Dispatcher } from '#dispatch';
-import type { PolicyDocument } from '#policy';
+import type { PolicyDocument, ProfilePolicy } from '#policy';
 import { allowedConnections } from '#policy';
+import { mayReach } from '#auth';
 
 /**
  * What this principal can see, and therefore what gets registered at all.
@@ -23,9 +24,18 @@ import { allowedConnections } from '#policy';
 /** Everything one profile contributes to the endpoint. */
 export interface ProfileRuntime {
   readonly config: Config;
+  /**
+   * The accounts this profile selects, for the `connection` argument's
+   * description — the id alone cannot say which mailbox it is.
+   *
+   * Optional because a registry built to read manifests has no selection, the
+   * same reason `refreshSkills` is: a harness that omits it gets bare ids, which
+   * is what this listed for everybody before.
+   */
+  readonly connections?: readonly SelectedConnection[];
   readonly registry: ProviderRegistry;
   readonly dispatcher: Dispatcher;
-  readonly policy: PolicyDocument;
+  readonly policy: ProfilePolicy;
   readonly floor?: PolicyDocument | undefined;
   /**
    * Re-read the skills into `registry`, if they have changed on the store.
@@ -72,8 +82,16 @@ export function oneProfile(
   return new Map([[name, runtime]]);
 }
 
+/**
+ * The connections this profile can reach at all, before policy narrows further.
+ *
+ * The grant rows *are* the answer (ADR-058). A profile reaches what it grants
+ * and nothing else, so this needs no view of the workspace's connections — which
+ * is the useful half of decoupling them: what a profile can see is written in
+ * the profile, and cannot widen when somebody connects a new account.
+ */
 function connectionsOf(runtime: ProfileRuntime): string[] {
-  return runtime.config.connections.map((connection) => `${connection.provider}.${connection.id}`);
+  return runtime.config.grants.map((grant) => grant.connection);
 }
 
 /**
@@ -94,6 +112,12 @@ export function mergeCapabilities(options: BuildServerOptions): Map<string, Merg
   const merged = new Map<string, MergedCapability>();
 
   for (const [name, runtime] of options.profiles) {
+    // The same list the dispatcher enforces with. A member does not merely fail
+    // to call a profile they are not on — it is absent from the `profile` enum,
+    // so they never learn it exists (ADR-060). Discovery and enforcement share
+    // one answer here for the same reason they share `allowedConnections`.
+    if (!mayReach(options.principal, name)) continue;
+
     const connections = connectionsOf(runtime);
 
     for (const { id, capability, discovered } of runtime.registry.capabilities()) {
@@ -151,13 +175,56 @@ export function visibleToolCount(options: BuildServerOptions): number {
  * Grouped rather than flattened because the two arguments are not independent:
  * `profile: personal` with a connection belonging to `work` is refused, and a
  * flat list would read as though any pairing were valid.
+ *
+ * **The account, not just the id.** This listed bare ids, and the id is the
+ * only thing a model has to choose on — so two accounts of one vendor were
+ * `ada_lovelace` and `ada_lovelace2` and nothing said which mailbox either was.
+ * `idFromAccount` takes only the local part, so that is what two addresses at
+ * different domains actually produce. Picking the wrong one sends mail as the
+ * wrong person, which is the same class of failure ADR-056 rules out for
+ * entities: ordering is not selection, and a caller that cannot tell two
+ * candidates apart must be given what tells them apart.
+ *
+ * The enum stays bare ids, because the id is what the caller passes.
  */
 export function describeWithConnections(
   description: string,
   reachable: ReadonlyMap<string, readonly string[]>,
+  accounts: ReadonlyMap<string, ReadonlyMap<string, string>> = new Map(),
 ): string {
-  const lines = [...reachable].map(
-    ([profile, connections]) => `  ${profile}: ${connections.join(', ')}`,
-  );
+  const lines = [...reachable].flatMap(([profile, connections]) => {
+    const known = accounts.get(profile);
+    return [
+      `  ${profile}:`,
+      ...connections.map((id) => `    ${id}${known?.get(id) === undefined ? '' : ` — ${known.get(id)!}`}`),
+    ];
+  });
   return `${description}\n\nAvailable connections, by profile:\n${lines.join('\n')}`;
 }
+
+/**
+ * How each profile's connections should read to a caller choosing between them.
+ *
+ * `account` always, `label` where the operator set one — the two fields that
+ * exist because the id cannot carry meaning and must not pretend to.
+ */
+export function accountsByProfile(
+  options: BuildServerOptions,
+): Map<string, Map<string, string>> {
+  const accounts = new Map<string, Map<string, string>>();
+
+  for (const [name, runtime] of options.profiles) {
+    const rows = new Map<string, string>();
+    for (const { connection } of runtime.connections ?? []) {
+      rows.set(
+        connection.id,
+        connection.label === undefined
+          ? connection.account
+          : `${connection.account} (${connection.label})`,
+      );
+    }
+    accounts.set(name, rows);
+  }
+
+  return accounts;
+}

package/src/server/oauth.ts

@@ -1,11 +1,10 @@
 import {
   authorizationServerMetadata,
   protectedResourceMetadata,
-  type AuthorizeRequest,
   type OAuthResult,
   type OAuthServer,
 } from '#auth';
-import { approvalPage } from '#cli/callback-page.ts';
+import { noticePage } from '#cli/callback-page.ts';
 
 /**
  * The HTTP surface of the authorization flow.
@@ -24,6 +23,7 @@ export const PROTECTED_RESOURCE_PATH = '/.well-known/oauth-protected-resource';
 export const AUTHORIZATION_SERVER_PATH = '/.well-known/oauth-authorization-server';
 const REGISTER_PATH = '/register';
 const AUTHORIZE_PATH = '/authorize';
+const CALLBACK_PATH = '/authorize/callback';
 const TOKEN_PATH = '/token';
 
 export interface AuthorizationSurface {
@@ -50,6 +50,7 @@ export function isAuthorizationPath(pathname: string): boolean {
     pathname === AUTHORIZATION_SERVER_PATH ||
     pathname === REGISTER_PATH ||
     pathname === AUTHORIZE_PATH ||
+    pathname === CALLBACK_PATH ||
     pathname === TOKEN_PATH
   );
 }
@@ -125,35 +126,37 @@ export async function handleAuthorization(
   if (!server) return new Response('Not found', { status: 404 });
 
   if (path === REGISTER_PATH && request.method === 'POST') {
-    return render(await server.register(await safeJson(request)), request, surface.target);
+    return render(await server.register(await safeJson(request)), request);
   }
 
-  if (path === AUTHORIZE_PATH) {
-    if (request.method === 'GET') {
-      return render(await server.authorize(url.searchParams), request, surface.target);
-    }
-    if (request.method === 'POST') {
-      const form = new URLSearchParams(await request.text());
-      return render(
-        await server.approve(requestFromForm(form), form.get('token') ?? ''),
-        request,
-        surface.target,
-      );
-    }
+  // Who this endpoint is, from the point of view of *this* request. Derived
+  // from `Host` rather than config for the reason `publicOrigin` gives: a
+  // deployed instance's hostname is assigned at deploy time, and an assertion
+  // whose audience does not match exactly is refused.
+  const endpoint = {
+    resource: `${origin}${surface.mcpPath}`,
+    callbackUrl: `${origin}${CALLBACK_PATH}`,
+  };
+
+  if (path === AUTHORIZE_PATH && request.method === 'GET') {
+    return render(await server.authorize(url.searchParams, endpoint), request);
+  }
+
+  // The browser returning from lanes.sh. A GET, because it arrives as a
+  // top-level navigation from a 302 — which is also why nothing here reads
+  // `Origin`: a navigation carries none. See `rebinding.ts`.
+  if (path === CALLBACK_PATH && request.method === 'GET') {
+    return render(await server.callback(url.searchParams, endpoint), request);
   }
 
   if (path === TOKEN_PATH && request.method === 'POST') {
-    return render(
-      await server.token(new URLSearchParams(await request.text())),
-      request,
-      surface.target,
-    );
+    return render(await server.token(new URLSearchParams(await request.text())), request);
   }
 
   return new Response('Method not allowed', { status: 405 });
 }
 
-function render(result: OAuthResult, request: Request, target: string): Response {
+function render(result: OAuthResult, request: Request): Response {
   switch (result.kind) {
     case 'json':
       return json(result.body, result.status);
@@ -161,95 +164,12 @@ function render(result: OAuthResult, request: Request, target: string): Response
     case 'redirect':
       return new Response(null, { status: 302, headers: { location: result.location } });
 
-    case 'consent':
-      return approvalPage({
-        // The name if it gave one, the identifier if not. Either way the
-        // redirect host goes on the screen beside it — a client may call itself
-        // anything, but it cannot change where the code is sent.
-        client: result.clientName ?? result.request.clientId,
-        redirectHost: hostOf(result.request.redirectUri),
-        // The page's policy has to admit the redirect the page's own approval
-        // ends in, or the browser blocks it. See `formActionFor`.
-        ...formActionFor(result.request.redirectUri),
-        action: `${publicOrigin(request)}${AUTHORIZE_PATH}`,
-        fields: formFromRequest(result.request),
-        retry: result.retry,
-        target,
-      });
-
     case 'error':
-      return new Response(result.message, { status: result.status });
-  }
-}
-
-/**
- * The authorization request, carried through the approval form.
- *
- * Round-tripped through hidden fields rather than held in a server-side session:
- * the deployed endpoint replaces instances between requests, so a session begun
- * on one and submitted to another would be gone. Nothing here is a secret — the
- * client sent all of it in the query string — and none of it is trusted on the
- * way back, because `approve` re-checks the client and the redirect URI against
- * what is registered before it mints anything.
- */
-function formFromRequest(request: AuthorizeRequest): Record<string, string> {
-  return {
-    client_id: request.clientId,
-    redirect_uri: request.redirectUri,
-    code_challenge: request.codeChallenge,
-    scope: request.scope,
-    ...(request.state !== undefined ? { state: request.state } : {}),
-    ...(request.resource !== undefined ? { resource: request.resource } : {}),
-  };
-}
-
-function requestFromForm(form: URLSearchParams): AuthorizeRequest {
-  return {
-    clientId: form.get('client_id') ?? '',
-    redirectUri: form.get('redirect_uri') ?? '',
-    codeChallenge: form.get('code_challenge') ?? '',
-    scope: form.get('scope') ?? '',
-    state: form.get('state') ?? undefined,
-    resource: form.get('resource') ?? undefined,
-  };
-}
-
-function hostOf(uri: string): string {
-  try {
-    return new URL(uri).host;
-  } catch {
-    return uri;
-  }
-}
-
-/**
- * The redirect target as a CSP source, for the consent page's `form-action`.
- *
- * Chrome and Safari check that directive against the redirect a form submission
- * produces, so the page has to name where its own approval is about to send the
- * browser — `'self'` alone mints the code and then blocks its delivery.
- *
- * Taken from the request being approved rather than from what the client
- * registered, because the two legitimately differ: a native client registers
- * `http://localhost/callback` and binds whatever port it got (RFC 8252), and
- * the origin the browser navigates to is the one carrying that port. It is
- * already checked against the registration — by `authorize` before this page is
- * rendered, and again by `approve` before anything is minted — and it cannot
- * move the token, because the form's `action` is built here rather than read
- * from the request.
- *
- * An origin and nothing else, because `isSafeRedirect` registers nothing else:
- * https, or http on loopback. A private-use scheme — `vscode:`, the other shape
- * RFC 8252 allows — would need a scheme-source here, and is refused two steps
- * earlier, so a branch for it would be a branch nothing can reach.
- */
-function formActionFor(uri: string): { formAction?: string } {
-  try {
-    const { protocol, origin } = new URL(uri);
-    if (protocol !== 'http:' && protocol !== 'https:') return {};
-    return { formAction: origin };
-  } catch {
-    return {};
+      // A page rather than a bare string, because the audience changed. These
+      // used to be read by a client following a redirect; now the interesting
+      // ones — "no profile lists you" — are read by a person in a browser who
+      // has just signed in and needs to know what to do next.
+      return noticePage(result.message, result.status);
   }
 }
 

package/src/server/read/credential.ts

@@ -0,0 +1,134 @@
+import { timingSafeEqual } from 'node:crypto';
+
+/**
+ * Whether a presented credential is this workspace's pairing token.
+ *
+ * A verifier rather than the token itself, because the two binds pay very
+ * different prices for the answer and only the verifier can know that. On
+ * loopback the credential store holds a decrypted copy and a read is a map
+ * lookup; on a deployed workspace `GcpSecretManagerStore` has no cache at all
+ * and every `get()` is a network round trip. A shared `token: () => Promise`
+ * thunk hid that difference behind one signature, and the comment that used to
+ * sit above it — "this is a map lookup in the ordinary case" — was true of one
+ * store and false of the other.
+ */
+export interface PairingCredential {
+  /** Never throws. A store that failed is a refusal, not a `500`. */
+  verify(presented: string): Promise<boolean>;
+}
+
+/**
+ * Constant-time, after a length check.
+ *
+ * The length is compared first and separately because `timingSafeEqual` throws
+ * on a mismatch rather than returning false. The length of a token is not the
+ * secret; its contents are.
+ */
+function matches(presented: string, expected: string): boolean {
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export interface CredentialSource {
+  /** `null` for a secret that exists with no version — the never-paired case. */
+  readonly read: () => Promise<string | null>;
+  /** Drops a cached decrypted copy, because the rotation was written elsewhere. */
+  readonly refresh?: (() => void) | undefined;
+  /** Why a read failed, for an operator. Never the credential itself. */
+  readonly onError?: ((reason: string) => void) | undefined;
+}
+
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Loopback: read on every presentation, so a rotation lands immediately.
+ *
+ * `pair --rotate` says "the previous pairing link no longer works", and captured
+ * at boot that was false — the live listener went on accepting the old token
+ * until the endpoint restarted. Reading per request is what makes the command
+ * tell the truth, and it is affordable here because the store is a local file.
+ */
+export function directPairingCredential(source: CredentialSource): PairingCredential {
+  return {
+    async verify(presented) {
+      try {
+        source.refresh?.();
+        const expected = await source.read();
+        return expected !== null && expected !== '' && matches(presented, expected);
+      } catch (error) {
+        source.onError?.(reasonOf(error));
+        return false;
+      }
+    },
+  };
+}
+
+/** How long a deployed endpoint may keep an answer. Matches the bearer's own window. */
+const CACHE_TTL_MS = 5_000;
+
+/**
+ * Deployed: one cached read, and a mismatch buys exactly one more.
+ *
+ * The same trade `BearerAuthenticator` already takes for the MCP bearer, over a
+ * strictly weaker credential and with the same five seconds. Without it a
+ * dashboard polling `/state` is one Secret Manager call per poll for as long as
+ * the page is open, and a stranger sending a wrong token is one call per
+ * request — which is the ADR-054 hazard in its purest form, a costly read
+ * performed on behalf of a caller who has presented nothing valid.
+ *
+ * What the re-read on mismatch preserves is the property that mattered: a
+ * token rotated *in* works on its first presentation, because a mismatch
+ * against a cached value is ambiguous and exactly one re-read separates
+ * "rotated" from "wrong". What it costs is that a token rotated *away* keeps
+ * reading for up to the window rather than stopping at once — bounded, where
+ * the failure `open.ts` records was unbounded until a restart.
+ */
+export function cachedPairingCredential(
+  source: CredentialSource & { readonly ttlMs?: number; readonly now?: () => number },
+): PairingCredential {
+  const ttl = source.ttlMs ?? CACHE_TTL_MS;
+  const now = source.now ?? (() => Date.now());
+
+  let cached: string | null = null;
+  // Both start "infinitely stale", so the first call reads and the first
+  // mismatch is always given its one re-read.
+  let readAt = -Infinity;
+  let missAt = -Infinity;
+
+  const reread = async (): Promise<void> => {
+    source.refresh?.();
+    cached = await source.read();
+    readAt = now();
+  };
+
+  const hit = (presented: string): boolean =>
+    cached !== null && cached !== '' && matches(presented, cached);
+
+  return {
+    async verify(presented) {
+      try {
+        if (now() - readAt >= ttl) await reread();
+        if (hit(presented)) return true;
+
+        // A miss against a cached value is ambiguous: the token may be wrong,
+        // or it may be the one a rotation has just written. One re-read tells
+        // them apart — and **one per window**, tracked separately from the
+        // ordinary refresh above. Keying it on `readAt` instead meant the
+        // re-read refreshed the very clock that decided whether to re-read, so
+        // every wrong guess bought its own Secret Manager call and the ceiling
+        // this cache exists to impose was not there at all.
+        if (now() - missAt < ttl) return false;
+        missAt = now();
+        await reread();
+
+        return hit(presented);
+      } catch (error) {
+        source.onError?.(reasonOf(error));
+        return false;
+      }
+    },
+  };
+}

package/src/server/read/deployed.ts

@@ -0,0 +1,56 @@
+import { PAIR_TOKEN_REF, readConnections } from '#profile';
+import type { Runtime } from '#cli/runtime.ts';
+import type { Logger } from '#connectivity';
+import type { ProfileRuntime } from '../mcp/visibility.ts';
+import { cachedPairingCredential } from './credential.ts';
+import type { ReadDeps } from './routes.ts';
+
+/**
+ * The same read surface, on a deployed endpoint's own port (ADR-064).
+ *
+ * Its sibling `./open.ts` binds a second TLS listener and cannot be used here:
+ * Cloud Run routes exactly one port. So this returns dependencies rather than a
+ * socket, and the router serves the two paths in front of its own bearer gate —
+ * the pairing token never passes through the endpoint's authenticator, because
+ * one shared check would make each credential able to do the other's job.
+ *
+ * **Nothing here reads a credential.** That is the structural half of the fix
+ * `./open.ts` describes: the pairing token is read per request, behind a
+ * verifier, so a Secret Manager rejection can fail a request and can no longer
+ * fail a boot. Adding `PAIR_TOKEN_REF` to `readableRefs` is the other half, and
+ * it stops the rejection happening at all — a bound secret with no version
+ * answers 404 and reads back as `null`, which is the never-paired case and
+ * renders as an ordinary `401`.
+ *
+ * Handed to `serve()`, which discards it on a loopback bind — beside `cors`,
+ * `allowedHostnames` and `meterUnauthenticated`, because it is the same kind of
+ * fact about the same address.
+ */
+export function deployedReadDeps(input: {
+  readonly primary: Runtime;
+  readonly profiles: () => ReadonlyMap<string, ProfileRuntime>;
+  readonly log: Logger;
+  readonly version: string;
+}): ReadDeps {
+  const { primary, log } = input;
+
+  return {
+    workspace: primary.target,
+    profiles: input.profiles,
+    audit: primary.audit,
+    connections: async () =>
+      (await readConnections(primary.resolution.workspaceRoot)).connections,
+    // Cached, unlike loopback's. `GcpSecretManagerStore` holds nothing between
+    // calls, so a dashboard polling `/state` would be one network round trip per
+    // poll and a stranger sending a wrong token one per request — which is the
+    // ADR-054 hazard exactly: a costly read performed for a caller who has
+    // presented nothing valid.
+    credential: cachedPairingCredential({
+      read: () => primary.credentials.get(PAIR_TOKEN_REF),
+      refresh: () => primary.credentials.refresh?.(),
+      onError: (reason) => log.warn('could not read the pairing credential', { reason }),
+    }),
+    endpoint: { kind: 'deployed', version: input.version, certificateExpiresAt: null },
+    log,
+  };
+}

package/src/server/read/listener.ts

@@ -0,0 +1,54 @@
+import { readRoutes, type ReadDeps } from './routes.ts';
+
+/**
+ * The read surface on loopback: its own port, over TLS (ADR-063).
+ *
+ * The routes themselves live in `./routes.ts`, shared with the deployed bind,
+ * so the four properties they enforce cannot come to differ between the two.
+ * What is decided *here* is the fifth, and it is the one that is genuinely
+ * about this bind rather than about the routes:
+ *
+ * **TLS.** Not for confidentiality on a loopback socket, but because Safari
+ * will not let an HTTPS page fetch `http://127.0.0.1` and offers no header,
+ * flag or opt-in that changes it. Without this the surface does not exist for a
+ * Safari user. It is also the whole reason for a second port: the MCP listener
+ * must keep answering `http://127.0.0.1:7337` for every registration that
+ * already exists.
+ *
+ * A deployed workspace needs none of this — Cloud Run terminates TLS with a
+ * certificate a browser already trusts, and routes exactly one port — so it
+ * takes the routes through the endpoint's own router instead. See
+ * `./deployed.ts`.
+ */
+
+export { READ_ORIGINS, type AuditTail, type ReadDeps } from './routes.ts';
+
+export interface ReadListenerOptions extends ReadDeps {
+  readonly host: string;
+  readonly port: number;
+  readonly tls: { readonly cert: string; readonly key: string };
+}
+
+export interface RunningReadListener {
+  readonly url: string;
+  stop(): Promise<void>;
+}
+
+export function serveRead(options: ReadListenerOptions): RunningReadListener {
+  const server = Bun.serve({
+    hostname: options.host,
+    port: options.port,
+    tls: { cert: options.tls.cert, key: options.tls.key },
+    // Everything, because this owns a whole port. The router on the deployed
+    // side passes only what `isReadPath` matched — handing an unmatched path to
+    // `readRoutes` there would swallow `/mcp`.
+    fetch: (request) => readRoutes(request, options),
+  });
+
+  return {
+    // The port the kernel assigned, not the one that was asked for. They differ
+    // whenever `port: 0` is passed, and a URL naming 0 is one nothing can reach.
+    url: `https://${options.host}:${server.port}`,
+    stop: () => server.stop(true),
+  };
+}

package/src/server/read/open.ts

@@ -0,0 +1,101 @@
+import { X509Certificate } from 'node:crypto';
+import { PAIR_CERT_REF, PAIR_KEY_REF, PAIR_TOKEN_REF, readConnections } from '#profile';
+import type { Runtime } from '#cli/runtime.ts';
+import type { Logger } from '#connectivity';
+import type { RunningServer } from '../index.ts';
+import type { ProfileRuntime } from '../mcp/visibility.ts';
+import { directPairingCredential } from './credential.ts';
+import { serveRead, type RunningReadListener } from './listener.ts';
+
+/**
+ * The dashboard's read surface on loopback, if this workspace has been paired.
+ *
+ * Absent by default and absent for every workspace that has not run
+ * `lanes link pair`, which is the whole shape of ADR-063: a browser origin
+ * reaching loopback is a grant somebody makes deliberately, not a property of
+ * running an endpoint. All three pieces must be present — the token and both
+ * halves of the certificate — because a partial pairing would bind a port
+ * serving something no browser will connect to.
+ *
+ * Bound one above the MCP port, and a failure to bind is reported rather than
+ * fatal: the endpoint is what the operator ran this for, and refusing to serve
+ * it because a second port is occupied would be the wrong trade.
+ */
+export async function openReadListener(
+  primary: Runtime,
+  server: RunningServer,
+  profiles: () => ReadonlyMap<string, ProfileRuntime>,
+  log: Logger,
+  version: string,
+): Promise<RunningReadListener | null> {
+  // Loopback only, and checked before a single credential is read.
+  //
+  // A second TLS listener one port above the endpoint is a loopback-only
+  // object: Cloud Run routes exactly one port, so there is nowhere for it to
+  // bind. Reading the three refs regardless meant a deployed revision asked
+  // Secret Manager for secrets no IAM binding covered — and Secret Manager
+  // answers a missing binding with 403 rather than 404, so the rejection
+  // escaped this function's try block, which wraps only `serveRead`, and the
+  // revision never went healthy.
+  //
+  // A deployed workspace now serves the same routes through the endpoint's own
+  // router (`./deployed.ts`), which reads no credential at boot at all — so
+  // that failure cannot recur there by construction, and `readableRefs` binds
+  // the token so the read itself stops being a rejection.
+  const bound = new URL(server.url);
+  if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(bound.hostname)) return null;
+
+  const [token, cert, key] = await Promise.all([
+    primary.credentials.get(PAIR_TOKEN_REF),
+    primary.credentials.get(PAIR_CERT_REF),
+    primary.credentials.get(PAIR_KEY_REF),
+  ]);
+
+  if (token === null || cert === null || key === null) return null;
+
+  try {
+    return serveRead({
+      host: bound.hostname,
+      port: Number(bound.port) + 1,
+      workspace: primary.target,
+      profiles,
+      audit: primary.audit,
+      connections: async () =>
+        (await readConnections(primary.resolution.workspaceRoot)).connections,
+      // Read on every presentation, so `pair --rotate` takes effect on a
+      // running endpoint. Affordable here because the store is a local file;
+      // the deployed bind caches for exactly this reason. `refresh()` drops the
+      // store's decrypted copy first, because the rotation was written by a
+      // different process.
+      credential: directPairingCredential({
+        read: () => primary.credentials.get(PAIR_TOKEN_REF),
+        refresh: () => primary.credentials.refresh?.(),
+        onError: (reason) => log.warn('could not read the pairing credential', { reason }),
+      }),
+      endpoint: { kind: 'local', version, certificateExpiresAt: expiryOf(cert) },
+      tls: { cert, key },
+    });
+  } catch (error) {
+    log.warn('could not serve the dashboard read surface', {
+      port: Number(bound.port) + 1,
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * When the pairing certificate stops working, as an ISO instant.
+ *
+ * `null` rather than a throw for a certificate that cannot be parsed: the
+ * surface it protects is already serving by the time anyone reads this, and
+ * refusing to answer `/state` because an expiry could not be formatted would
+ * take down the working thing to report on the broken one.
+ */
+function expiryOf(certificate: string): string | null {
+  try {
+    return new X509Certificate(certificate).validToDate.toISOString();
+  } catch {
+    return null;
+  }
+}