@lanes-sh/link 0.1.0

package/src/providers/vault/provider.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import {
+  defineLocalProvider,
+  keepKeys,
+  redaction,
+  type Capability,
+  type ProviderDefinition,
+} from '#connectivity';
+import { assertItemId, type VaultStore } from '#secrets';
+
+/**
+ * `vault` — the owner's own secret material.
+ *
+ * Three properties, each of which is a decision recorded in ADR-012:
+ *
+ * **Tools only, never resources.** Resources are listable and cacheable, and
+ * both are wrong for a secret (`docs/detailed/providers.md`).
+ *
+ * **Per-item policy through the capability name.** Each stored item gets its own
+ * read capability — `vault.get.github_token` — so `deny: [vault.get.bank]` and
+ * `allow: [vault.get.*]` are both already expressible against the policy engine
+ * exactly as it stands. The alternative was teaching policy about arguments,
+ * which `packages/core/src/config/schema.ts` warns against by name: a policy
+ * expression language is a language with its own bugs, and a bug here is the one
+ * this project cannot afford.
+ *
+ * Because capabilities are fixed for the life of a process, the item list is
+ * read from the store when the runtime is built. **An item written by
+ * `vault.put` is not readable until the endpoint restarts.** That is a feature:
+ * a write cannot hand itself a read, so granting access to a new secret is a
+ * deliberate act by the operator between two runs.
+ *
+ * There is deliberately no `vault.list`. The policy-filtered tool list *is* the
+ * listing, and it is the only one that cannot over-report — an agent granted one
+ * item cannot discover that the others exist.
+ *
+ * **A separate store and a separate encryption key.** Never `SecretStore`.
+ * See `vault-store.ts`; the store arrives as a constructor argument rather than
+ * through `ProviderContext`, because `ProviderContext` deliberately carries no
+ * path to any raw backend.
+ */
+
+export interface VaultProviderOptions {
+  readonly store: VaultStore;
+  /**
+   * Which items exist, read from the store at startup. Each becomes a
+   * `vault.get.<id>` capability.
+   *
+   * Passed in rather than read here because building a provider is synchronous
+   * and reading an encrypted file is not — and because the runtime is the right
+   * place to decide when the store is opened.
+   */
+  readonly items?: ReadonlyArray<{ id: string; description?: string }>;
+}
+
+export function createVaultProvider(options: VaultProviderOptions): ProviderDefinition {
+  const { store } = options;
+
+  // Deduplicated across connections: a capability id is provider-wide, so two
+  // connections holding an item of the same name contribute one capability. The
+  // handler still reads from the invoked connection's own namespace, so the two
+  // values never mix.
+  const items = new Map<string, string | undefined>();
+  for (const item of options.items ?? []) {
+    if (!items.has(item.id)) items.set(item.id, item.description);
+  }
+
+  const reads: Capability[] = [...items].map(([id, description]) => ({
+    kind: 'tool' as const,
+    name: `get.${id}`,
+    title: `Read vault item "${id}"`,
+    description:
+      description ??
+      `Return the stored value of vault item "${id}". Handle it as a secret: it is the owner's credential, not context to quote back.`,
+    inputSchema: z.object({}),
+    // Nothing to redact — the id is in the capability name, which the audit
+    // event records as `capability`, and there are no arguments at all.
+    async handler(_input, context) {
+      const item = await store.get(context.connection.id, id);
+      if (!item) {
+        return {
+          content: [{ type: 'text', text: `No vault item "${id}" on ${context.connection.key}.` }],
+          isError: true,
+        };
+      }
+
+      // Length rather than value: enough to tell a truncated paste from a
+      // correct one, and it never reaches the log as the value itself.
+      context.audit.annotate({ item: id, bytes: item.value.length });
+      return { content: [{ type: 'text', text: item.value }] };
+    },
+  }));
+
+  return defineLocalProvider({
+    id: 'vault',
+    name: 'Vault',
+    version: '1.0.0',
+    description:
+      "The owner's own passwords and API keys, in a store separate from the system's credentials and under a separate key. Reads are granted one item at a time.",
+
+    configSchema: z.object({}),
+    connectionSchema: z.object({}),
+
+    bundles: [
+      {
+        name: 'read',
+        description: 'Read stored items. Grant one at a time, not as a bundle.',
+        oauth_scopes: [],
+        capabilities: [...items.keys()].map((id) => `get.${id}`),
+        default: true,
+      },
+      {
+        name: 'write',
+        description: 'Store and remove items.',
+        oauth_scopes: [],
+        capabilities: ['put', 'remove'],
+      },
+    ],
+
+    capabilities: [
+      ...reads,
+
+      {
+        kind: 'tool',
+        name: 'put',
+        title: 'Store a vault item',
+        description:
+          'Store or replace a secret under an id. The item becomes readable only after the endpoint restarts, and only if policy grants "vault.get.<id>" — a write cannot grant itself a read.',
+        inputSchema: z.object({
+          id: z
+            .string()
+            .min(1)
+            .describe('Item id: lowercase letters, digits and "_". Becomes part of a capability name.'),
+          value: z.string().min(1).describe('The secret to store'),
+          description: z.string().optional().describe('What this is, for the operator'),
+        }),
+        // The id and its description are names worth recording — an audit log
+        // that cannot say *which* item was written answers very little. The
+        // value is withheld outright rather than type-marked, because
+        // `<string:40>` still discloses a secret's length. Redaction resolves
+        // before the policy decision in `dispatch.ts`, so a denied call is
+        // redacted identically to an allowed one.
+        redact: redaction({ keep: ['id', 'description'], withhold: ['value'] }),
+        async handler({ id, value, description }, context) {
+          assertItemId(id);
+          await store.put(context.connection.id, {
+            id,
+            value,
+            ...(description ? { description } : {}),
+          });
+
+          context.audit.annotate({ item: id, bytes: value.length });
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text:
+                  `Stored vault item "${id}" on ${context.connection.key}. ` +
+                  `It is not readable yet: restart the endpoint, and allow "vault.get.${id}" in policy.`,
+              },
+            ],
+          };
+        },
+      },
+
+      {
+        kind: 'tool',
+        name: 'remove',
+        title: 'Remove a vault item',
+        description: 'Delete a stored item. Its read capability disappears when the endpoint restarts.',
+        inputSchema: z.object({
+          id: z.string().min(1).describe('Item id'),
+        }),
+        redact: keepKeys('id'),
+        async handler({ id }, context) {
+          const removed = await store.delete(context.connection.id, id);
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: removed
+                  ? `Removed vault item "${id}" from ${context.connection.key}.`
+                  : `No vault item "${id}" on ${context.connection.key}.`,
+              },
+            ],
+            ...(removed ? {} : { isError: true }),
+          };
+        },
+      },
+    ],
+  });
+}

package/src/registry/index.ts

@@ -0,0 +1,36 @@
+/**
+ * What exists, and what it is called.
+ *
+ * The registry holds every provider available to a profile — built in, or
+ * declared as workspace YAML — and the capabilities each one contributes,
+ * addressed `provider.capability`. `reconcile` is the other half of the same
+ * question: the config file says what should exist, the database records what
+ * did, and reconcile makes the second match the first without ever deleting
+ * history.
+ *
+ * `policy-bridge` turns a profile's declared rules into the document
+ * `#policy` evaluates, and lives here because it is a translation of config,
+ * not a policy decision.
+ */
+
+export {
+  ProviderRegistry,
+  matchesGlob,
+  type RegisteredCapability,
+  type RegisteredProvider,
+} from './registry.ts';
+
+export {
+  applyReconcile,
+  credentialRefFor,
+  formatPlan,
+  planIsNoop,
+  planReconcile,
+  ownClientRefsFor,
+  rotatableCredentialRefsFor,
+  type AuthenticatingProviders,
+  type ReconcileAction,
+  type ReconcilePlan,
+} from './reconcile.ts';
+
+export { toPolicyDocument } from './policy-bridge.ts';

package/src/registry/policy-bridge.ts

@@ -0,0 +1,32 @@
+import type { PolicyDocument, PolicyRule } from '#policy';
+import type { Config } from '#profile';
+
+/**
+ * Turn the config's `policy` block into the document the policy engine
+ * evaluates.
+ *
+ * The config format keeps `allow` and `deny` as separate lists because that is
+ * what reads clearly in YAML; the engine wants one list carrying an effect,
+ * because evaluation must consider both together to make deny win regardless of
+ * ordering. Converting here keeps that difference from leaking either way.
+ */
+export function toPolicyDocument(config: Config): PolicyDocument {
+  const rules: PolicyRule[] = [];
+
+  for (const [effect, entries] of [
+    ['allow', config.policy.allow],
+    ['deny', config.policy.deny],
+  ] as const) {
+    for (const entry of entries) {
+      rules.push({
+        capability: entry.capability,
+        effect,
+        ...('expires_at' in entry && entry.expires_at
+          ? { expiresAt: new Date(entry.expires_at) }
+          : {}),
+      });
+    }
+  }
+
+  return { rules };
+}

package/src/registry/reconcile.ts

@@ -0,0 +1,313 @@
+import type { SecretStore } from '#secrets';
+import type { ConnectionRecord, ConnectionStatus, RuntimeState } from '#stores/state';
+import {
+  credentialRefForConnection,
+  rotatableCredentialRefs,
+  type ProviderManifest,
+} from '#connectivity';
+import type { ConnectionConfig, Config } from '#profile';
+
+/**
+ * Where a connection's credential lives.
+ *
+ * The single authority, because there used to be two that disagreed: reconcile
+ * derived `<provider>/<id>` and never read the manifest, while the request
+ * authorizer read the manifest and never derived. A provider declaring
+ * `credential_ref: mything/api_key` was therefore reported unauthorized forever
+ * — `doctor` told you to run `connect`, and `connect` did not help.
+ *
+ * The manifest answers it, and the connection's own `credential_ref` does not
+ * overrule that. It used to, and the override was reported rather than obeyed:
+ * `resolveSecretRefs` treats the field as an *addition* to what a connection may
+ * reach, and every path that actually reads a credential — the OAuth refresh,
+ * `connect`, `requirements`, `setup` — derives from the manifest and has never
+ * read it. Substituting here made the status disagree with the request in both
+ * directions: `active` on a connection whose every call 401s, and unauthorized
+ * on one that works, which is the same bug this function was written to end
+ * arriving from the other side.
+ *
+ * It is still the answer when the manifest gives none. A `local` provider
+ * authenticates with nothing, so there is no derived ref to contradict, and
+ * `resolveSecretRefs` makes this field that connection's whole allowlist —
+ * which leaves reporting whether it is present the only signal there is.
+ */
+export function credentialRefFor(
+  connection: ConnectionConfig,
+  manifest: ProviderManifest | undefined,
+): string | undefined {
+  const derived = manifest ? credentialRefForConnection(manifest, connection.id) : undefined;
+  return derived ?? connection.credential_ref;
+}
+
+/**
+ * The same question for a deploy, which needs the refs a *running* instance
+ * rewrites so it can grant them and nothing else.
+ *
+ * Deliberately not routed through `credentialRefFor`, and so deliberately blind
+ * to a hand-placed `credential_ref`: the refresh path derives from the manifest
+ * and has never read the config field, so the ref written is the derived one
+ * whatever the connection says. Granting what the config names instead would
+ * bind a secret nobody writes and leave the one that is written unbound.
+ *
+ * `#deployments` cannot import `#connectivity` — see `architecture.test.ts` —
+ * which is why the crossing happens here, next to the sibling that already
+ * makes it.
+ */
+export function rotatableCredentialRefsFor(
+  connection: ConnectionConfig,
+  manifest: ProviderManifest | undefined,
+): readonly string[] {
+  return manifest ? rotatableCredentialRefs(manifest, connection.id) : [];
+}
+
+/**
+ * The OAuth client a revision signs its refreshes with, where the profile holds one.
+ *
+ * Read-only, and only for a profile that declares the entry: the client is the
+ * operator's, shared by every connection of that vendor, and ADR-026's line is
+ * that a revision rotates what is its own and never rewrites somebody else's.
+ * So this is deliberately *not* part of `rotatableCredentialRefsFor`.
+ *
+ * These were missing, and the failure was silent in the worst way. The
+ * gcp-secret-manager adapter answers `null` only on a 404 — an *unbound* secret
+ * is a 403, which throws — so a bring-your-own Google connection on Cloud Run
+ * would serve until its access token expired and then fail every call, an hour
+ * after the revision reported healthy. A profile that authorises against a
+ * broker declares no entry and so adds nothing here, which is the arrangement
+ * this is meant to leave alone.
+ *
+ * Here rather than in `#deployments` for the reason its sibling gives: that
+ * component cannot import `#connectivity`, and this needs the manifest.
+ */
+export function ownClientRefsFor(
+  manifest: ProviderManifest | undefined,
+  oauthApps: Readonly<Record<string, { client_id_ref: string; client_secret_ref: string }>>,
+): readonly string[] {
+  if (manifest?.auth.kind !== 'oauth' || manifest.auth.registration !== 'manual') return [];
+  const app = manifest.auth.app;
+  if (!app) return [];
+
+  const declared = oauthApps[app];
+  return declared ? [declared.client_id_ref, declared.client_secret_ref] : [];
+}
+
+/**
+ * How to find a provider's manifest, so a missing `credential_ref` can derive.
+ *
+ * A lookup rather than a boolean: "does this authenticate" was never enough to
+ * answer "where does the credential live", and pretending otherwise is what let
+ * the two answers drift apart.
+ */
+export type AuthenticatingProviders = (providerId: string) => ProviderManifest | undefined;
+
+/**
+ * Reconcile declared config against runtime state.
+ *
+ * Planning and applying are separate functions over the same plan, so
+ * `lanes link plan` and `lanes link start` cannot disagree about what is about to happen. If
+ * the preview were computed differently from the mutation, the preview would
+ * eventually become a lie.
+ */
+
+export type ReconcileAction =
+  | { kind: 'create'; connection: string; displayName: string; status: ConnectionStatus }
+  | { kind: 'update'; connection: string; changes: readonly string[] }
+  | { kind: 'status'; connection: string; from: ConnectionStatus; to: ConnectionStatus; reason: string }
+  /**
+   * An undeclared connection is disabled, never deleted. Deleting it would
+   * orphan its audit history, and the log's value is precisely that it outlives
+   * the configuration that produced it.
+   */
+  | { kind: 'disable'; connection: string; reason: string }
+  | { kind: 'unchanged'; connection: string };
+
+export interface ReconcilePlan {
+  readonly actions: readonly ReconcileAction[];
+  /** Declared in config but absent from the state. */
+  readonly missingInDatabase: readonly string[];
+  /** Present in the state but no longer declared. */
+  readonly undeclared: readonly string[];
+  /** Declared connections whose credential could not be resolved. */
+  readonly unauthorized: readonly string[];
+}
+
+export function planIsNoop(plan: ReconcilePlan): boolean {
+  return plan.actions.every((action) => action.kind === 'unchanged');
+}
+
+/**
+ * Work out what reconcile would do, without touching anything.
+ *
+ * A missing credential does NOT fail: the connection is marked `unauthorized`,
+ * startup continues, and the problem surfaces in `lanes link doctor` and as an
+ * actionable error if that connection's capability is actually called. A
+ * half-configured Gmail account must not stop the other providers from serving.
+ */
+export async function planReconcile(
+  config: Config,
+  state: RuntimeState,
+  credentials: SecretStore,
+  /**
+   * Optional so tests and callers without a registry keep working: without it,
+   * only an explicit `credential_ref` is checked, which is the pre-derivation
+   * behaviour.
+   */
+  manifestFor: AuthenticatingProviders = () => undefined,
+): Promise<ReconcilePlan> {
+  const existing = new Map<string, ConnectionRecord>();
+  for (const record of await state.connections.list()) {
+    existing.set(`${record.provider}.${record.id}`, record);
+  }
+
+  const actions: ReconcileAction[] = [];
+  const missingInDatabase: string[] = [];
+  const unauthorized: string[] = [];
+  const declared = new Set<string>();
+
+  for (const connection of config.connections) {
+    const key = `${connection.provider}.${connection.id}`;
+    declared.add(key);
+
+    const ref = credentialRefFor(connection, manifestFor(connection.provider));
+    const authorized = ref
+      ? await credentials.has(ref)
+      : true; // A provider needing no credential is authorized by construction.
+
+    if (!authorized) unauthorized.push(key);
+
+    // Declaring the connection is what enables it. There is no separate
+    // `enabled` flag to disagree with the connection's own existence; to turn
+    // one off, delete it or deny its capabilities.
+    const desired: ConnectionStatus = authorized ? 'active' : 'unauthorized';
+
+    const record = existing.get(key);
+    if (!record) {
+      missingInDatabase.push(key);
+      actions.push({
+        kind: 'create',
+        connection: key,
+        displayName: connection.account,
+        status: desired,
+      });
+      continue;
+    }
+
+    const changes: string[] = [];
+    if (record.displayName !== connection.account) changes.push('account');
+
+    if (changes.length > 0) actions.push({ kind: 'update', connection: key, changes });
+
+    if (record.status !== desired) {
+      actions.push({
+        kind: 'status',
+        connection: key,
+        from: record.status,
+        to: desired,
+        reason: authorized
+          ? 'credential resolves'
+          : `credential ${ref} is missing from the credential store`,
+      });
+    } else if (changes.length === 0) {
+      actions.push({ kind: 'unchanged', connection: key });
+    }
+  }
+
+  const undeclared: string[] = [];
+  for (const [key, record] of existing) {
+    if (declared.has(key)) continue;
+    undeclared.push(key);
+    if (record.status !== 'disabled') {
+      actions.push({
+        kind: 'disable',
+        connection: key,
+        reason: 'no longer declared in config; disabled rather than deleted to preserve audit history',
+      });
+    }
+  }
+
+  return { actions, missingInDatabase, undeclared, unauthorized };
+}
+
+export async function applyReconcile(
+  config: Config,
+  state: RuntimeState,
+  plan: ReconcilePlan,
+): Promise<void> {
+  const byKey = new Map(config.connections.map((c) => [`${c.provider}.${c.id}`, c]));
+
+  for (const action of plan.actions) {
+    if (action.kind === 'unchanged') continue;
+
+    const [provider = '', id = ''] = splitConnectionKey(action.connection);
+
+    if (action.kind === 'disable') {
+      await state.connections.setStatus(provider, id, 'disabled');
+      continue;
+    }
+
+    if (action.kind === 'status') {
+      await state.connections.setStatus(provider, id, action.to);
+      continue;
+    }
+
+    const declared = byKey.get(action.connection);
+    if (!declared) continue;
+
+    await state.connections.upsert({
+      provider,
+      id,
+      displayName: declared.account,
+      status: action.kind === 'create' ? action.status : await currentStatus(state, provider, id),
+    });
+  }
+}
+
+async function currentStatus(
+  state: RuntimeState,
+  provider: string,
+  id: string,
+): Promise<ConnectionStatus> {
+  return (await state.connections.get(provider, id))?.status ?? 'active';
+}
+
+function splitConnectionKey(key: string): [string, string] {
+  const index = key.indexOf('.');
+  return index === -1 ? [key, ''] : [key.slice(0, index), key.slice(index + 1)];
+}
+
+/**
+ * Render a plan for `lanes link plan`.
+ *
+ * Reconcile disables undeclared connections, so this exists specifically so
+ * that outcome is never a surprise.
+ */
+export function formatPlan(plan: ReconcilePlan): string {
+  if (planIsNoop(plan)) return 'No changes. Runtime state matches the declared config.';
+
+  const lines: string[] = [];
+  for (const action of plan.actions) {
+    switch (action.kind) {
+      case 'create':
+        lines.push(`  + ${action.connection}  create (${action.status})`);
+        break;
+      case 'update':
+        lines.push(`  ~ ${action.connection}  update ${action.changes.join(', ')}`);
+        break;
+      case 'status':
+        lines.push(`  ~ ${action.connection}  ${action.from} -> ${action.to}  (${action.reason})`);
+        break;
+      case 'disable':
+        lines.push(`  - ${action.connection}  disable  (${action.reason})`);
+        break;
+      case 'unchanged':
+        break;
+    }
+  }
+
+  if (plan.unauthorized.length > 0) {
+    lines.push('', 'Unauthorized connections (startup continues; these will error if called):');
+    for (const key of plan.unauthorized) lines.push(`    ${key}  — run: lanes link connect ${key}`);
+  }
+
+  return lines.join('\n');
+}