@lanes-sh/link 0.7.2 → 0.9.0

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

package/src/stores/blobs/conformance.ts

@@ -177,6 +177,25 @@ export function describeBlobStoreContract(
       });
     });
 
+    test('allows a name that merely begins with dots', async () => {
+      await use(async (store) => {
+        // Not a traversal — an ordinary name that happens to start with two
+        // dots, which a provider will hand over verbatim because it is a
+        // caller's to choose. One adapter refused these and the rest stored
+        // them, so the same workspace behaved differently depending on which
+        // target it was opened against. That is the divergence this whole
+        // suite exists to catch, and it caught nothing until there was a case
+        // for it.
+        // Distinct names, because a filesystem cannot hold `x` as a file and
+        // `x/y` beneath it at once — a real difference between an object store
+        // and a directory tree, and not the one under test here.
+        for (const key of ['..config', '...rc', '..nested/inner.txt']) {
+          await store.put(key, bytes(key));
+          expect(text(await store.get(key))).toBe(key);
+        }
+      });
+    });
+
     test('allows a traversal that stays inside, normalised', async () => {
       await use(async (store) => {
         // Weaker than `scopeBlobStore`'s rule on purpose: the namespace

package/src/stores/state/index.ts

@@ -26,6 +26,11 @@
 import type { BlobStore } from '../blobs/index.ts';
 import { keyFromEntry, namespacePrefix, objectKey } from './keys.ts';
 
+// Re-exported because the contract-3 migration has to address objects this
+// module wrote, and deriving `connections%2Ev1/gmail%2Emain.json` by hand at the
+// call site is the second spelling of an encoding that must not have two.
+export { decodeSegment, encodeSegment, objectKey } from './keys.ts';
+
 export type ConnectionStatus =
   | 'active'
   /** Declared, but its credential is missing or rejected. Does not block startup. */
@@ -94,17 +99,78 @@ export interface RuntimeState {
  * contain. The same rule keeps `audit.log` and `state.kv` out of reach in
  * `#profile`'s layout.
  */
-const CONNECTIONS = 'connections.v1';
+export const CONNECTIONS_NAMESPACE = 'connections.v1';
 const CURSORS = 'cursors.v1';
 
+/**
+ * The discovery cache, and what the endpoint's own OAuth server remembers.
+ *
+ * Both carry a `.v1` for the reason `connections.v1` and `cursors.v1` do, and
+ * here it is doing more than versioning. A provider's own keys are namespaced
+ * `<provider>/<connection>` in this same store, a provider id is
+ * `[a-z][a-z0-9_]*`, and only `custom` is refused by grammar — so while these
+ * were spelled `discovery` and `oauth/clients`, a manifest with id `discovery`
+ * or `oauth` landed inside them. That was a collision when everything shared
+ * one store; with the workspace/profile split below it would be a silent
+ * cross-profile leak, because these two route to the workspace. A dotted name
+ * is one no provider can reach.
+ */
+export const DISCOVERY_NAMESPACE = 'discovery.v1';
+export const OAUTH_NAMESPACE = 'oauth.v1';
+
+/**
+ * Whether a namespace belongs to the workspace rather than to one profile.
+ *
+ * Connection records and the discovery cache are facts about an account or a
+ * provider — a `connect` run once must read as connected from every profile —
+ * and the OAuth server is the endpoint's, not a profile's. Everything else is
+ * this profile's use of an account: its cursors, and each provider's own keys.
+ *
+ * Every name here carries a dot, so the list cannot be entered by a provider.
+ */
+export function isWorkspaceNamespace(namespace: string): boolean {
+  return (
+    namespace === CONNECTIONS_NAMESPACE ||
+    namespace === DISCOVERY_NAMESPACE ||
+    namespace === OAUTH_NAMESPACE ||
+    namespace.startsWith(`${OAUTH_NAMESPACE}/`)
+  );
+}
+
+/**
+ * Runtime state over two stores: the workspace's, and one profile's.
+ *
+ * `kv` routes on the namespace rather than being two stores the caller picks
+ * between, because the callers are providers and they do not know which of
+ * their keys are shared — nor should they. `isWorkspaceNamespace` is the whole
+ * rule, and it is closed: a namespace it does not name is the profile's.
+ *
+ * Both are required, with no default that falls back to one. A default would
+ * mean forgetting the second argument shares every profile's cursors and
+ * provider keys silently — which is the failure this split exists to remove.
+ * Passing the same store twice is still how a test that is not exercising the
+ * split says so, and it says it out loud.
+ */
 export function createRuntimeState(
   blobs: BlobStore,
+  profileBlobs: BlobStore,
   now: () => Date = () => new Date(),
 ): RuntimeState {
-  const kv = createKeyValue(blobs);
+  const workspaceKv = createKeyValue(blobs);
+  const profileKv = createKeyValue(profileBlobs);
+  const forNamespace = (namespace: string): KeyValueStore =>
+    isWorkspaceNamespace(namespace) ? workspaceKv : profileKv;
+
+  const kv: KeyValueStore = {
+    get: (namespace, key) => forNamespace(namespace).get(namespace, key),
+    set: (namespace, key, value) => forNamespace(namespace).set(namespace, key, value),
+    delete: (namespace, key) => forNamespace(namespace).delete(namespace, key),
+    keys: (namespace) => forNamespace(namespace).keys(namespace),
+    clearNamespace: (namespace) => forNamespace(namespace).clearNamespace(namespace),
+  };
 
   const readConnection = async (provider: string, id: string): Promise<ConnectionRecord | null> =>
-    decodeConnection(await kv.get(CONNECTIONS, connectionKey(provider, id)));
+    decodeConnection(await workspaceKv.get(CONNECTIONS_NAMESPACE, connectionKey(provider, id)));
 
   const connections: ConnectionRepository = {
     async upsert(record) {
@@ -116,7 +182,7 @@ export function createRuntimeState(
         createdAt: existing?.createdAt ?? now(),
         updatedAt: now(),
       };
-      await kv.set(CONNECTIONS, connectionKey(record.provider, record.id), encodeConnection(stored));
+      await workspaceKv.set(CONNECTIONS_NAMESPACE, connectionKey(record.provider, record.id), encodeConnection(stored));
       return stored;
     },
 
@@ -124,8 +190,8 @@ export function createRuntimeState(
 
     async list() {
       const records: ConnectionRecord[] = [];
-      for (const key of await kv.keys(CONNECTIONS)) {
-        const record = decodeConnection(await kv.get(CONNECTIONS, key));
+      for (const key of await workspaceKv.keys(CONNECTIONS_NAMESPACE)) {
+        const record = decodeConnection(await workspaceKv.get(CONNECTIONS_NAMESPACE, key));
         if (record) records.push(record);
       }
       return records.sort(
@@ -136,8 +202,8 @@ export function createRuntimeState(
     async setStatus(provider, id, status) {
       const existing = await readConnection(provider, id);
       if (!existing) return;
-      await kv.set(
-        CONNECTIONS,
+      await workspaceKv.set(
+        CONNECTIONS_NAMESPACE,
         connectionKey(provider, id),
         encodeConnection({ ...existing, status, updatedAt: now() }),
       );
@@ -145,8 +211,8 @@ export function createRuntimeState(
   };
 
   const cursors: CursorRepository = {
-    get: (namespace) => kv.get(CURSORS, namespace),
-    set: (namespace, cursor) => kv.set(CURSORS, namespace, cursor),
+    get: (namespace) => profileKv.get(CURSORS, namespace),
+    set: (namespace, cursor) => profileKv.set(CURSORS, namespace, cursor),
   };
 
   return { connections, kv, cursors };

package/src/stores/state/testing.ts

@@ -15,7 +15,11 @@ import { createMemoryBlobStore } from '../blobs/testing.ts';
 import { createRuntimeState, type RuntimeState } from './index.ts';
 
 export function createMemoryState(now: () => Date = () => new Date()): RuntimeState {
-  return createRuntimeState(createMemoryBlobStore(), now);
+  // The same store twice: this harness is for callers that are not exercising
+  // the workspace/profile split, and saying so explicitly is the point of
+  // `createRuntimeState` having no default.
+  const blobs = createMemoryBlobStore();
+  return createRuntimeState(blobs, blobs, now);
 }
 
 /** An in-memory credential store, for the same reason. */