@lanes-sh/link 0.7.1 → 0.8.0

package/src/server/endpoint.ts

@@ -1,21 +1,16 @@
-import { MCP_PATH, serve } from './index.ts';
+import { MCP_PATH, serve, type RunningServer } from './index.ts';
 import { serveOverStdio } from './stdio.ts';
 import { Generations, type OpenedWorkspace } from './generations.ts';
 import type { AuthorizationSurface } from './oauth.ts';
 import type { ProfileRuntime } from './mcp/index.ts';
-import {
-  AuthenticatorChain,
-  IssuedTokenAuthenticator,
-  OAuthServer,
-  OAuthStore,
-  OidcAuthenticator,
-  OidcVerifier,
-  tokensMatch,
-  type Authenticator,
-} from '#auth';
+import { AuthenticatorChain } from '#auth';
+import { openAuthorization } from './authorization.ts';
+import { openReadListener } from './read/open.ts';
+import { deployedReadDeps } from './read/deployed.ts';
+import { version } from '#cli/version.ts';
 import type { Logger } from '#connectivity';
 import { silentLogger } from './logging.ts';
-import { listProfiles } from '#profile';
+import { listProfiles, readConnections } from '#profile';
 import {
   applyReconcile,
   formatPlan,
@@ -82,6 +77,8 @@ export interface EndpointOptions {
 export interface RunningEndpoint {
   readonly url: string;
   readonly profiles: readonly string[];
+  /** The dashboard read surface, when this workspace is paired (ADR-063). */
+  readonly readUrl?: string | undefined;
   stop(): Promise<void>;
 }
 
@@ -133,21 +130,33 @@ async function openReconciled(options: {
       }
     }
 
-    for (const [name, runtime] of runtimes) {
-      const result = await planReconcile(
-        runtime.config,
-        runtime.state,
-        runtime.credentials,
-        runtime.manifestFor,
-      );
-      if (!planIsNoop(result)) {
-        reporter.reconciled({
-          profile: name,
-          plan: formatPlan(result),
-          ofMany: runtimes.size > 1,
-        });
-        await applyReconcile(runtime.config, runtime.state, result);
-      }
+    // Once for the workspace, over every connection the workspace holds.
+    //
+    // Runtime state is one store per workspace since contract 3, and reconcile
+    // disables everything in it that the connection list does not declare — so
+    // running it per profile over that profile's *grants* had each pass disable
+    // the connections only the other profiles granted. Two profiles was enough:
+    // the second pass disabled the first's accounts, every later call was
+    // refused `denied_connection_unauthorized`, and restarting flipped which
+    // profile survived.
+    //
+    // The primary's runtime is used for the stores because they are the same
+    // stores for every profile here. `workspaceConnections` is the whole list,
+    // which is what "undeclared" has to be measured against.
+    const declared = primary.workspaceConnections;
+    const result = await planReconcile(
+      declared,
+      primary.state,
+      primary.credentials,
+      primary.manifestFor,
+    );
+    if (!planIsNoop(result)) {
+      reporter.reconciled({
+        profile: primary.resolution.profile,
+        plan: formatPlan(result),
+        ofMany: false,
+      });
+      await applyReconcile(declared, primary.state, result);
     }
 
     return { primary, runtimes };
@@ -183,80 +192,6 @@ function closeAll(runtimes: ReadonlyMap<string, Runtime>): Promise<unknown> {
   return Promise.all([...runtimes.values()].map((runtime) => runtime.close()));
 }
 
-/**
- * The remote-client gate, if this profile declares one.
- *
- * Endpoint-scoped rather than per profile, like the bearer token and for the
- * same reason (ADR-009): one URL serves every profile in the workspace, so
- * there is one place a client authorises and one set of tokens.
- *
- * Returns null when `auth.authorization` is absent, and everything downstream
- * treats null as "exactly as before" — no metadata published, no pointer on the
- * `401`, one authenticator instead of a chain.
- */
-async function openAuthorization(
-  primary: Runtime,
-  log: Logger,
-): Promise<{ surface: AuthorizationSurface; authenticator: Authenticator } | null> {
-  const declared = primary.config.auth.authorization;
-  if (!declared) return null;
-
-  const profile = primary.resolution.profile;
-
-  if (declared.mode === 'oidc') {
-    const audience = await primary.credentials.get(declared.client_id_ref);
-    if (!audience) {
-      // Refuse rather than verify without an audience. A verifier that cannot
-      // check who a token was issued for accepts every token the issuer minted
-      // for anything, which is the failure this mode exists to prevent.
-      throw new Error(
-        `auth.authorization.client_id_ref names "${declared.client_id_ref}", which is not in ` +
-          `this target's credential store. Store it with: lanes link secrets set ${declared.client_id_ref}`,
-      );
-    }
-
-    const verifier = new OidcVerifier({
-      issuer: declared.issuer,
-      audience,
-      allowedSubjects: declared.allowed_subjects,
-      ...(declared.introspection_endpoint
-        ? { introspectionEndpoint: declared.introspection_endpoint }
-        : {}),
-    });
-
-    return {
-      // The issuer is somebody else's origin, so it is a constant here rather
-      // than derived from the request.
-      surface: { issuer: () => declared.issuer, mcpPath: MCP_PATH, target: primary.target },
-      authenticator: new OidcAuthenticator(verifier, profile),
-    };
-  }
-
-  const store = new OAuthStore(primary.state.kv);
-  const expected = primary.config.auth.token_ref;
-
-  const server = new OAuthServer({
-    store,
-    accessTokenTtlMs: declared.access_token_ttl_minutes * 60_000,
-    // So a replayed refresh token leaves a line. It is refused rather than
-    // acted on (ADR-035), and a refusal nobody can see is how a connector
-    // losing its authorization came to need log forensics to explain.
-    log,
-    // Approval is proof of holding the endpoint token, compared the same way
-    // the request path compares it. There is one person behind this endpoint
-    // and they already have exactly one credential; a second one invented for
-    // the consent screen would be a password to lose.
-    verifyOwner: async (presented) => {
-      const token = await primary.credentials.get(expected);
-      return token !== null && tokensMatch(presented, token);
-    },
-  });
-
-  return {
-    surface: { server, issuer: (origin) => origin, mcpPath: MCP_PATH, target: primary.target },
-    authenticator: new IssuedTokenAuthenticator(store, profile),
-  };
-}
 
 export async function startEndpoint(options: EndpointOptions): Promise<RunningEndpoint> {
   const reporter = options.reporter ?? SILENT;
@@ -278,13 +213,26 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       if (!token) {
         throw new Error(
           `No profile token at "${primary.config.auth.token_ref}" in this target's credential store. ` +
-            'A deployed instance never mints its own — run `lanes link token rotate --target <target>` ' +
+            'A deployed instance never mints its own — run `lanes link token rotate --workspace <name>` ' +
             'from your machine, or `lanes link secrets push --from local --to cloud`, then redeploy.',
         );
       }
     }
 
-    const gate = await openAuthorization(primary, log);
+    // Read through a holder rather than closed over `runtimes`, because a
+    // reload replaces that map and the gate is deliberately built once
+    // (ADR-029). Without the indirection, a member added after start would
+    // stay invisible until the endpoint was restarted — which is precisely the
+    // thing `profile members add` tells the operator has taken effect.
+    let serving: ReadonlyMap<string, Runtime> = runtimes;
+
+    const gate = await openAuthorization(primary, log, async (subject) =>
+      [...serving]
+        .filter(([, runtime]) =>
+          runtime.config.members.some((member) => member.subject === subject),
+        )
+        .map(([name]) => name),
+    );
 
     // The authenticator and the authorization gate are built once, from the
     // runtime this endpoint booted with, and are deliberately not part of what
@@ -295,6 +243,7 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       { profiles: profileRuntimes(runtimes), close: () => closeAll(runtimes).then(() => {}) },
       async (): Promise<OpenedWorkspace> => {
         const reopened = await openReconciled(options);
+        serving = reopened.runtimes;
         return {
           profiles: profileRuntimes(reopened.runtimes),
           close: () => closeAll(reopened.runtimes).then(() => {}),
@@ -312,6 +261,12 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       { primary: primary.resolution.profile, log, ...(gate ? { remoteClients: true } : {}) },
     );
 
+    // Read once. `version()` walks up to the install root and parses
+    // `package.json`; doing it per request would put a synchronous file read on
+    // the read surface's hot path to answer a value that cannot change while
+    // this process lives.
+    const runningVersion = version();
+
     const server = serve({
       generations,
       primary: primary.resolution.profile,
@@ -322,20 +277,46 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       ...(gate ? { authorization: gate.surface } : {}),
       ...(options.port !== undefined ? { port: options.port } : {}),
       ...(options.host !== undefined ? { host: options.host } : {}),
+      // Offered unconditionally and discarded by `serve()` on a loopback bind,
+      // which is where every other property of the bind address is decided. It
+      // opens nothing and reads no credential, so building it for a bind that
+      // will not use it costs a closure (ADR-064).
+      read: deployedReadDeps({
+        primary,
+        profiles: () => generations.current.profiles,
+        log,
+        version: runningVersion,
+      }),
     });
 
     // After `serve()`, so the record means the socket is bound. Recording it
     // from the constructor claimed an endpoint that a failed bind never served.
     generations.announce();
 
+    // Only when `lanes link pair` has provisioned all three. Absent, this is
+    // simply not served — the read surface is opt-in and its absence is the
+    // default (ADR-063), so an endpoint that was never paired binds one port
+    // exactly as it always did.
+    const read = await openReadListener(
+      primary,
+      server,
+      () => generations.current.profiles,
+      log,
+      runningVersion,
+    );
+
     return {
       url: server.url,
       profiles: [...runtimes.keys()],
+      ...(read ? { readUrl: read.url } : {}),
       // `server.stop()` closes the request handler, which closes whichever
       // generation is current — and a generation owns the runtimes it opened.
       // Closing `runtimes` here too would reach past a reload and close a set
       // nothing is serving from any more.
-      stop: () => server.stop(),
+      stop: async () => {
+        await read?.stop();
+        await server.stop();
+      },
     };
   } catch (error) {
     await closeAll(runtimes);

package/src/server/generation.ts

@@ -189,7 +189,16 @@ export class Generation {
    * a handler outliving its generation is the stale-config bug.
    */
   handlerFor(principal: Principal, clientLabel: string | undefined): McpHttpHandler {
-    const key = `${principal.id}\u0000${clientLabel ?? ''}`;
+    // The delegation list is part of the key, not just the identity.
+    //
+    // `Principal` gained `profiles` this release, and `mergeCapabilities` and
+    // `forProfile` both read it off the *captured* principal — so two tokens for
+    // one subject with different scopes hashed to one entry and whichever
+    // authorized first decided what the other could reach. Removing somebody
+    // from a profile and re-authorizing then served them the profile they had
+    // just lost, or refused one they still had, depending on order.
+    const reach = principal.profiles === undefined ? '*' : [...principal.profiles].sort().join(',');
+    const key = `${principal.id}\u0000${reach}\u0000${clientLabel ?? ''}`;
     const existing = this.#handlers.get(key);
     if (existing) return existing;
 

package/src/server/harness.ts

@@ -5,10 +5,11 @@ import {
   IssuedTokenAuthenticator,
   OAuthServer,
   OAuthStore,
-  tokensMatch,
+  type Federation,
 } from '#auth';
 import { oneProfile, type ProfileRuntime } from './mcp/index.ts';
-import { parseConfig, type Config } from '#profile';
+import {
+  type ConnectionConfig, parseConfig, type Config } from '#profile';
 import { ProviderRegistry, toPolicyDocument } from '#registry';
 import { Dispatcher } from '#dispatch';
 import { createMemoryCredentials, createMemoryState } from '#stores/state/testing.ts';
@@ -33,26 +34,58 @@ import { serveOverStdio } from './stdio.ts';
  * the right calls, and a mocked transport cannot demonstrate that.
  */
 
+/**
+ * The connections a harness config implies, derived from its grants.
+ *
+ * A test config declares grants and no `connections.yaml` — there is no
+ * workspace on disk to read one from. Deriving the rows from the grant refs
+ * keeps the harness honest about the only thing dispatch uses them for, which is
+ * resolving `<provider>.<id>` to a provider and an id. Anything richer (an
+ * account label, a credential ref) belongs to a real workspace and a test that
+ * needs one builds it.
+ */
+function harnessConnections(config: Config): ConnectionConfig[] {
+  return config.grants.map((grant) => {
+    const [provider = '', id = ''] = grant.connection.split('.');
+    return { provider, id, account: grant.connection };
+  });
+}
+
 export const TEST_TOKEN = 'llk_test_token_value';
 
+/** A signed-in person no profile lists. See the federation stub below. */
+export const STRANGER = 'NOBODY_LISTS_THIS_PERSON';
+
+/**
+ * A profile for the harness, from the `allow`/`deny` a test hands over.
+ *
+ * The two `example` accounts are the point: every test here is about a rule
+ * covering both, or one of them, so the harness gives each its own grant row
+ * carrying the same rules (ADR-058). That is what the flat block used to mean,
+ * which keeps every existing test asserting what it was written to assert.
+ */
 export function configFor(profile: string, port: number, policy: string): Config {
+  const rules = policy
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => `    ${line.trim()}`)
+    .join('\n');
+
+  const grant = (id: string): string =>
+    `  - connection: example.${id}\n${rules.replace(/^ {4}(allow|deny):/gm, '    $1:')}`;
+
   return parseConfig(`
-contract: 2
+contract: 3
 instance:
   profile: ${profile}
   port: ${port}
 limits:
   requests_per_minute: 1000
   upstream_calls_per_minute: 1000
-connections:
-  - id: a
-    provider: example
-    account: Scratch A
-  - id: b
-    provider: example
-    account: Scratch B
-policy:
-${policy}
+grants:
+${grant('a')}
+${grant('b')}
+members: []
 `).config;
 }
 
@@ -110,6 +143,15 @@ export interface HarnessOptions {
   refreshSkills?: (registry: ProviderRegistry) => Promise<void>;
   /** Serve the `self` authorization flow alongside the bearer token. */
   authorization?: boolean;
+  /**
+   * The identity half of that flow, stubbed.
+   *
+   * The real one talks to lanes.sh and verifies a signature; a test that
+   * exercised it would be testing `AssertionVerifier`, which has its own file
+   * and its own key pair. What a harness test is about is what the endpoint
+   * does *with* an answer, so the answer is injected.
+   */
+  federation?: Partial<Federation>;
   /**
    * What a reload re-reads, standing in for `openReconciled` over a workspace
    * this harness does not have. Throwing is how the "a failed reload keeps
@@ -162,6 +204,8 @@ export function wireProfiles(options: HarnessOptions): WiredProfiles {
 
   const dispatcher = new Dispatcher({
     config,
+    connections: harnessConnections(config),
+    oauthApps: [],
     registry,
     connectorFor: (providerId): AnyConnector | undefined => {
       const entry = registry.get(providerId);
@@ -199,6 +243,8 @@ export function wireProfiles(options: HarnessOptions): WiredProfiles {
       policy: extraPolicy,
       dispatcher: new Dispatcher({
         config: extraConfig,
+        connections: harnessConnections(extraConfig),
+        oauthApps: [],
         registry,
         connectorFor: (providerId): AnyConnector | undefined => {
           const entry = registry.get(providerId);
@@ -241,7 +287,19 @@ export function startHarness(options: HarnessOptions): Harness {
             accessTokenTtlMs: 3_600_000,
             log,
             ...(options.now ? { now: options.now } : {}),
-            verifyOwner: (presented) => Promise.resolve(tokensMatch(presented, token)),
+            federation: {
+              consentUrl: 'https://lanes.example/link/authorize',
+              // Anything non-empty verifies, as the subject it spells. Enough to
+              // drive the flow, and obviously not a verifier.
+              verify: async (assertion) =>
+                assertion ? { subject: `lanes:${assertion}`, email: null } : null,
+              // One reserved spelling answers "no profile names them", because
+              // that refusal is a real branch — a person signs in successfully
+              // and still reaches nothing — and there has to be a way to drive it.
+              profilesFor: async (subject) =>
+                subject === `lanes:${STRANGER}` ? [] : [options.profile],
+              ...options.federation,
+            },
           }),
           issuer: (origin: string) => origin,
           mcpPath: '/mcp',

package/src/server/index.ts

@@ -4,6 +4,7 @@ import { capabilityIdForToolName } from '#server/mcp';
 import { ATTACHMENTS_PATH, handleAttachments } from './attachments.ts';
 import { allowedHostnamesFor, rebindingRefusal } from './rebinding.ts';
 import { ANY_ORIGIN, corsAware, type CorsPolicy } from './cors.ts';
+import { isReadPath, readRoutes, type ReadDeps } from './read/routes.ts';
 import type { Generation } from './generation.ts';
 import type { Generations } from './generations.ts';
 import {
@@ -67,6 +68,16 @@ export interface ServerOptions {
    * — a page the owner happens to be visiting — before this would be reached.
    */
   readonly meterUnauthenticated?: boolean | undefined;
+  /**
+   * The dashboard's read surface, when this bind may serve it (ADR-064).
+   *
+   * Another property of the bind address, decided in the same lines of
+   * `serve()` as `cors` and the meter. Absent on loopback, where the TLS
+   * listener in `./read/open.ts` serves it on its own port instead — a
+   * cross-origin grant on `127.0.0.1` is what `./rebinding.ts` refuses
+   * outright, and ADR-039's rule is not being relaxed to fit this in.
+   */
+  readonly read?: ReadDeps | undefined;
 }
 
 export const MCP_PATH = '/mcp';
@@ -155,6 +166,8 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
           healthPath: HEALTH_PATH,
           isAuthorizationPath,
           authorizationEnabled: options.authorization !== undefined,
+          isReadPath,
+          readEnabled: options.read !== undefined,
         });
         if (refusal) {
           options.log.warn('rejected request', { reason: 'unauthenticated_rate' });
@@ -188,6 +201,17 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
         });
       }
 
+      // Above the 404 gate because these are deliberately not in the three-path
+      // set, and never through `options.authenticator`: the pairing token is a
+      // different credential for a different surface, and one shared check
+      // would make each able to do the other's job (ADR-063). Below the meter,
+      // because verifying one costs a credential-store read. Only what
+      // `isReadPath` matched is handed over — `readRoutes` answers everything
+      // it is given, so a wider hand-off would swallow `/mcp`.
+      if (options.read && isReadPath(url.pathname)) {
+        return await readRoutes(request, options.read);
+      }
+
       if (
         url.pathname !== MCP_PATH &&
         url.pathname !== ATTACHMENTS_PATH &&
@@ -344,8 +368,15 @@ export function serve(options: ServeOptions): RunningServer {
   const cors: CorsPolicy | undefined = loopback
     ? undefined
     : { allowedOrigins: primary.config.auth.allowed_origins ?? [ANY_ORIGIN] };
+  // The fourth property of this bind address, decided with the other three.
+  // Never on loopback: `./read/open.ts` serves it there over TLS on its own
+  // port, and a deployment-only grant that leaked onto `127.0.0.1` is exactly
+  // what ADR-039 refuses. Discarded rather than overridable, as `cors` is.
+  const read = loopback ? undefined : options.read;
+
   const handler = createRequestHandler({
     ...options,
+    ...(read ? { read } : { read: undefined }),
     // Off on loopback for the same reason `cors` is undefined there, and decided
     // here so every property of the bind address is decided together. An
     // explicit `true` wins, which is how a test drives the deployed behaviour.

package/src/server/mcp/build.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { isPrompt, isResource, isTool } from '#connectivity';
 import { SERVER_ICONS } from './icon.ts';
+import { GUIDE_TITLE, GUIDE_URI, guideDocument } from './guide.ts';
 import { serverInstructions } from './instructions.ts';
 import { SERVER_NAME } from './naming.ts';
 import { registerPrompt } from './prompts.ts';
@@ -77,12 +78,30 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
       // server — to be told nothing is there.
       capabilities: {
         tools: { listChanged: false },
-        ...(offers(merged, isResource) ? { resources: { listChanged: false } } : {}),
+        // Unconditional now: `lanes://instructions` is registered below
+        // whatever policy said, so this endpoint always has at least one
+        // resource and gating the capability on the merged set would advertise
+        // nothing while serving something.
+        resources: { listChanged: false },
         ...(offers(merged, isPrompt) ? { prompts: { listChanged: false } } : {}),
       },
     },
   );
 
+  // Always, and ahead of everything policy decided. This describes the surface
+  // rather than exposing any of it, so there is nothing here to grant — and a
+  // client whose owner has connected nothing at all still gets an account of
+  // what the thing is. It also means `resources` is advertised unconditionally,
+  // which `offers` below no longer decides on its own.
+  server.registerResource(
+    'instructions',
+    GUIDE_URI,
+    { title: GUIDE_TITLE, description: 'What this endpoint is and how to behave against it', mimeType: 'text/markdown' },
+    async (uri: URL) => ({
+      contents: [{ uri: uri.href, mimeType: 'text/markdown', text: guideDocument() }],
+    }),
+  );
+
   for (const [id, entry] of merged) {
     // Discovered first: an upstream MCP server or an OpenAPI document supplies
     // the schema, and there is no local capability object to inspect.

package/src/server/mcp/client-info.ts

@@ -0,0 +1,54 @@
+/**
+ * Which agent is calling, read off the request rather than off a header.
+ *
+ * The audit log's `clientLabel` field has always said it holds "the MCP
+ * `clientInfo` name". It did not. Over HTTP it read an `x-mcp-client` header,
+ * which is not part of MCP and which no client sends; over a pipe nothing set
+ * it at all. So the one field that exists to say *who made this call* was empty
+ * on every event this endpoint has ever written.
+ *
+ * The protocol does carry it. A client announces itself at `initialize` and the
+ * SDK repeats that announcement in every later request, in `_meta` under
+ * `io.modelcontextprotocol/clientInfo`, which the server surfaces on the
+ * request envelope. Reading it there rather than from the handshake is what
+ * makes it work at all here: streamable HTTP is stateless on this endpoint, a
+ * fresh `McpServer` is built and discarded per request (`build.ts`), and a
+ * handshake captured on one instance is gone before the next arrives.
+ *
+ * **A client that announces itself only at `initialize` and never repeats it is
+ * still anonymous**, and that is the honest outcome rather than a gap worth
+ * papering over. The SDK does not backfill the envelope from the session, so
+ * inferring one would mean this endpoint keeping its own session table to hold
+ * a field it is not allowed to trust anyway.
+ *
+ * **Self-reported, and labelled as such wherever it surfaces.** A client may
+ * call itself anything. It is recorded so a reader can see which agent made a
+ * call and is never consulted to decide what that agent may do — the same rule
+ * the field carried when it was a header, and the reason widening it is safe.
+ */
+
+/** Where the SDK puts the client's own `Implementation` on each request. */
+const CLIENT_INFO_META_KEY = 'io.modelcontextprotocol/clientInfo';
+
+/**
+ * The name the client gave for itself, or undefined.
+ *
+ * Deliberately tolerant. This is untrusted input on a path whose failure mode
+ * would otherwise be an exception inside a tool call that was going to succeed,
+ * and the worst honest outcome is the empty field that already exists.
+ */
+export function clientLabelFrom(extra: unknown): string | undefined {
+  if (typeof extra !== 'object' || extra === null) return undefined;
+
+  const request = (extra as { mcpReq?: unknown }).mcpReq;
+  if (typeof request !== 'object' || request === null) return undefined;
+
+  const envelope = (request as { envelope?: unknown }).envelope;
+  if (typeof envelope !== 'object' || envelope === null) return undefined;
+
+  const info = (envelope as Record<string, unknown>)[CLIENT_INFO_META_KEY];
+  if (typeof info !== 'object' || info === null) return undefined;
+
+  const name = (info as { name?: unknown }).name;
+  return typeof name === 'string' && name.length > 0 ? name : undefined;
+}