@lanes-sh/link 0.1.0

package/src/server/mcp/tools.ts

@@ -0,0 +1,186 @@
+import { fromJsonSchema, type McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { isToolResult } from '#connectivity';
+import { toolNameFor } from './naming.ts';
+import { resourceLinkRouter } from './routing.ts';
+import { sanitizeSchema } from './schema.ts';
+import { describeWithConnections, type BuildServerOptions, type MergedCapability } from './visibility.ts';
+
+/**
+ * Tools — the capability kind everything else is measured against.
+ *
+ * Two registration paths and one handler. Discovered capabilities carry JSON
+ * Schema, because they come from an upstream MCP server or an OpenAPI document;
+ * local ones author Zod. Both end up as the same registered tool, with `profile`
+ * and `connection` injected either way — ADR-001 does not change just because
+ * the schema arrived differently.
+ */
+
+/** The two arguments core injects, and no provider declares. */
+function routingProperties(profiles: string[], connections: string[]): Record<string, unknown> {
+  return {
+    profile: {
+      type: 'string',
+      enum: profiles,
+      description: 'Which profile to act within',
+    },
+    connection: {
+      type: 'string',
+      enum: connections,
+      description: 'Which configured account to act on, within that profile',
+    },
+  };
+}
+
+export function registerDiscoveredTool(
+  server: McpServer,
+  id: string,
+  entry: MergedCapability,
+  options: BuildServerOptions,
+): void {
+  const discovered = entry.discovered!;
+  const profiles = [...entry.reachable.keys()];
+  const connections = [...new Set([...entry.reachable.values()].flat())];
+
+  const properties = (discovered.inputSchema['properties'] as Record<string, unknown>) ?? {};
+  const required = (discovered.inputSchema['required'] as string[]) ?? [];
+
+  server.registerTool(
+    toolNameFor(id),
+    {
+      ...(discovered.title ? { title: discovered.title } : {}),
+      description: describeWithConnections(discovered.description, entry.reachable),
+      // Spread the upstream schema rather than rebuilding it from properties
+      // and required alone. Vendors put `$defs` beside those and `$ref` into
+      // them — Linear's attachment tools do — and a rebuild drops the
+      // definitions while keeping the references, leaving a schema that cannot
+      // resolve itself. That failure only appears once a tool using it is
+      // actually registered, which is why a catch-all grant surfaced it and a
+      // read-only one never did.
+      inputSchema: fromJsonSchema(
+        sanitizeSchema({
+          ...discovered.inputSchema,
+          type: 'object',
+          properties: { ...properties, ...routingProperties(profiles, connections) },
+          required: [...required, 'profile', 'connection'],
+        }),
+      ),
+    },
+    makeHandler(id, entry, options),
+  );
+}
+
+export function registerLocalTool(
+  server: McpServer,
+  id: string,
+  entry: MergedCapability,
+  capability: Extract<NonNullable<MergedCapability['capability']>, { kind: 'tool' }>,
+  options: BuildServerOptions,
+): void {
+  const profiles = [...entry.reachable.keys()];
+  const connections = [...new Set([...entry.reachable.values()].flat())];
+  const shape = (capability.inputSchema as unknown as { shape?: z.ZodRawShape }).shape ?? {};
+
+  server.registerTool(
+    toolNameFor(id),
+    {
+      ...(capability.title ? { title: capability.title } : {}),
+      description: describeWithConnections(capability.description, entry.reachable),
+      inputSchema: {
+        ...shape,
+        // Injected by core, never declared by a provider — ADR-001. Both enums
+        // are built from resolved policy, so they double as the discovery
+        // filter.
+        profile: z.enum(profiles as [string, ...string[]]).describe('Which profile to act within'),
+        connection: z
+          .enum(connections as [string, ...string[]])
+          .describe('Which configured account to act on, within that profile'),
+      },
+    },
+    makeHandler(id, entry, options),
+  );
+}
+
+/**
+ * One tool handler, shared by local and discovered capabilities.
+ *
+ * `connection` is stripped here rather than inside a connector: it is injected
+ * by us and means nothing upstream, so forwarding it would leak our routing
+ * detail into someone else's API.
+ */
+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) => {
+    const { profile, connection, ...rest } = (args ?? {}) as Record<string, unknown>;
+
+    const name = String(profile);
+    const runtime = options.profiles.get(name);
+    const reachable = entry.reachable.get(name);
+
+    // The enums are a union across profiles, so a caller can name a valid
+    // profile and a connection that belongs to a different one. Refuse it here
+    // rather than dispatching: routing a `work` account through `personal`
+    // would cross exactly the boundary profiles exist to hold.
+    if (!runtime || !reachable) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Profile "${name}" does not offer ${capabilityId}. Available: ${[...entry.reachable.keys()].join(', ')}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!reachable.includes(String(connection))) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Connection "${String(connection)}" is not part of profile "${name}". Available there: ${reachable.join(', ')}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const outcome = await runtime.dispatcher.invoke({
+      principal: options.principal,
+      capabilityId,
+      connectionKey: String(connection),
+      arguments: rest,
+      clientLabel: options.clientLabel,
+    });
+
+    if (!outcome.ok) {
+      // A refusal is a tool error rather than a protocol error: the agent should
+      // be able to read it, explain it, and pick something else, not lose the
+      // connection.
+      return { content: [{ type: 'text' as const, text: outcome.message }], isError: true };
+    }
+
+    // A tool capability always produces a `ToolResult`; the guard is what makes
+    // that structural rather than assumed, now that dispatch can return three
+    // other shapes.
+    if (!isToolResult(outcome.result)) {
+      return {
+        content: [{ type: 'text' as const, text: `${capabilityId} is not a tool` }],
+        isError: true,
+      };
+    }
+
+    const result = outcome.result;
+    const route = resourceLinkRouter(runtime, capabilityId, name, String(connection));
+
+    return {
+      content: result.content.map((block) =>
+        block.type === 'text'
+          ? { type: 'text' as const, text: block.text }
+          : { type: 'resource_link' as const, uri: route(block.uri), name: block.name ?? block.uri },
+      ),
+      ...(result.isError ? { isError: true } : {}),
+    };
+  };
+}

package/src/server/mcp/visibility.ts

@@ -0,0 +1,132 @@
+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 { allowedConnections } from '#policy';
+
+/**
+ * What this principal can see, and therefore what gets registered at all.
+ *
+ * The server is a pure function of resolved policy: a capability the principal
+ * cannot reach on any connection is not registered, and one it can reach on some
+ * connections advertises exactly those in its `connection` enum. A client
+ * therefore cannot discover a connection it has no grant for.
+ *
+ * Discovery filtering and invocation enforcement share one implementation
+ * (`allowedConnections`, which calls the same `evaluate` the dispatcher uses).
+ * If they were computed separately they could drift, and a leak in discovery is
+ * still a leak.
+ */
+
+/** Everything one profile contributes to the endpoint. */
+export interface ProfileRuntime {
+  readonly config: Config;
+  readonly registry: ProviderRegistry;
+  readonly dispatcher: Dispatcher;
+  readonly policy: PolicyDocument;
+  readonly floor?: PolicyDocument | undefined;
+  /**
+   * Re-read the skills into `registry`, if they have changed on the store.
+   *
+   * Optional because only a served endpoint has one — a registry built to read
+   * manifests has nothing to refresh. Cheap and idempotent; the endpoint decides
+   * how often to ask (ADR-014).
+   */
+  refreshSkills?(): Promise<void>;
+}
+
+export interface BuildServerOptions {
+  /**
+   * Every profile this endpoint serves, keyed by name.
+   *
+   * One port, several profiles, and `profile` injected into each tool beside
+   * `connection`. What this trades away is worth naming: a token used to open
+   * exactly one profile, so a leaked one reached exactly one set of accounts.
+   * Now a single token reaches all of them and the *caller* chooses, which makes
+   * cross-profile access a matter of what the model decides to pass. Policy is
+   * still enforced per profile, and every call records which one.
+   */
+  readonly profiles: ReadonlyMap<string, ProfileRuntime>;
+  readonly principal: Principal;
+  /** Self-reported by the client. Recorded in audit; never used to authorize. */
+  readonly clientLabel?: string | undefined;
+  readonly version?: string;
+}
+
+/** One profile as the map the builder wants. */
+export function oneProfile(
+  name: string,
+  runtime: ProfileRuntime,
+): ReadonlyMap<string, ProfileRuntime> {
+  return new Map([[name, runtime]]);
+}
+
+function connectionsOf(runtime: ProfileRuntime): string[] {
+  return runtime.config.connections.map((connection) => `${connection.provider}.${connection.id}`);
+}
+
+/**
+ * What each profile exposes of one capability, merged.
+ *
+ * A capability is registered once even when several profiles offer it — two
+ * mailboxes are still one `gmail.users.messages.list` tool — with the profile
+ * chosen per call. `reachable` stays per profile because the connection enum
+ * must not imply that an account of one profile can be used through another.
+ */
+export interface MergedCapability {
+  readonly reachable: Map<string, string[]>;
+  readonly capability: ReturnType<ProviderRegistry['capabilities']>[number]['capability'];
+  readonly discovered: ReturnType<ProviderRegistry['capabilities']>[number]['discovered'];
+}
+
+export function mergeCapabilities(options: BuildServerOptions): Map<string, MergedCapability> {
+  const merged = new Map<string, MergedCapability>();
+
+  for (const [name, runtime] of options.profiles) {
+    const connections = connectionsOf(runtime);
+
+    for (const { id, capability, discovered } of runtime.registry.capabilities()) {
+      const reachable = allowedConnections(
+        id,
+        connections,
+        options.principal.id,
+        runtime.policy,
+        runtime.floor,
+      );
+      if (reachable.length === 0) continue;
+
+      const existing = merged.get(id);
+      if (existing) {
+        existing.reachable.set(name, reachable);
+        continue;
+      }
+
+      merged.set(id, { reachable: new Map([[name, reachable]]), capability, discovered });
+    }
+  }
+
+  return merged;
+}
+
+/** Which capability ids this principal can reach, across every profile served. */
+export function visibleCapabilities(options: BuildServerOptions): string[] {
+  return [...mergeCapabilities(options).keys()];
+}
+
+/**
+ * Say which accounts are reachable, grouped by profile.
+ *
+ * Grouped rather than flattened because the two arguments are not independent:
+ * `profile: personal` with a connection belonging to `work` is refused, and a
+ * flat list would read as though any pairing were valid.
+ */
+export function describeWithConnections(
+  description: string,
+  reachable: ReadonlyMap<string, readonly string[]>,
+): string {
+  const lines = [...reachable].map(
+    ([profile, connections]) => `  ${profile}: ${connections.join(', ')}`,
+  );
+  return `${description}\n\nAvailable connections, by profile:\n${lines.join('\n')}`;
+}

package/src/server/oauth.ts

@@ -0,0 +1,222 @@
+import {
+  authorizationServerMetadata,
+  protectedResourceMetadata,
+  type AuthorizeRequest,
+  type OAuthResult,
+  type OAuthServer,
+} from '#auth';
+import { approvalPage } from '#cli/callback-page.ts';
+
+/**
+ * The HTTP surface of the authorization flow.
+ *
+ * Its own file so the router stays a router: `index.ts` gains a delegation, the
+ * way it already delegates attachments, rather than six more branches and a
+ * form parser. It also keeps that file inside its size budget, which is the
+ * rule that would otherwise be relaxed to fit this in.
+ *
+ * Everything here is transport work — parse, dispatch, render. The decisions
+ * live in `#auth`, which is what makes the flow testable as a sequence of
+ * values rather than as a browser session.
+ */
+
+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 TOKEN_PATH = '/token';
+
+export interface AuthorizationSurface {
+  /** Present only in `self` mode; `oidc` publishes metadata and issues nothing. */
+  readonly server?: OAuthServer | undefined;
+  /** Where a client should go to get a token — this origin, or an issuer's. */
+  readonly issuer: (origin: string) => string;
+  /** The MCP endpoint path, so `resource` names what the client actually calls. */
+  readonly mcpPath: string;
+  /**
+   * The target this endpoint runs as, so the consent page can name the store its
+   * token actually lives in. Credentials are per-target, and the reader is about
+   * to run a command in a shell that resolves a target of its own — usually
+   * `local`, which is the one store a deployed endpoint's token is never in.
+   */
+  readonly target: string;
+}
+
+/** Every path this surface answers, so the router can ask before authenticating. */
+export function isAuthorizationPath(pathname: string): boolean {
+  return (
+    pathname === PROTECTED_RESOURCE_PATH ||
+    pathname.startsWith(`${PROTECTED_RESOURCE_PATH}/`) ||
+    pathname === AUTHORIZATION_SERVER_PATH ||
+    pathname === REGISTER_PATH ||
+    pathname === AUTHORIZE_PATH ||
+    pathname === TOKEN_PATH
+  );
+}
+
+/**
+ * The origin a client used to reach here.
+ *
+ * Not `request.url`, and not config. Cloud Run terminates TLS and forwards the
+ * original scheme in a header, so a URL built from the incoming request says
+ * `http` and every metadata document would name a resource no client asked for
+ * — which fails the exact-match the specification requires. Config cannot help
+ * either: the hostname carries a project hash assigned at deploy time.
+ */
+export function publicOrigin(request: Request): string {
+  const url = new URL(request.url);
+  const host = request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? url.host;
+  const proto = request.headers.get('x-forwarded-proto') ?? url.protocol.replace(':', '');
+  return `${proto}://${host}`;
+}
+
+export function resourceMetadataUrl(request: Request): string {
+  return `${publicOrigin(request)}${PROTECTED_RESOURCE_PATH}`;
+}
+
+export async function handleAuthorization(
+  request: Request,
+  surface: AuthorizationSurface,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const origin = publicOrigin(request);
+  const path = url.pathname;
+
+  // Both spellings: the bare document, and the one suffixed with the resource's
+  // own path, which is what a client probes first when the `401` pointed it
+  // nowhere. Answering both costs a comparison and removes a failure mode.
+  if (path === PROTECTED_RESOURCE_PATH || path.startsWith(`${PROTECTED_RESOURCE_PATH}/`)) {
+    return json(
+      protectedResourceMetadata({
+        resource: `${origin}${surface.mcpPath}`,
+        issuer: surface.issuer(origin),
+      }),
+    );
+  }
+
+  if (path === AUTHORIZATION_SERVER_PATH) {
+    // Only meaningful when this endpoint *is* the authorization server. Pointed
+    // at an external issuer, the client reads that issuer's document instead,
+    // and answering here with ours would send it to endpoints that do not exist.
+    if (!surface.server) return new Response('Not found', { status: 404 });
+    return json(authorizationServerMetadata(origin));
+  }
+
+  const server = surface.server;
+  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);
+  }
+
+  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,
+      );
+    }
+  }
+
+  if (path === TOKEN_PATH && request.method === 'POST') {
+    return render(
+      await server.token(new URLSearchParams(await request.text())),
+      request,
+      surface.target,
+    );
+  }
+
+  return new Response('Method not allowed', { status: 405 });
+}
+
+function render(result: OAuthResult, request: Request, target: string): Response {
+  switch (result.kind) {
+    case 'json':
+      return json(result.body, result.status);
+
+    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),
+        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;
+  }
+}
+
+async function safeJson(request: Request): Promise<unknown> {
+  try {
+    return await request.json();
+  } catch {
+    return {};
+  }
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      'content-type': 'application/json',
+      // Discovery documents are public by definition and read on every fresh
+      // connection; `no-store` on the token endpoint is the part that matters,
+      // and it is the default for a POST anyway.
+      'cache-control': 'no-store',
+    },
+  });
+}

package/src/server/rebinding.ts

@@ -0,0 +1,53 @@
+import {
+  hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  originValidationResponse,
+} from '@modelcontextprotocol/server';
+
+/**
+ * DNS-rebinding protection for a loopback endpoint.
+ *
+ * The attack this exists for needs no bug to work. An endpoint on 127.0.0.1 is
+ * reachable by any page the owner happens to be visiting: the attacker serves a
+ * short-TTL record, rebinds it to loopback, and the browser then calls this
+ * endpoint same-origin — at which point CORS stops applying and responses
+ * become readable. What it reaches is everything that answers before
+ * authentication, which is `/health`, the discovery documents, `/register`, and
+ * the `/authorize` consent form that asks for the owner's token.
+ *
+ * The check belongs here rather than in the MCP handler because the SDK's entry
+ * is documented as deliberately validation-free and expects this in front of
+ * it. The helpers are the SDK's for the same reason `quoted` is one function: a
+ * second implementation of a check is a second thing to drift.
+ *
+ * Only for loopback. A routable deployment gets nothing from this — rebinding
+ * to a public address buys an attacker no reach the address did not already
+ * give — and its hostname is assigned by the platform rather than known here,
+ * so a fixed allowlist would refuse every legitimate request instead.
+ */
+export function allowedHostnamesFor(host: string, isLoopbackHost: boolean): string[] | undefined {
+  if (!isLoopbackHost) return undefined;
+
+  // The SDK's list rather than our own `LOOPBACK` set: this one has to match
+  // what a *browser* puts in a Host header, which means `[::1]` in brackets and
+  // every `*.localhost` name, not just the three spellings we bind to.
+  const allowed = localhostAllowedHostnames();
+  return allowed.includes(host) ? allowed : [...allowed, host];
+}
+
+/**
+ * The refusal, or `undefined` to let the request through.
+ *
+ * Host and Origin answer different questions — where the request thinks it is
+ * going, and where it came from — so both are checked. A missing Origin passes
+ * by design: no non-browser client sends one, and every MCP client is one.
+ */
+export function rebindingRefusal(
+  request: Request,
+  allowedHostnames: readonly string[],
+): Response | undefined {
+  const allowed = [...allowedHostnames];
+  return (
+    hostHeaderValidationResponse(request, allowed) ?? originValidationResponse(request, allowed)
+  );
+}