@lanes-sh/link 0.1.0

package/src/registry/registry.ts

@@ -0,0 +1,240 @@
+import {
+  RESERVED_PROVIDER_IDS,
+  type Capability,
+  type DiscoveredCapability,
+  type ProviderDefinition,
+  type ProviderManifest,
+} from '#connectivity';
+
+/**
+ * The provider registry.
+ *
+ * A provider is a **manifest**. Local providers additionally carry code, so the
+ * registry holds one shape regardless of connectivity: every entry has a
+ * manifest, and `definition` is present only for `local`.
+ *
+ * Capabilities come from two places and the difference is the point of this
+ * milestone:
+ *
+ *   - **local** providers declare them in code (Zod input schemas)
+ *   - **mcp / http** providers have them **discovered** — from an upstream
+ *     server's `tools/list` or from an OpenAPI document — and cached in the
+ *     database, so a stateless instance serves without a discovery round trip
+ */
+
+export interface RegisteredProvider {
+  readonly manifest: ProviderManifest;
+  /** Present only for `local` connectors. */
+  readonly definition?: ProviderDefinition;
+  /** Where this came from, so `provider list` can distinguish shipped from yours. */
+  readonly origin: 'builtin' | 'workspace';
+}
+
+export interface RegisteredCapability {
+  /** Fully qualified: `notion.search`. What policy rules and audit events name. */
+  readonly id: string;
+  readonly provider: string;
+  /** For local providers. */
+  readonly capability?: Capability;
+  /** For discovered providers: re-derived at startup where the spec is committed, cached otherwise. */
+  readonly discovered?: DiscoveredCapability;
+}
+
+export class ProviderRegistry {
+  readonly #providers = new Map<string, RegisteredProvider>();
+  /** provider id → discovered capabilities. See `cli/runtime/discovery.ts` for where they come from. */
+  readonly #discovered = new Map<string, DiscoveredCapability[]>();
+  readonly #allowReserved: boolean;
+  #revision = 0;
+
+  constructor(options: { allowReserved?: boolean } = {}) {
+    this.#allowReserved = options.allowReserved ?? false;
+  }
+
+  /**
+   * Bumped whenever the capability set changes.
+   *
+   * The endpoint memoises work derived from this registry — which wire names it
+   * advertises, which ids exist — and those memos were computed once and could
+   * not notice a `replace`. Reading a number is cheaper than recomputing them
+   * per request and safer than assuming they never go stale.
+   */
+  get revision(): number {
+    return this.#revision;
+  }
+
+  /**
+   * `memory`, `skills`, and `vault` are refused until the owner layer ships.
+   * Reserving them costs nothing today; reclaiming a namespace after providers
+   * exist in the wild would silently change what a policy rule means.
+   */
+  register(entry: ProviderDefinition | ProviderManifest, origin: 'builtin' | 'workspace' = 'builtin'): void {
+    const manifest = 'manifest' in entry ? entry.manifest : entry;
+    const definition = 'manifest' in entry ? entry : undefined;
+
+    if (this.#providers.has(manifest.id)) {
+      throw new Error(`Provider "${manifest.id}" is already registered`);
+    }
+
+    if (!this.#allowReserved && RESERVED_PROVIDER_IDS.includes(manifest.id)) {
+      throw new Error(
+        `Provider id "${manifest.id}" is reserved for the owner layer (memory, skills, vault) and cannot be claimed.`,
+      );
+    }
+
+    this.#providers.set(manifest.id, {
+      manifest,
+      ...(definition ? { definition } : {}),
+      origin,
+    });
+    this.#revision++;
+  }
+
+  /**
+   * Swap a provider already registered under this id, keeping its origin.
+   *
+   * Only `skills` uses this, and only because each skill is its own capability:
+   * a skill written after the process started is invisible until the registry
+   * holds it, and restarting an endpoint to pick up a file is the friction
+   * ADR-014 set out to remove.
+   *
+   * **Not a general hot-reload facility.** Replacing a provider mid-flight
+   * changes what policy is evaluated against between one call and the next, so
+   * the only safe subjects are providers whose capabilities are pure data. The
+   * vault deliberately does *not* use this — see ADR-012 §3, where an item
+   * becoming readable only after a restart is the property, not the delay.
+   */
+  replace(entry: ProviderDefinition | ProviderManifest): void {
+    const manifest = 'manifest' in entry ? entry.manifest : entry;
+    const definition = 'manifest' in entry ? entry : undefined;
+
+    const existing = this.#providers.get(manifest.id);
+    if (!existing) {
+      throw new Error(`Provider "${manifest.id}" is not registered, so there is nothing to replace`);
+    }
+
+    this.#providers.set(manifest.id, {
+      manifest,
+      ...(definition ? { definition } : {}),
+      origin: existing.origin,
+    });
+    this.#revision++;
+  }
+
+  get(id: string): RegisteredProvider | undefined {
+    return this.#providers.get(id);
+  }
+
+  manifest(id: string): ProviderManifest | undefined {
+    return this.#providers.get(id)?.manifest;
+  }
+
+  has(id: string): boolean {
+    return this.#providers.has(id);
+  }
+
+  list(): RegisteredProvider[] {
+    return [...this.#providers.values()].sort((a, b) => a.manifest.id.localeCompare(b.manifest.id));
+  }
+
+  /**
+   * Load discovered capabilities for a provider, from the database cache.
+   *
+   * Discovery itself happens in the CLI at connect and refresh time. The server
+   * only ever reads what was cached, which is what keeps it stateless.
+   */
+  setDiscovered(providerId: string, capabilities: readonly DiscoveredCapability[]): void {
+    this.#discovered.set(providerId, [...capabilities]);
+  }
+
+  discovered(providerId: string): readonly DiscoveredCapability[] {
+    return this.#discovered.get(providerId) ?? [];
+  }
+
+  /**
+   * Every capability across every registered provider, fully qualified.
+   *
+   * Hand-written and discovered are added together rather than either/or. A
+   * `local` provider still has only the first and an `mcp` provider only the
+   * second, but a remote provider may now carry a handful of authored
+   * capabilities beside the ones its OpenAPI document describes — which is how a
+   * mail API gets a send that assembles MIME here, since the generic HTTP
+   * transport can only issue a JSON body and no document describes composing
+   * one.
+   *
+   * Authored wins on a name collision. The overlap is the reason to author one at
+   * all: the discovered version is the thing being replaced.
+   */
+  capabilities(): RegisteredCapability[] {
+    return this.list().flatMap((entry): RegisteredCapability[] => {
+      const providerId = entry.manifest.id;
+      const authored = entry.definition?.capabilities ?? [];
+      const names = new Set(authored.map((capability) => capability.name));
+
+      return [
+        ...authored.map((capability) => ({
+          id: `${providerId}.${capability.name}`,
+          provider: providerId,
+          capability,
+        })),
+        ...this.discovered(providerId)
+          .filter((capability) => !names.has(capability.name))
+          .map((capability) => ({
+            id: `${providerId}.${capability.name}`,
+            provider: providerId,
+            discovered: capability,
+          })),
+      ];
+    });
+  }
+
+  findCapability(id: string): RegisteredCapability | undefined {
+    return this.capabilities().find((entry) => entry.id === id);
+  }
+
+  /**
+   * Which capability ids a bundle expands to.
+   *
+   * Local bundles name capabilities exactly. Discovered bundles match by glob,
+   * because the names are not known when the manifest is written — and for
+   * `http` connectors the bundle is decided by HTTP method, so the connector
+   * assigns it during discovery rather than the manifest guessing.
+   */
+  expandBundle(providerId: string, bundleName: string): string[] {
+    const entry = this.#providers.get(providerId);
+    if (!entry) return [];
+
+    const bundle = entry.manifest.bundles?.find((candidate) => candidate.name === bundleName);
+    const discovered = this.discovered(providerId);
+
+    if (discovered.length > 0) {
+      return discovered
+        .filter((capability) =>
+          bundle
+            ? capability.bundle === bundleName ||
+              bundle.capabilities.some((pattern) => matchesGlob(pattern, capability.name))
+            : capability.bundle === bundleName,
+        )
+        .map((capability) => `${providerId}.${capability.name}`);
+    }
+
+    return (bundle?.capabilities ?? []).map((name) => `${providerId}.${name}`);
+  }
+
+  defaultBundle(providerId: string): string | undefined {
+    const manifest = this.#providers.get(providerId)?.manifest;
+    return (manifest?.bundles?.find((bundle) => bundle.default) ?? manifest?.bundles?.[0])?.name;
+  }
+}
+
+/** `*` matches any run of characters. Deliberately not a full glob dialect. */
+export function matchesGlob(pattern: string, value: string): boolean {
+  if (!pattern.includes('*')) return pattern === value;
+
+  const expression = pattern
+    .split('*')
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*');
+
+  return new RegExp(`^${expression}$`).test(value);
+}

package/src/secrets/document.ts

@@ -0,0 +1,293 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * One encrypted document, and everything that goes into keeping one.
+ *
+ * This exists because there were two of these. The system credential store and
+ * the vault had each grown their own AES-256-GCM envelope, their own
+ * write-then-rename, their own "read the key from an env var, else a sibling
+ * `.key` file, else mint one at 0600", and their own decrypt-failure message —
+ * differing in a magic string and nothing else that mattered. Two
+ * implementations of a format is two chances to get a format wrong, and the one
+ * this project cannot afford to get wrong is this one.
+ *
+ * What is *not* merged is the two stores themselves. They keep separate
+ * documents, separate keys, and separate environment variables, because that is
+ * the boundary `docs/detailed/security.md` is built on: one master secret reused across
+ * purposes turns any single compromise into a total one. Sharing the code that
+ * seals a document is the opposite of sharing the key that opens it.
+ *
+ * **The whole document is encrypted, names included.** A credential store whose
+ * key names were readable would disclose which accounts exist and how many;
+ * a vault whose item names were readable would disclose what the owner keeps.
+ */
+
+const FORMAT_VERSION = 1;
+export const KEY_BYTES = 32;
+const IV_BYTES = 12; // GCM standard; 96 bits is what the mode is specified for.
+
+interface EncryptedDocument {
+  readonly magic: string;
+  readonly version: number;
+  readonly iv: string;
+  readonly tag: string;
+  readonly ciphertext: string;
+}
+
+/**
+ * Where a document is kept.
+ *
+ * Deliberately smaller than a storage interface: read it, write it, and say what
+ * to call it in an error. Nothing about the ciphertext depends on which
+ * implementation is in use, which is what lets a target switch without the
+ * format changing.
+ */
+export interface DocumentIO {
+  /** The stored document, or null when nothing has been written yet. */
+  read(): Promise<string | null>;
+  write(text: string): Promise<void>;
+  /** Named in every error, so "could not decrypt" says which document. */
+  readonly label: string;
+  /** Where to look for the key, appended to the remediation in a decrypt error. */
+  readonly keyHint: string;
+}
+
+/** Resolve the 32-byte key, however this target supplies one. */
+export type KeySource = () => Promise<Uint8Array>;
+
+export function fileDocumentIO(path: string, keyPath: string): DocumentIO {
+  return {
+    label: path,
+    keyHint: ` or ${keyPath}`,
+
+    async read() {
+      return existsSync(path) ? readFile(path, 'utf8') : null;
+    },
+
+    async write(text) {
+      await mkdir(dirname(path), { recursive: true });
+
+      // Write-then-rename so a crash cannot leave a truncated store.
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile(temporary, text, { mode: 0o600 });
+      await rename(temporary, path);
+      await chmod(path, 0o600);
+    },
+  };
+}
+
+export function blobDocumentIO(store: BlobStore, key: string): DocumentIO {
+  return {
+    label: key,
+    keyHint: '',
+
+    async read() {
+      const bytes = await store.get(key);
+      return bytes === null ? null : new TextDecoder().decode(bytes);
+    },
+
+    async write(text) {
+      await store.put(key, new TextEncoder().encode(text), { contentType: 'application/json' });
+    },
+  };
+}
+
+/**
+ * The document as one entry in a secret store.
+ *
+ * Structurally typed rather than importing `SecretStore` from `./index.ts`,
+ * which imports this file — a type-only cycle would erase cleanly, but the two
+ * methods used are the whole of what is needed and naming them is clearer than
+ * pointing back up.
+ *
+ * The size guard is Secret Manager's payload limit. Hitting it should say what
+ * happened and what the ceiling is, rather than surfacing as a REST error from
+ * inside a write that already looked like it was going to work.
+ */
+export function secretDocumentIO(
+  store: {
+    get(ref: string): Promise<string | null>;
+    set(ref: string, value: string): Promise<void>;
+  },
+  ref: string,
+  limitBytes = 64 * 1024,
+): DocumentIO {
+  return {
+    label: ref,
+    keyHint: '',
+
+    read: () => store.get(ref),
+
+    async write(text) {
+      const size = new TextEncoder().encode(text).byteLength;
+      if (size > limitBytes) {
+        throw new Error(
+          `The vault document is ${size} bytes, over the ${limitBytes}-byte limit for one secret. ` +
+            'A vault holds keys and passwords; something much larger than that belongs in a file.',
+        );
+      }
+      await store.set(ref, text);
+    },
+  };
+}
+
+/**
+ * A key from the environment, from a sibling file, or newly minted.
+ *
+ * The order matters and so does the fallback's absence in the blob case: a file
+ * store may mint a key on first use because it can write it beside the document
+ * at 0600 and that file survives the process. A deployment has nowhere
+ * equivalent to put one — writing it beside the ciphertext it protects would
+ * encrypt nothing, and generating a fresh key per revision would make every
+ * previously stored item permanently unreadable while looking like it worked.
+ */
+export function fileKeySource(input: {
+  readonly keyPath: string;
+  readonly envVar: string;
+  readonly env: Record<string, string | undefined>;
+  readonly explicit?: Uint8Array | undefined;
+}): KeySource {
+  return async () => {
+    const explicit = explicitKey(input.explicit, input.env, input.envVar);
+    if (explicit) return explicit;
+
+    if (existsSync(input.keyPath)) {
+      const decoded = decodeKey(await readFile(input.keyPath, 'utf8'));
+      assertKeyLength(decoded, input.keyPath);
+      return decoded;
+    }
+
+    const generated = new Uint8Array(randomBytes(KEY_BYTES));
+    await mkdir(dirname(input.keyPath), { recursive: true });
+    // Written 0600 from the start rather than chmod-ed afterwards, so there is
+    // no window in which the key is world-readable.
+    await writeFile(input.keyPath, Buffer.from(generated).toString('base64'), { mode: 0o600 });
+    await chmod(input.keyPath, 0o600);
+    return generated;
+  };
+}
+
+export function envOnlyKeySource(input: {
+  readonly envVar: string;
+  readonly env: Record<string, string | undefined>;
+  readonly explicit?: Uint8Array | undefined;
+  readonly label: string;
+  /** The command that mints one, named because the caller knows which store this is. */
+  readonly remedy: string;
+}): KeySource {
+  return async () => {
+    const explicit = explicitKey(input.explicit, input.env, input.envVar);
+    if (explicit) return explicit;
+
+    throw new Error(
+      `${input.label}: ${input.envVar} is required for a blob-backed store. ` +
+        `Generate one with "${input.remedy}" and store it in the deployment's secret manager — ` +
+        'this adapter will not mint a key, because a key it generated would be lost with the ' +
+        'process and take every stored item with it.',
+    );
+  };
+}
+
+function explicitKey(
+  provided: Uint8Array | undefined,
+  env: Record<string, string | undefined>,
+  envVar: string,
+): Uint8Array | null {
+  if (provided) {
+    assertKeyLength(provided, 'the key passed to the store');
+    return provided;
+  }
+
+  const fromEnv = env[envVar];
+  if (!fromEnv) return null;
+
+  const decoded = decodeKey(fromEnv);
+  assertKeyLength(decoded, envVar);
+  return decoded;
+}
+
+export function decodeKey(value: string): Uint8Array {
+  return new Uint8Array(Buffer.from(value.trim(), 'base64'));
+}
+
+export function assertKeyLength(key: Uint8Array, source: string): void {
+  if (key.length !== KEY_BYTES) {
+    throw new Error(
+      `${source} must decode to ${KEY_BYTES} bytes, got ${key.length}. ` +
+        'Generate one with: openssl rand -base64 32',
+    );
+  }
+}
+
+/** A fresh key, base64, printed once and stored by the operator. */
+export function generateKey(): string {
+  return randomBytes(KEY_BYTES).toString('base64');
+}
+
+/** Seal a payload into the on-disk envelope. */
+export function seal(magic: string, key: Uint8Array, payload: unknown): string {
+  const iv = randomBytes(IV_BYTES); // Fresh per write; reuse under GCM is catastrophic.
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+
+  const ciphertext = Buffer.concat([
+    cipher.update(JSON.stringify(payload), 'utf8'),
+    cipher.final(),
+  ]);
+
+  const document: EncryptedDocument = {
+    magic,
+    version: FORMAT_VERSION,
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+
+  return JSON.stringify(document, null, 2);
+}
+
+/**
+ * Open a sealed document, or refuse.
+ *
+ * GCM authentication failing means the wrong key or an altered document. Both
+ * are refusals, never a partial read — a store that returned what it could
+ * decrypt would be a store an attacker can truncate.
+ */
+export function open<T>(
+  magic: string,
+  key: Uint8Array,
+  text: string,
+  io: Pick<DocumentIO, 'label' | 'keyHint'>,
+  envVar: string,
+): T {
+  const document = JSON.parse(text) as EncryptedDocument;
+
+  if (document.magic !== magic) {
+    throw new Error(`${io.label}: not a ${magic} document (found ${JSON.stringify(document.magic)}).`);
+  }
+  if (document.version !== FORMAT_VERSION) {
+    throw new Error(
+      `${io.label}: format version ${document.version}, but this build understands ${FORMAT_VERSION}.`,
+    );
+  }
+
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(document.iv, 'base64'));
+    decipher.setAuthTag(Buffer.from(document.tag, 'base64'));
+
+    const plaintext = Buffer.concat([
+      decipher.update(Buffer.from(document.ciphertext, 'base64')),
+      decipher.final(),
+    ]).toString('utf8');
+
+    return JSON.parse(plaintext) as T;
+  } catch {
+    throw new Error(
+      `${io.label}: could not decrypt. The key is wrong or the document has been modified. ` +
+        `Check ${envVar}${io.keyHint}.`,
+    );
+  }
+}

package/src/secrets/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Secrets — one component, one format, two stores that must never become one.
+ *
+ * "Secrets" means two different things here, and collapsing them is the most
+ * dangerous mistake available in this codebase:
+ *
+ *   1. **System credentials** (`./system.ts`) — OAuth refresh tokens, OAuth app
+ *      client secrets, the profile API token. These authorise the system
+ *      itself. They are NEVER reachable from MCP, in any form, for any client.
+ *      If an agent could read the Gmail refresh token it would simply call
+ *      Google directly, and the entire policy layer would become decorative.
+ *
+ *   2. **Vault items** (`./vault.ts`) — the owner's own passwords and API keys,
+ *      which an agent may legitimately be granted access to, one at a time,
+ *      under policy.
+ *
+ * They used to be two components with two implementations of the same
+ * AES-256-GCM document, two write-then-rename routines, and two copies of "read
+ * the key from an env var, else a sibling file, else mint one". That
+ * duplication was worth removing and is gone: `./document.ts` is the single
+ * format, and both stores are built on it with the same adapters.
+ *
+ * What is deliberately *not* shared is the part that matters — a separate
+ * document, a separate key, a separate environment variable. One master secret
+ * reused across purposes turns any single compromise into a total one.
+ * Two tests hold that line, each living with its own subject:
+ * `#dispatch`'s `control-plane.test.ts` asserts a `ProviderContext` has no path
+ * to a full store, and `#providers/vault`'s own test asserts that provider
+ * never so much as names one.
+ */
+
+/**
+ * A key into a secret store, e.g. `google/client_secret`, `gmail/main`,
+ * `profile/token`. Config files carry these references; never values.
+ */
+export type SecretRef = string;
+
+/** Matches `segment/segment[/segment...]`, lowercase, no traversal. */
+const SECRET_REF_PATTERN = /^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)+$/;
+
+export function isValidSecretRef(ref: string): boolean {
+  return SECRET_REF_PATTERN.test(ref);
+}
+
+export function assertValidSecretRef(ref: string): void {
+  if (!isValidSecretRef(ref)) {
+    throw new Error(
+      `Malformed secret reference: ${JSON.stringify(ref)}. ` +
+        'Expected lowercase segments separated by "/", e.g. "acme/main".',
+    );
+  }
+}
+
+/**
+ * The full store. Held by the CLI and by the dispatch layer; never handed to a
+ * provider, and never exposed through MCP.
+ *
+ * `list` returns keys only. There is no operation that enumerates values.
+ */
+export interface SecretStore {
+  get(ref: SecretRef): Promise<string | null>;
+  set(ref: SecretRef, value: string): Promise<void>;
+  has(ref: SecretRef): Promise<boolean>;
+  delete(ref: SecretRef): Promise<void>;
+  list(prefix?: string): Promise<SecretRef[]>;
+  /**
+   * Drop whatever is held in memory so the next read reaches the store.
+   *
+   * Optional because most adapters hold nothing to drop. It exists for the one
+   * caller that has to see a value it did not write itself: the endpoint
+   * checking a bearer token that `lanes link token rotate` replaced from a
+   * different process. The file adapter keeps the whole decrypted document
+   * cached, so without this a re-read is served the copy it already had.
+   */
+  refresh?(): void;
+}
+
+/**
+ * What a provider sees: read-only, and only the references belonging to the one
+ * connection it was invoked for.
+ *
+ * A Gmail provider handling `gmail.main` cannot read `gmail.side`'s refresh
+ * token, cannot read `google/client_secret` unless its connection declares it,
+ * and cannot enumerate anything.
+ */
+export interface ScopedSecrets {
+  get(ref: SecretRef): Promise<string | null>;
+  has(ref: SecretRef): Promise<boolean>;
+}
+
+/**
+ * Restrict a store to an explicit allowlist of references.
+ *
+ * Allowlist rather than prefix match: a provider's reachable secrets are exactly
+ * what its connection declares. A prefix rule would silently widen as new refs
+ * appear under the same prefix.
+ */
+export function scopeSecrets(
+  base: SecretStore,
+  allowed: readonly SecretRef[],
+): ScopedSecrets {
+  const allowlist = new Set(allowed);
+
+  const check = (ref: SecretRef): void => {
+    if (!allowlist.has(ref)) {
+      // Deliberately does not reveal whether the ref exists in the underlying
+      // store — an out-of-scope ref is indistinguishable from a missing one.
+      throw new Error(`Secret ${JSON.stringify(ref)} is not in scope for this connection`);
+    }
+  };
+
+  return {
+    async get(ref) {
+      check(ref);
+      return base.get(ref);
+    },
+    async has(ref) {
+      check(ref);
+      return base.has(ref);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The two stores
+// ---------------------------------------------------------------------------
+
+export {
+  createBlobSecretStore,
+  createFileSecretStore,
+  generateCredentialKey,
+  type BlobSecretsOptions,
+  type FileSystemSecretsOptions,
+} from './system.ts';
+
+export {
+  DEFAULT_SECRET_REF as VAULT_DOCUMENT_REF,
+  VAULT_ITEM_ID,
+  VAULT_KEY_ENV,
+  VAULT_KEY_REF,
+  assertItemId,
+  createBlobVaultStore,
+  createFileVaultStore,
+  createMemoryVaultStore,
+  createSecretVaultStore,
+  generateVaultKey,
+  type BlobVaultStoreOptions,
+  type FileVaultStoreOptions,
+  type SecretVaultStoreOptions,
+  type VaultItem,
+  type VaultStore,
+} from './vault.ts';
+
+export { generateKey, type DocumentIO } from './document.ts';