@lanes-sh/link 0.7.1 → 0.8.0

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;
+  }
+}

package/src/server/read/routes.ts

@@ -0,0 +1,247 @@
+import type { Logger } from '#connectivity';
+import type { ProfileRuntime } from '../mcp/visibility.ts';
+import type { PairingCredential } from './credential.ts';
+import { readState, type ConnectionRow, type ReadEndpoint } from './state.ts';
+
+/**
+ * The two routes a browser origin may read, and everything that guards them.
+ *
+ * One implementation, two binds. On loopback `./listener.ts` gives them a port
+ * of their own over TLS; on a deployed workspace `./deployed.ts` hands them to
+ * the endpoint's own router, because Cloud Run routes exactly one port. The
+ * split is deliberate and the sharing is the point: four of ADR-063's five
+ * properties are decided in this file, so the two surfaces cannot drift into
+ * two answers about what a pairing token may reach.
+ *
+ * Four properties, and dropping any one makes the others decorative:
+ *
+ *  - **One origin, named, never `*`.** Echoed with `Vary: Origin`. A deployment
+ *    may wildcard `/mcp` because it is already publicly reachable and a `curl`
+ *    has that reach already — but this returns every connection, every profile
+ *    and the whole audit log, and `cors.ts`'s wildcard was buying the absence of
+ *    a required setup step that does not exist here. So it is named.
+ *  - **A credential that cannot call a tool.** The pairing token, minted by
+ *    `lanes link pair`, under its own ref, rotatable on its own. It is not the
+ *    MCP bearer and not an OAuth token, and it never passes through the
+ *    endpoint's authenticator — one shared check would make each able to do the
+ *    other's job.
+ *  - **Never ambient.** An `Authorization` header the page must already hold.
+ *    No cookie, no session, so `credentials: 'include'` buys an attacker
+ *    nothing.
+ *  - **Reads only, ever.** No mutation is reachable from here at all. Editing a
+ *    profile from a browser would put control-plane mutation behind a CORS
+ *    grant, and ADR-007 does not move for a convenience.
+ *
+ * The fifth — TLS — belongs to the bind rather than to the routes, and
+ * `./listener.ts` carries it.
+ */
+
+/** Where the dashboard lives, and where it lives while somebody is building it. */
+export const READ_ORIGINS: readonly string[] = ['https://lanes.sh', 'http://localhost:3000'];
+
+export const STATE_PATH = '/state';
+export const AUDIT_PATH = '/audit';
+
+/**
+ * Whether the router should hand this path over.
+ *
+ * A predicate rather than an exported array, so the router owns no literal of
+ * its own and cannot come to disagree with the handler about which paths these
+ * are. `isAuthorizationPath` is the same shape for the same reason.
+ */
+export function isReadPath(pathname: string): boolean {
+  return pathname === STATE_PATH || pathname === AUDIT_PATH;
+}
+
+/** The most entries `/audit` will return, however many are asked for. */
+const AUDIT_CEILING = 500;
+const AUDIT_DEFAULT = 100;
+
+/**
+ * The half of the audit log this reads, declared rather than imported.
+ *
+ * `server` may not depend on `#audit`, and widening that table for one `tail`
+ * would be the wrong direction to resolve it: these routes do not know how the
+ * log is chained, stored, or verified, and nothing here should be able to find
+ * out. What they need is the last N entries, so that is what they ask for.
+ */
+export interface AuditTail {
+  tail(options?: { limit?: number }): Promise<
+    readonly {
+      readonly id: string;
+      readonly timestamp: Date;
+      readonly profile: string;
+      readonly principal: string;
+      readonly clientLabel?: string | undefined;
+      readonly provider: string;
+      readonly connection?: string | undefined;
+      readonly capability: string;
+      readonly arguments: Readonly<Record<string, unknown>>;
+      readonly authorization: string;
+      readonly status: string;
+      readonly durationMs: number;
+      readonly error?: { readonly kind: string; readonly message: string } | undefined;
+    }[]
+  >;
+}
+
+export interface ReadDeps {
+  readonly workspace: string;
+  /** The current generation's profiles, read through a thunk so a reload lands. */
+  readonly profiles: () => ReadonlyMap<string, ProfileRuntime>;
+  readonly audit: AuditTail;
+  /**
+   * The workspace's connection rows, read per request.
+   *
+   * A thunk rather than a value because a connection added while the endpoint
+   * runs should appear without a restart — the same reason `profiles` is one.
+   * Read from `connections.yaml` rather than derived from the grants, because
+   * a label and an account live on the connection and a grant carries neither.
+   */
+  readonly connections: () => Promise<readonly ConnectionRow[]>;
+  readonly credential: PairingCredential;
+  /** What this endpoint says about itself. Fixed for the life of the bind. */
+  readonly endpoint: ReadEndpoint;
+  readonly allowedOrigins?: readonly string[] | undefined;
+  readonly log?: Logger | undefined;
+}
+
+/**
+ * Answer a read request, whatever it turns out to be.
+ *
+ * This answers **every** request handed to it, including its own `404` for an
+ * unknown path — which is what lets `serveRead` pass a whole port through it.
+ * The router must therefore hand over only what `isReadPath` matched: given an
+ * unmatched path this would swallow `/mcp`.
+ */
+export async function readRoutes(request: Request, deps: ReadDeps): Promise<Response> {
+  const origins = deps.allowedOrigins ?? READ_ORIGINS;
+  const origin = request.headers.get('origin');
+  const allowed = origin !== null && origins.includes(origin);
+
+  // Answered before the credential is checked, because a preflight carries no
+  // credential — that is what it is for. It carries no data either, so
+  // answering one reveals only that something is listening, which the TCP
+  // connection already revealed.
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: allowed ? 204 : 403, headers: cors(origin, allowed) });
+  }
+
+  // Not `405`. A surface that answered "method not allowed" would be confirming
+  // to any page that a Lanes read surface is here; a page that is not the
+  // dashboard learns nothing it did not send.
+  if (request.method !== 'GET') {
+    return json({ error: 'not_found' }, 404, cors(origin, allowed));
+  }
+
+  if (origin !== null && !allowed) {
+    return json({ error: 'origin_not_allowed' }, 403, cors(origin, false));
+  }
+
+  // The header is parsed before the store is asked anything. A request carrying
+  // no bearer cannot be the dashboard, and on a deployed workspace a store read
+  // is a network call — so answering it from the request alone is the
+  // difference between a stranger costing nothing and a stranger costing a
+  // Secret Manager round trip. `BearerAuthenticator` orders itself the same way
+  // for the same reason.
+  const presented = bearer(request);
+
+  if (presented === null || !(await deps.credential.verify(presented))) {
+    return json(
+      {
+        error: 'unpaired',
+        // The page shows this verbatim. Every failure looks the same from a
+        // browser — an expired certificate, a rotated token, a listener that is
+        // not running — so the answer is always the command that fixes all of
+        // them rather than a diagnosis the page cannot make.
+        run: 'lanes link pair',
+      },
+      401,
+      cors(origin, allowed),
+    );
+  }
+
+  const url = new URL(request.url);
+
+  if (url.pathname === STATE_PATH) {
+    const rows = await deps.connections().catch(() => []);
+    return json(
+      readState(deps.workspace, deps.profiles(), rows, deps.endpoint),
+      200,
+      cors(origin, allowed),
+    );
+  }
+
+  if (url.pathname === AUDIT_PATH) {
+    const limit = Math.min(
+      Number(url.searchParams.get('limit') ?? AUDIT_DEFAULT) || AUDIT_DEFAULT,
+      AUDIT_CEILING,
+    );
+    const profile = url.searchParams.get('profile');
+
+    const events = await deps.audit.tail({ limit });
+    const shown = profile ? events.filter((event) => event.profile === profile) : events;
+
+    return json(
+      {
+        events: shown.map((event) => ({
+          id: event.id,
+          timestamp: event.timestamp.toISOString(),
+          profile: event.profile,
+          principal: event.principal,
+          clientLabel: event.clientLabel ?? null,
+          provider: event.provider,
+          connection: event.connection ?? null,
+          capability: event.capability,
+          // Already redacted where it was written. This does not redact again,
+          // and must not start to: a second rule here would be a second answer
+          // to what is sensitive, and the log's own would stop being the truth.
+          arguments: event.arguments,
+          authorization: event.authorization,
+          // Authorised and then failed is a state the four fields above cannot
+          // express, and it is the one worth seeing: a call the policy allowed
+          // and the provider refused reads as a successful call without these.
+          status: event.status,
+          durationMs: event.durationMs,
+          error: event.error ?? null,
+        })),
+      },
+      200,
+      cors(origin, allowed),
+    );
+  }
+
+  return json({ error: 'not_found' }, 404, cors(origin, allowed));
+}
+
+function bearer(request: Request): string | null {
+  const header = request.headers.get('authorization') ?? '';
+  if (!header.toLowerCase().startsWith('bearer ')) return null;
+
+  const presented = header.slice(7).trim();
+  return presented === '' ? null : presented;
+}
+
+function cors(origin: string | null, allowed: boolean): Record<string, string> {
+  // `Vary: Origin` unconditionally, including on a refusal. Without it a cache
+  // between here and the page can serve one origin's answer to another, which
+  // is the whole grant leaking through an intermediary.
+  const headers: Record<string, string> = { vary: 'Origin' };
+  if (!allowed || origin === null) return headers;
+
+  headers['access-control-allow-origin'] = origin;
+  headers['access-control-allow-headers'] = 'authorization';
+  headers['access-control-allow-methods'] = 'GET, OPTIONS';
+  headers['access-control-max-age'] = '600';
+  // Deliberately absent: `access-control-allow-credentials`. The token is sent
+  // explicitly by the page, so allowing cookies would add an ambient credential
+  // to a surface whose safety rests on there not being one.
+  return headers;
+}
+
+function json(body: unknown, status: number, headers: Record<string, string>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { ...headers, 'content-type': 'application/json', 'cache-control': 'no-store' },
+  });
+}

package/src/server/read/state.ts

@@ -0,0 +1,171 @@
+import { allowedConnections } from '#policy';
+import type { ProfileRuntime } from '../mcp/visibility.ts';
+
+/**
+ * What the dashboard is shown, assembled.
+ *
+ * Read-only by construction rather than by convention: this produces plain data
+ * and holds nothing that can mutate. Every field is something the CLI already
+ * prints — `status`, `connection list` and `profile show` in one document — so
+ * nothing here is readable that a person at this machine could not already read.
+ *
+ * **No credential is in it.** Not a connection's tokens, not a vault value, not
+ * the contents of a secret ref. What is here is the shape of the workspace:
+ * which accounts exist, which profiles select them, and what each allows.
+ */
+
+export interface ReadConnection {
+  readonly ref: string;
+  readonly provider: string;
+  readonly id: string;
+  /**
+   * The operator's own word for it, and what a reader should be shown.
+   *
+   * `gmail.ada_lovelace` is an address, not a name. A dashboard listing refs is
+   * asking somebody to read identifiers when they gave the thing a label
+   * precisely so they would not have to.
+   */
+  readonly label: string | null;
+  /** The identity the provider reported at connect time. */
+  readonly account: string | null;
+  /** Which profiles grant this connection at all. */
+  readonly profiles: readonly string[];
+}
+
+/** The connection rows as `connections.yaml` holds them. */
+export interface ConnectionRow {
+  readonly provider: string;
+  readonly id: string;
+  readonly account?: string | undefined;
+  readonly label?: string | undefined;
+}
+
+export interface ReadGrant {
+  readonly connection: string;
+  /** The capability ids reachable on it, after the floor and the profile's rules. */
+  readonly reachable: readonly string[];
+}
+
+export interface ReadProfile {
+  readonly name: string;
+  readonly description: string | null;
+  readonly grants: readonly ReadGrant[];
+  /** Subjects only. An email is a fact about a person that is not held here. */
+  readonly members: readonly { subject: string; role: string }[];
+}
+
+/**
+ * What the endpoint says about itself.
+ *
+ * Added because the dashboard now reads more than one kind of endpoint and had
+ * no way to tell which it was looking at — the page derived "local" from the
+ * fact that the only address it could reach was a loopback one, which stopped
+ * being true the moment a deployed workspace became readable.
+ *
+ * `certificateExpiresAt` is loopback's alone. ADR-063 promised that an expiry
+ * would be reported and nothing reported it; an expired certificate fails in
+ * the browser with an error the page cannot read, so the one place it can
+ * usefully appear is inside a response sent while the certificate still works.
+ * A deployed endpoint has none of its own — the platform terminates TLS — and
+ * says `null` rather than inventing one.
+ */
+export interface ReadEndpoint {
+  readonly kind: 'local' | 'deployed';
+  /** The version serving this request, so a page can say what it is reading. */
+  readonly version: string;
+  readonly certificateExpiresAt: string | null;
+}
+
+export interface ReadState {
+  readonly workspace: string;
+  readonly endpoint: ReadEndpoint;
+  readonly connections: readonly ReadConnection[];
+  readonly profiles: readonly ReadProfile[];
+}
+
+/**
+ * The workspace as the dashboard sees it.
+ *
+ * `reachable` comes from `allowedConnections`, the same call discovery and
+ * enforcement make. That is the point rather than a convenience: a dashboard
+ * that decided visibility its own way would eventually disagree with the
+ * endpoint about what a profile can do, and the version a person reads would be
+ * the wrong one.
+ */
+export function readState(
+  workspace: string,
+  profiles: ReadonlyMap<string, ProfileRuntime>,
+  rows: readonly ConnectionRow[],
+  endpoint: ReadEndpoint,
+): ReadState {
+  // The workspace's own list is the source of truth for *which connections
+  // exist*. Deriving it from the grants instead made an account that no profile
+  // grants invisible — and that is precisely the state `connect` leaves one in
+  // when it is run without `--profile`, so a freshly authorised account did not
+  // appear at all. Grants say who can reach a connection, not whether it is
+  // there.
+  const grantedBy = new Map<string, string[]>();
+  const described: ReadProfile[] = [];
+
+  for (const [name, runtime] of profiles) {
+    const grants: ReadGrant[] = [];
+
+    for (const grant of runtime.config.grants) {
+      const ref = grant.connection;
+      grantedBy.set(ref, [...(grantedBy.get(ref) ?? []), name]);
+
+      const reachable = runtime.registry
+        .capabilities()
+        .filter(
+          ({ id: capability }) =>
+            allowedConnections(capability, [ref], name, runtime.policy, runtime.floor).length > 0,
+        )
+        .map(({ id: capability }) => capability);
+
+      grants.push({ connection: ref, reachable });
+    }
+
+    described.push({
+      name,
+      description: runtime.config.description ?? null,
+      grants,
+      members: runtime.config.members.map((member) => ({
+        subject: member.subject,
+        role: member.role,
+      })),
+    });
+  }
+
+  const connections: ReadConnection[] = rows.map((row) => {
+    const ref = `${row.provider}.${row.id}`;
+    return {
+      ref,
+      provider: row.provider,
+      id: row.id,
+      label: row.label ?? null,
+      account: row.account ?? null,
+      profiles: grantedBy.get(ref) ?? [],
+    };
+  });
+
+  // A grant naming a connection the workspace no longer holds. `assertGrantsResolve`
+  // refuses this at load, so it is unreachable through the CLI — but the read
+  // surface should describe what is there rather than assume, and a row that
+  // appeared only in a grant would otherwise vanish from the listing while
+  // still governing a profile.
+  const known = new Set(connections.map((one) => one.ref));
+  for (const ref of grantedBy.keys()) {
+    if (known.has(ref)) continue;
+    const [provider = ref, id = ''] = ref.split('.');
+    connections.push({
+      ref,
+      provider,
+      id,
+      label: null,
+      account: null,
+      profiles: grantedBy.get(ref) ?? [],
+    });
+  }
+
+  return { workspace, endpoint, connections, profiles: described };
+}