@lanes-sh/link 0.1.0

package/src/server/stdio.ts

@@ -0,0 +1,192 @@
+import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/server';
+import { ownerPrincipal } from '#auth';
+import type { Logger } from '#connectivity';
+import {
+  buildMcpServer,
+  capabilityIdForToolName,
+  toolNameFor,
+  visibleCapabilities,
+  type ProfileRuntime,
+} from './mcp/index.ts';
+
+/**
+ * The stdio surface.
+ *
+ * Same registry, same policy, same audit as the HTTP endpoint — a different
+ * boundary. Over HTTP a caller proves who they are with a bearer token, because
+ * anyone who can reach the port might be anyone. Over stdio the pipe *is* the
+ * proof: this process was spawned by the client holding the other end of it, as
+ * the operator, with no port for anyone else to reach. There is nothing left to
+ * authenticate, so this path has no authenticator and no token — it serves the
+ * owner principal directly.
+ *
+ * It exists because a client can be unable to speak HTTP at all. Claude
+ * Desktop's `claude_desktop_config.json` validates each entry against
+ * `{ command, args?, env?, extensionId? }` — a `url` is not a field it has, so
+ * "point it at the endpoint" is not available and something must speak MCP on
+ * its stdin and stdout.
+ *
+ * Two differences from HTTP are worth knowing, and neither is incidental:
+ *
+ * - **The tool list is fixed for the connection.** `createMcpHandler` builds a
+ *   fresh server per request, so an HTTP caller sees a skill added a moment ago.
+ *   `serveStdio` pins one instance for the life of the pipe (the era decision is
+ *   made once, at the opening exchange), so a skill added mid-session appears on
+ *   the next launch. A client that spawns this per session — which is how they
+ *   all work — gets the current list every time it starts.
+ * - **One connection, one process.** The client owns the lifetime: it spawns the
+ *   process, and closing the pipe ends it.
+ */
+
+export interface StdioOptions {
+  /** Every profile this surface serves, keyed by name. */
+  readonly profiles: ReadonlyMap<string, ProfileRuntime>;
+  /** Which profile owns the connection — the one a call defaults to naming. */
+  readonly primary: string;
+  readonly log: Logger;
+  readonly version?: string | undefined;
+  readonly clientLabel?: string | undefined;
+  /**
+   * Bring your own transport, rather than this process's stdin and stdout.
+   *
+   * A test drives the real surface over a pair of in-memory streams with it. It
+   * is the same seam the SDK offers for serving stdio over a socket.
+   */
+  readonly transport?: Transport | undefined;
+}
+
+export interface StdioSurface {
+  /** Tears down the connection and the server instance pinned to it. */
+  close(): Promise<void>;
+}
+
+export function serveOverStdio(options: StdioOptions): StdioSurface {
+  if (!options.profiles.has(options.primary)) {
+    throw new Error(`Profile "${options.primary}" is not among those being served.`);
+  }
+
+  const principal = ownerPrincipal(options.primary);
+
+  /**
+   * Wire names this principal may see, and every capability id behind them.
+   *
+   * Computed once because the pinned instance's tool list is fixed for the
+   * connection anyway — the memoisation the HTTP path needs exists only because
+   * it rebuilds per request.
+   */
+  const visible = new Set(
+    visibleCapabilities({ profiles: options.profiles, principal }).map(toolNameFor),
+  );
+  const allCapabilityIds = [
+    ...new Set(
+      [...options.profiles.values()].flatMap((runtime) =>
+        runtime.registry.capabilities().map(({ id }) => id),
+      ),
+    ),
+  ];
+
+  const handle = serveStdio(
+    () =>
+      buildMcpServer({
+        profiles: options.profiles,
+        principal,
+        ...(options.clientLabel ? { clientLabel: options.clientLabel } : {}),
+        ...(options.version ? { version: options.version } : {}),
+      }),
+    {
+      transport: auditRefusals(options.transport ?? new StdioServerTransport(), (message) =>
+        recordRefusal(message, options, visible, allCapabilityIds),
+      ),
+      onerror: (error: Error) => options.log.error('mcp stdio error', { message: error.message }),
+    },
+  );
+
+  return { close: () => handle.close() };
+}
+
+/**
+ * A call naming a tool policy filtering hid, recorded as a refusal.
+ *
+ * The same trace the HTTP edge writes, from the only place this transport can
+ * write it. Policy-filtered discovery means an unpermitted tool is never
+ * advertised, so the protocol layer answers a call naming one before any of our
+ * code runs — and it would otherwise leave no trace at all, which is what
+ * `audit.every-invocation` in `docs/detailed/security.md` promises it does not.
+ *
+ * HTTP reads the method and target from the 2026-07-28 headers, which is exact
+ * for an envelope client and blind to a 2025-era one — a documented gap over
+ * there, and not one here. There are no headers on a pipe, so this reads the
+ * body unconditionally, which is cheap because the transport has already parsed
+ * it into a message.
+ */
+function recordRefusal(
+  message: JSONRPCMessage,
+  options: StdioOptions,
+  visible: ReadonlySet<string>,
+  allCapabilityIds: readonly string[],
+): void {
+  if (!('method' in message) || !('id' in message)) return;
+  if (message.method !== 'tools/call' && message.method !== 'prompts/get') return;
+
+  const params = (message as { params?: { name?: unknown } }).params;
+  const toolName = typeof params?.name === 'string' ? params.name : undefined;
+  if (!toolName || visible.has(toolName)) return;
+
+  // Not awaited: `onmessage` is synchronous, and holding the message back to
+  // wait on a store would delay the refusal the caller is owed. The row lands
+  // just after the error does.
+  //
+  // `resources/read` is absent for the same reason it is absent over HTTP: a
+  // concrete URI does not match a wire name, so recovering the capability id
+  // means matching it against every registered template. `resources.test.ts`
+  // asserts that gap rather than hiding it.
+  void options.profiles
+    .get(options.primary)!
+    .dispatcher.recordRefusal({
+      principal: ownerPrincipal(options.primary),
+      capabilityId: capabilityIdForToolName(toolName, allCapabilityIds),
+      ...(options.clientLabel ? { clientLabel: options.clientLabel } : {}),
+    })
+    .catch((error: Error) =>
+      options.log.warn('could not record refusal', { message: error.message }),
+    );
+}
+
+/**
+ * The transport, with a look at every inbound message on its way past.
+ *
+ * A wrapper rather than a subclass because the SDK owns the transport it is
+ * handed: it installs its own `onmessage`, starts it, and closes it. Assigning
+ * the inner transport's callbacks here and forwarding them keeps that ownership
+ * intact — the entry sees exactly what the pipe delivered, in the same order.
+ */
+function auditRefusals(inner: Transport, inspect: (message: JSONRPCMessage) => void): Transport {
+  const outer: Transport = {
+    start: () => inner.start(),
+    send: (message, sendOptions) => inner.send(message, sendOptions),
+    close: () => inner.close(),
+    ...(inner.setProtocolVersion
+      ? { setProtocolVersion: (version: string) => inner.setProtocolVersion!(version) }
+      : {}),
+    ...(inner.setSupportedProtocolVersions
+      ? {
+          setSupportedProtocolVersions: (versions: string[]) =>
+            inner.setSupportedProtocolVersions!(versions),
+        }
+      : {}),
+  };
+
+  inner.onmessage = (message, extra) => {
+    try {
+      inspect(message);
+    } catch {
+      // An audit attempt must never cost the caller their message.
+    }
+    outer.onmessage?.(message, extra);
+  };
+  inner.onclose = () => outer.onclose?.();
+  inner.onerror = (error) => outer.onerror?.(error);
+
+  return outer;
+}

package/src/stores/blobs/conformance.ts

@@ -0,0 +1,223 @@
+import { describe, expect, test } from 'bun:test';
+import { scopeBlobStore, type BlobStore } from './index.ts';
+
+/**
+ * The `BlobStore` contract, once, run against every adapter.
+ *
+ * `docs/detailed/init.md` promises that no application-layer code differs between the
+ * local and deployed targets. For blobs that promise now has a consumer —
+ * `providers/owner/src/memory.ts` stores entry bodies here — and it is only
+ * worth something if the adapters actually behave identically. A per-adapter
+ * test file cannot say so; it can only say each one passes the tests someone
+ * remembered to write for it. This suite is the assertion itself: filesystem,
+ * S3, and the in-memory store are held to one set of behaviours, and an
+ * adapter that diverges fails here rather than in production on whichever
+ * target the operator happened to deploy.
+ *
+ * Adapter-specific mechanism — write-then-rename, `.meta` sidecars,
+ * `ListObjectsV2` pagination — stays in the adapter's own test file. What
+ * lives here is behaviour every caller can rely on regardless of where it is
+ * running.
+ *
+ * Not exported from `package.json`: this imports `bun:test`, so it is
+ * reachable only by relative path from a test file, the same way `testing.ts`
+ * is kept away from application code.
+ */
+
+export interface ContractBlobStore {
+  /** A handle on this store. */
+  open(): BlobStore;
+  dispose(): Promise<void>;
+}
+
+const bytes = (text: string) => new TextEncoder().encode(text);
+const text = (data: Uint8Array | null) => (data ? new TextDecoder().decode(data) : null);
+
+export function describeBlobStoreContract(
+  name: string,
+  createStore: () => Promise<ContractBlobStore>,
+): void {
+  /** Open a fresh store, run against it, and clean up either way. */
+  const use = async (run: (store: BlobStore) => Promise<void>): Promise<void> => {
+    const handle = await createStore();
+    try {
+      await run(handle.open());
+    } finally {
+      await handle.dispose();
+    }
+  };
+
+  describe(`${name}: round trip`, () => {
+    test('stores, reads, and deletes', async () => {
+      await use(async (store) => {
+        expect(await store.get('note.txt')).toBeNull();
+        expect(await store.has('note.txt')).toBe(false);
+
+        await store.put('note.txt', bytes('hello'));
+        expect(text(await store.get('note.txt'))).toBe('hello');
+        expect(await store.has('note.txt')).toBe(true);
+
+        await store.delete('note.txt');
+        expect(await store.get('note.txt')).toBeNull();
+        expect(await store.has('note.txt')).toBe(false);
+      });
+    });
+
+    test('accepts a nested key without the caller creating anything first', async () => {
+      await use(async (store) => {
+        await store.put('a/b/c/deep.txt', bytes('deep'));
+        expect(text(await store.get('a/b/c/deep.txt'))).toBe('deep');
+      });
+    });
+
+    test('overwrites in place', async () => {
+      await use(async (store) => {
+        await store.put('one.txt', bytes('1'));
+        await store.put('one.txt', bytes('overwritten'));
+
+        expect(text(await store.get('one.txt'))).toBe('overwritten');
+        expect((await store.list()).map((entry) => entry.key)).toEqual(['one.txt']);
+      });
+    });
+
+    test('deleting something absent is not an error', async () => {
+      await use(async (store) => {
+        await store.delete('never-existed.txt');
+      });
+    });
+
+    test('round-trips binary data unchanged', async () => {
+      await use(async (store) => {
+        const data = new Uint8Array([0, 1, 2, 253, 254, 255]);
+
+        await store.put('raw.bin', data);
+        expect(await store.get('raw.bin')).toEqual(data);
+      });
+    });
+
+    test('round-trips an empty blob rather than reporting it absent', async () => {
+      await use(async (store) => {
+        await store.put('empty.bin', new Uint8Array([]));
+
+        expect(await store.has('empty.bin')).toBe(true);
+        expect(await store.get('empty.bin')).toEqual(new Uint8Array([]));
+      });
+    });
+  });
+
+  describe(`${name}: listing`, () => {
+    test('lists recursively, sorted, with forward-slash keys', async () => {
+      await use(async (store) => {
+        await store.put('one.txt', bytes('1'));
+        await store.put('nested/two.txt', bytes('22'));
+        await store.put('nested/deeper/three.txt', bytes('333'));
+
+        expect((await store.list()).map((entry) => entry.key)).toEqual([
+          'nested/deeper/three.txt',
+          'nested/two.txt',
+          'one.txt',
+        ]);
+      });
+    });
+
+    test('filters by prefix and reports sizes', async () => {
+      await use(async (store) => {
+        await store.put('a/one.txt', bytes('1'));
+        await store.put('b/two.txt', bytes('22'));
+
+        const listed = await store.list('a/');
+        expect(listed.map((entry) => entry.key)).toEqual(['a/one.txt']);
+        expect(listed[0]?.size).toBe(1);
+      });
+    });
+
+    test('reports the content type it was given', async () => {
+      await use(async (store) => {
+        await store.put('doc.txt', bytes('x'), { contentType: 'text/plain' });
+
+        const listed = await store.list();
+        expect(listed.map((entry) => entry.key)).toEqual(['doc.txt']);
+        expect(listed[0]?.contentType).toContain('text/plain');
+      });
+    });
+
+    test('listing an empty store returns nothing rather than throwing', async () => {
+      await use(async (store) => {
+        expect(await store.list()).toEqual([]);
+      });
+    });
+
+    test('a deleted blob leaves the key space', async () => {
+      await use(async (store) => {
+        await store.put('gone.txt', bytes('x'));
+        await store.delete('gone.txt');
+
+        expect(await store.list()).toEqual([]);
+      });
+    });
+  });
+
+  describe(`${name}: containment`, () => {
+    test('refuses a key that resolves outside the store root', async () => {
+      await use(async (store) => {
+        // `scopeBlobStore` rejects these earlier, but an adapter is usable
+        // directly and containment belongs where a key becomes an address.
+        await expect(store.get('../outside.txt')).rejects.toThrow(/outside the store root/);
+        await expect(store.put('a/../../outside.txt', bytes('x'))).rejects.toThrow(
+          /outside the store root/,
+        );
+        await expect(store.delete('../../etc/passwd')).rejects.toThrow(/outside the store root/);
+        await expect(store.has('../outside.txt')).rejects.toThrow(/outside the store root/);
+      });
+    });
+
+    test('refuses a key that resolves to the root itself', async () => {
+      await use(async (store) => {
+        await expect(store.get('.')).rejects.toThrow(/outside the store root/);
+      });
+    });
+
+    test('allows a traversal that stays inside, normalised', async () => {
+      await use(async (store) => {
+        // Weaker than `scopeBlobStore`'s rule on purpose: the namespace
+        // boundary refuses a `..` segment outright, an adapter only has to
+        // know where the key lands.
+        await store.put('a/../b.txt', bytes('inside'));
+
+        expect(text(await store.get('b.txt'))).toBe('inside');
+        expect((await store.list()).map((entry) => entry.key)).toEqual(['b.txt']);
+      });
+    });
+  });
+
+  describe(`${name}: composed with namespace scoping`, () => {
+    test('two connections on one store cannot see each other', async () => {
+      await use(async (base) => {
+        const a = scopeBlobStore(base, 'example/a');
+        const b = scopeBlobStore(base, 'example/b');
+
+        await a.put('note.txt', bytes('from a'));
+        await b.put('note.txt', bytes('from b'));
+
+        expect(text(await a.get('note.txt'))).toBe('from a');
+        expect(text(await b.get('note.txt'))).toBe('from b');
+        expect((await a.list()).map((entry) => entry.key)).toEqual(['note.txt']);
+        expect(await a.has('note.txt')).toBe(true);
+      });
+    });
+
+    test('deleting through one namespace leaves the other alone', async () => {
+      await use(async (base) => {
+        const a = scopeBlobStore(base, 'example/a');
+        const b = scopeBlobStore(base, 'example/b');
+
+        await a.put('note.txt', bytes('from a'));
+        await b.put('note.txt', bytes('from b'));
+        await a.delete('note.txt');
+
+        expect(await a.get('note.txt')).toBeNull();
+        expect(text(await b.get('note.txt'))).toBe('from b');
+      });
+    });
+  });
+}

package/src/stores/blobs/index.ts

@@ -0,0 +1,125 @@
+import { posix } from 'node:path';
+
+/**
+ * Blob storage.
+ *
+ * No provider consumes this in M1 or M2 — the example and Gmail read providers
+ * store no bytes. The interface and the filesystem adapter exist now because
+ * the owner layer (M3: memory attachments, vault documents) is the workload it
+ * was defined for, and because retrofitting a storage interface after
+ * providers exist is more expensive than defining it before.
+ *
+ * Do not add S3, Azure, or GCS adapters until a provider actually writes bytes.
+ */
+
+/** A blob key. Always relative to whatever namespace the caller was scoped to. */
+export type BlobKey = string;
+
+export interface BlobMetadata {
+  readonly key: BlobKey;
+  readonly size: number;
+  readonly contentType?: string;
+  readonly modifiedAt: Date;
+}
+
+export interface BlobStore {
+  put(key: BlobKey, data: Uint8Array, options?: { contentType?: string }): Promise<void>;
+  get(key: BlobKey): Promise<Uint8Array | null>;
+  has(key: BlobKey): Promise<boolean>;
+  delete(key: BlobKey): Promise<void>;
+  list(prefix?: string): Promise<BlobMetadata[]>;
+}
+
+/**
+ * Restrict a store to a key namespace.
+ *
+ * Providers never receive a raw `BlobStore`; they receive one scoped to
+ * `<provider>/<connection>`, so one connection's bytes are not addressable from
+ * another. The scoping is enforced here rather than trusted to the provider.
+ */
+export function scopeBlobStore(base: BlobStore, namespace: string): BlobStore {
+  const prefix = normaliseNamespace(namespace);
+  const scoped = (key: BlobKey): BlobKey => {
+    assertSafeKey(key);
+    return `${prefix}${key}`;
+  };
+
+  // Every method is `async` on purpose. A key-validation failure must surface
+  // as a rejected promise, matching the declared interface — if these threw
+  // synchronously, callers would have to both try/catch and .catch() the same
+  // call, and one of the two would inevitably be forgotten.
+  return {
+    async put(key, data, options) {
+      return base.put(scoped(key), data, options);
+    },
+    async get(key) {
+      return base.get(scoped(key));
+    },
+    async has(key) {
+      return base.has(scoped(key));
+    },
+    async delete(key) {
+      return base.delete(scoped(key));
+    },
+    async list(innerPrefix) {
+      const entries = await base.list(`${prefix}${innerPrefix ?? ''}`);
+      return entries.map((entry) => ({ ...entry, key: entry.key.slice(prefix.length) }));
+    },
+  };
+}
+
+function normaliseNamespace(namespace: string): string {
+  if (namespace.length === 0) throw new Error('Blob namespace must not be empty');
+  return namespace.endsWith('/') ? namespace : `${namespace}/`;
+}
+
+/**
+ * A virtual root deep enough that `..` can actually escape it.
+ *
+ * `posix.resolve('/', '../x')` clamps to `/x` — the traversal disappears
+ * instead of being caught — so resolving against `/` would silently accept
+ * every key a real store rejects.
+ */
+const CONTAINMENT_ROOT = '/blobs';
+
+/**
+ * Resolve a key to its canonical form, refusing anything that escapes the
+ * store.
+ *
+ * This is the *adapter's* containment rule, and it is deliberately not
+ * `assertSafeKey` above. That one guards the namespace boundary and so refuses
+ * a `..` segment outright, because a provider writing one has a bug worth
+ * surfacing. This one asks the weaker question an adapter has to ask — does
+ * the key, once resolved, still land inside the store — so `a/../b` normalises
+ * to `b` rather than failing.
+ *
+ * It lives here so every adapter answers identically. An operator who switches
+ * targets must not find that a key their local store refused is one their
+ * deployed store happily writes; `conformance.ts` asserts exactly that, and it
+ * can only do so if there is one rule rather than one per adapter.
+ */
+export function containedKey(key: BlobKey): BlobKey {
+  if (key.includes('\0')) throw new Error('Blob key must not contain a NUL byte');
+
+  const resolved = posix.resolve(CONTAINMENT_ROOT, key);
+  const relative = posix.relative(CONTAINMENT_ROOT, resolved);
+
+  if (relative === '' || relative === '..' || relative.startsWith('../')) {
+    throw new Error(`Blob key resolves outside the store root: ${key}`);
+  }
+  return relative;
+}
+
+/**
+ * A provider must not be able to escape its namespace with `../`, an absolute
+ * path, or a NUL byte. This is a boundary, so it throws rather than sanitising
+ * — silently rewriting a traversal attempt hides a provider bug.
+ */
+function assertSafeKey(key: BlobKey): void {
+  if (key.length === 0) throw new Error('Blob key must not be empty');
+  if (key.startsWith('/')) throw new Error(`Blob key must be relative: ${key}`);
+  if (key.includes('\0')) throw new Error('Blob key must not contain a NUL byte');
+  if (key.split('/').includes('..')) {
+    throw new Error(`Blob key must not traverse outside its namespace: ${key}`);
+  }
+}

package/src/stores/blobs/testing.ts

@@ -0,0 +1,49 @@
+/**
+ * An in-memory `BlobStore` for tests.
+ *
+ * Test-only, behind a separate entry point so application code cannot reach it
+ * by accident. The filesystem and S3 adapters are the real ones.
+ *
+ * It goes through `containedKey` like they do. A Map cannot be escaped, so
+ * containment buys it no safety — but a provider exercised against this store
+ * and shipped against a real one must not discover that a key it relies on is
+ * refused in production. `conformance.ts` holds all three to the one rule.
+ */
+
+import { containedKey, type BlobMetadata, type BlobStore } from './index.ts';
+
+export function createMemoryBlobStore(): BlobStore {
+  const blobs = new Map<string, { data: Uint8Array; contentType?: string; modifiedAt: Date }>();
+
+  return {
+    async put(key, data, options) {
+      blobs.set(containedKey(key), {
+        data,
+        ...(options?.contentType ? { contentType: options.contentType } : {}),
+        modifiedAt: new Date(),
+      });
+    },
+    async get(key) {
+      return blobs.get(containedKey(key))?.data ?? null;
+    },
+    async has(key) {
+      return blobs.has(containedKey(key));
+    },
+    async delete(key) {
+      blobs.delete(containedKey(key));
+    },
+    async list(prefix) {
+      const out: BlobMetadata[] = [];
+      for (const [key, blob] of blobs) {
+        if (prefix && !key.startsWith(prefix)) continue;
+        out.push({
+          key,
+          size: blob.data.byteLength,
+          modifiedAt: blob.modifiedAt,
+          ...(blob.contentType ? { contentType: blob.contentType } : {}),
+        });
+      }
+      return out.sort((a, b) => a.key.localeCompare(b.key));
+    },
+  };
+}