@lanes-sh/link 0.7.2 → 0.8.0

package/src/server/mcp/guide.ts

@@ -0,0 +1,120 @@
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+
+/**
+ * The long form of what this endpoint is, served as a resource.
+ *
+ * `initialize.instructions` has a budget it pays on every request forever, so it
+ * carries only the habits that must arrive everywhere. This is the document a
+ * client reads once when it wants the whole account, and it is served always,
+ * without a tool grant, because it describes the surface rather than exposing
+ * any of it.
+ *
+ * **Why a resource rather than a longer `instructions`.** A client caches
+ * `initialize` for the life of its registration, so guidance improved after
+ * somebody connected never reaches them. A resource is fetched when it is read,
+ * so this can be corrected without anybody reconnecting.
+ *
+ * **No vendor may be named here.** `src/architecture.test.ts` forbids it
+ * anywhere under `server/`, and rightly: what an owner has connected is theirs,
+ * and prose naming one provider would be wrong for everybody else.
+ */
+
+export const GUIDE_URI = 'lanes://instructions';
+
+export const GUIDE_TITLE = 'How this endpoint works';
+
+/**
+ * The document.
+ *
+ * Fixed prose, deliberately: it describes the model rather than this workspace,
+ * and the per-principal facts are in `initialize.instructions`, which is
+ * computed. Two documents with different lifetimes, and mixing them would make
+ * this one wrong the moment a connection was added.
+ */
+export function guideDocument(): string {
+  return `# Lanes Link
+
+One endpoint in front of everything its owner has chosen to expose. It
+authenticates, applies permissions per call, and records what happened.
+
+## The three words
+
+**Connection.** One authorised account or store, named \`<provider>.<id>\`. It
+belongs to the workspace, so the same account can be reached from more than one
+profile without being authorised twice.
+
+**Profile.** A selection of connections, with the capabilities allowed on each,
+and the people who may consume it. This is how someone keeps work and personal
+apart, and how they hand you one mailbox read-only while another is writable.
+
+**Workspace.** Where connections and profiles live, and which credential store
+opens them. You never name one; the endpoint you are talking to is already in it.
+
+## Routing
+
+Every tool takes \`profile\` and \`connection\`. Both are enums, and both are
+already narrowed to what you may reach, so anything offered is something you are
+allowed to use.
+
+**When it is ambiguous which profile is meant, ask.** Do not default to whichever
+is listed first. A profile is a boundary somebody drew on purpose, and crossing
+it is the failure this design exists to prevent.
+
+A connection belongs to a profile. Naming one from a different profile is
+refused, and the refusal lists what is available where you asked.
+
+## The owner's own material
+
+${RESERVED_PROVIDER_IDS.join(', ')} are not third-party services. They are the
+owner's own stores, and each is a connection like any other, so a profile decides
+which instances it can reach and what it may do with them.
+
+**Memory and tasks are different stores.** Search memory before concluding you do
+not know something about this person or their work. A thing to *do* is a task,
+and it has a status; "remember to..." is a task, not a memory. Both are served
+back to every later session, so write when asked rather than by habit.
+
+**Skills are the owner's procedures**, surfaced as prompts rather than tools.
+That is deliberate: a procedure is selected by the person, not chosen by the
+model, and you cannot read one's body. If a task has a skill for it, say so and
+let them invoke it rather than improvising your own version.
+
+**Vault values are credentials.** Use one to do the thing that needs it. Do not
+quote it back, summarise it, or write it anywhere.
+
+**Entities are the people, companies and projects this owner deals with.** Before
+using anyone's address or handle, look them up. A lookup returns every match and
+never chooses: more than one means ask which is meant, not take the first.
+
+## What is set up is answerable
+
+Before saying something cannot be reached, or that an account must be added, ask
+the setup surface. It reports what exists and what is missing, and it gives the
+exact command for the missing thing.
+
+**Running that command is the owner's to do, and inventing one is not.** Every
+change to what exists here is a command a person runs; nothing on this surface
+adds a connection, edits a profile, or changes who may consume it. That is not an
+omission to work around.
+
+## When a call is refused
+
+A refusal is information, not an obstacle. Three kinds, and they mean different
+things:
+
+- **The profile is not available.** You are not a member of it. Nothing you can
+  do; its owner adds you.
+- **The connection is not part of this profile.** Look at what is, in the enum.
+- **The capability is denied.** The profile allows a narrower set than the tool
+  suggests. Say what was refused and let the owner decide whether to widen it.
+
+Retrying a refusal unchanged produces the same refusal and one more line in the
+owner's audit log.
+
+## Files are named, not carried
+
+Where a tool takes attachments, give a path, an HTTPS URL, or an attachment
+already on another message. Do not base64 a file into an argument: it is recorded
+in the audit log, and the log is something the owner reads.
+`;
+}

package/src/server/mcp/instructions.ts

@@ -53,7 +53,7 @@ import type { MergedCapability } from './visibility.ts';
  */
 const OPENING = `This endpoint is one place to reach what its owner has chosen to expose. It
 authenticates, applies permissions, and records what happened, so you do not
-have to.`;
+have to. Read \`lanes://instructions\` for the whole account of how it works.`;
 
 const ROUTING = `**Routing.** Every tool takes \`profile\` and \`connection\`. A profile is how
 someone separates work from personal — when it is ambiguous which one is meant,

package/src/server/mcp/prompts.ts

@@ -1,3 +1,5 @@
+import { forProfile } from '#auth';
+import { clientLabelFrom } from './client-info.ts';
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { isPromptResult } from '#connectivity';
@@ -48,17 +50,19 @@ export function registerPrompt(
       description: describeWithConnections(capability.description, entry.reachable),
       argsSchema: z.object(shape),
     },
-    async (args: Record<string, unknown>) => {
+    async (args: Record<string, unknown>, extra?: unknown) => {
       const { profile, connection, ...rest } = args;
       const scope = resolveScope(entry, profile, connection);
       if ('error' in scope) throw new Error(scope.error);
 
+      const label = clientLabelFrom(extra) ?? options.clientLabel;
+
       const outcome = await options.profiles.get(scope.profile)!.dispatcher.invoke({
-        principal: options.principal,
+        principal: forProfile(options.principal, scope.profile),
         capabilityId: id,
         connectionKey: scope.connectionKey,
         arguments: rest,
-        clientLabel: options.clientLabel,
+        ...(label ? { clientLabel: label } : {}),
       });
 
       // A prompt has no `isError` to carry a refusal in, so a denial is a

package/src/server/mcp/resources.ts

@@ -1,3 +1,5 @@
+import { forProfile } from '#auth';
+import { clientLabelFrom } from './client-info.ts';
 import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/server';
 import { isResourceListResult, isResourceResult } from '#connectivity';
 import type { DispatchOutcome } from '#dispatch';
@@ -28,14 +30,20 @@ export function registerResource(
       const scope = { profile, connectionId };
       const scoped = scopeResourceUri(capability.uriTemplate, scope);
 
-      const dispatch = (args: Record<string, unknown>): Promise<DispatchOutcome> =>
-        runtime.dispatcher.invoke({
-          principal: options.principal,
+      const dispatch = (
+        args: Record<string, unknown>,
+        extra?: unknown,
+      ): Promise<DispatchOutcome> => {
+        const label = clientLabelFrom(extra) ?? options.clientLabel;
+
+        return runtime.dispatcher.invoke({
+          principal: forProfile(options.principal, profile),
           capabilityId: id,
           connectionKey,
           arguments: args,
-          clientLabel: options.clientLabel,
+          ...(label ? { clientLabel: label } : {}),
         });
+      };
 
       const metadata = {
         description: `${capability.description} (${profile}: ${connectionKey})`,
@@ -44,8 +52,8 @@ export function registerResource(
 
       // `uri` is the whole argument — the provider recovers its own template
       // variables from it and never sees the routing segments core prepended.
-      const read = async (uri: URL) => {
-        const outcome = await dispatch({ uri: uri.href });
+      const read = async (uri: URL, _variables?: unknown, extra?: unknown) => {
+        const outcome = await dispatch({ uri: uri.href }, extra);
         if (!outcome.ok) throw new Error(outcome.message);
         if (!isResourceResult(outcome.result)) {
           throw new Error(`${id} did not return resource contents`);
@@ -83,8 +91,8 @@ export function registerResource(
           // rather than an oversight. A provider omits `list` when its resource
           // space is unbounded.
           list: capability.list
-            ? async () => {
-                const outcome = await dispatch({});
+            ? async (extra?: unknown) => {
+                const outcome = await dispatch({}, extra);
                 if (!outcome.ok) throw new Error(outcome.message);
                 if (!isResourceListResult(outcome.result)) return { resources: [] };
 

package/src/server/mcp/tools.ts

@@ -1,6 +1,8 @@
+import { forProfile } from '#auth';
 import { fromJsonSchema, type McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { isToolResult } from '#connectivity';
+import { clientLabelFrom } from './client-info.ts';
 import { toolNameFor } from './naming.ts';
 import { resourceLinkRouter } from './routing.ts';
 import { sanitizeSchema } from './schema.ts';
@@ -111,9 +113,13 @@ export function registerLocalTool(
 function makeHandler(capabilityId: string, entry: MergedCapability, options: BuildServerOptions) {
   // `unknown` because the JSON-Schema overload types it that way; the schema
   // has already validated the shape by the time this runs.
-  return async (args: unknown) => {
+  return async (args: unknown, extra?: unknown) => {
     const { profile, connection, ...rest } = (args ?? {}) as Record<string, unknown>;
 
+    // The request first, then whatever the transport knew before the call —
+    // which on a stateless POST is nothing, and is why the request is asked.
+    const label = clientLabelFrom(extra) ?? options.clientLabel;
+
     const name = String(profile);
     const runtime = options.profiles.get(name);
     const reachable = entry.reachable.get(name);
@@ -147,11 +153,11 @@ function makeHandler(capabilityId: string, entry: MergedCapability, options: Bui
     }
 
     const outcome = await runtime.dispatcher.invoke({
-      principal: options.principal,
+      principal: forProfile(options.principal, name),
       capabilityId,
       connectionKey: String(connection),
       arguments: rest,
-      clientLabel: options.clientLabel,
+      ...(label ? { clientLabel: label } : {}),
     });
 
     if (!outcome.ok) {

package/src/server/mcp/visibility.ts

@@ -3,8 +3,9 @@ import type { Principal } from '#auth';
 import type { Config } 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.
@@ -25,7 +26,7 @@ export interface ProfileRuntime {
   readonly config: Config;
   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 +73,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 +103,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()) {

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