@lanes-sh/link 0.1.0

package/src/audit/conformance.ts

@@ -0,0 +1,374 @@
+import { describe, expect, test } from 'bun:test';
+import type { AuditDraft, AuditStore } from './index.ts';
+
+/**
+ * One behavioural suite, run against every backing store.
+ *
+ * The same reasoning as `#stores/blobs/conformance.ts`: an operator who
+ * switches targets must not find that the log they could read locally is one
+ * their deployed target answers differently. The chain in particular is worth
+ * holding to one rule — a `verify` that passes on a filesystem and misses a
+ * tampered record in a bucket would be worse than no `verify` at all.
+ *
+ * The fixture exposes raw key access because the interesting half of this
+ * suite is what happens when somebody edits the log behind the endpoint's
+ * back, and there is no honest way to test that through the interface — the
+ * absence of a way to mutate an event is the guarantee being tested.
+ */
+export interface ContractSink {
+  open(options?: { now?: () => Date; run?: string }): AuditStore;
+  keys(): Promise<string[]>;
+  read(key: string): Promise<Uint8Array | null>;
+  write(key: string, bytes: Uint8Array): Promise<void>;
+  remove(key: string): Promise<void>;
+  dispose?(): Promise<void>;
+}
+
+function draft(overrides: Partial<AuditDraft> = {}): AuditDraft {
+  return {
+    profile: 'personal',
+    principal: 'personal:owner',
+    provider: 'gmail',
+    connection: 'gmail.main',
+    capability: 'gmail.users_messages_list',
+    arguments: { q: '<string:12>' },
+    authorization: 'allowed',
+    status: 'ok',
+    durationMs: 12,
+    ...overrides,
+  };
+}
+
+/** A clock that advances a second per call, so ordering is deterministic. */
+function ticking(start = Date.UTC(2026, 7, 12, 10, 0, 0)): () => Date {
+  let at = start;
+  return () => {
+    at += 1000;
+    return new Date(at);
+  };
+}
+
+export function describeAuditSinkContract(
+  name: string,
+  create: () => Promise<ContractSink> | ContractSink,
+): void {
+  describe(`audit sink contract: ${name}`, () => {
+    async function use(body: (fixture: ContractSink) => Promise<void>): Promise<void> {
+      const fixture = await create();
+      try {
+        await body(fixture);
+      } finally {
+        await fixture.dispose?.();
+      }
+    }
+
+    describe('writing and reading back', () => {
+      test('append stamps an id and a timestamp, and tail returns the event', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          const written = await sink.append(draft());
+
+          expect(written.id).toMatch(/^evt_/);
+          expect(written.timestamp).toBeInstanceOf(Date);
+
+          const [read] = await sink.tail();
+          expect(read?.id).toBe(written.id);
+          expect(read?.capability).toBe('gmail.users_messages_list');
+          expect(read?.timestamp.getTime()).toBe(written.timestamp.getTime());
+        });
+      });
+
+      test('tail presents oldest first', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ capability: 'one' }));
+          await sink.append(draft({ capability: 'two' }));
+          await sink.append(draft({ capability: 'three' }));
+
+          expect((await sink.tail()).map((event) => event.capability)).toEqual([
+            'one',
+            'two',
+            'three',
+          ]);
+        });
+      });
+
+      test('a limit keeps the newest, not the first written', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          for (const capability of ['one', 'two', 'three', 'four']) {
+            await sink.append(draft({ capability }));
+          }
+
+          expect((await sink.tail({ limit: 2 })).map((event) => event.capability)).toEqual([
+            'three',
+            'four',
+          ]);
+        });
+      });
+
+      test('events sharing a millisecond keep their order', async () => {
+        await use(async (fixture) => {
+          // Keys are timestamped to the millisecond and then disambiguated by a
+          // random id, so sorting by key alone leaves same-millisecond events in
+          // arbitrary order. `seq` is the tiebreaker — the job SQLite's implicit
+          // `rowid` used to do.
+          //
+          // This is not a corner case. A refusal is answered without touching a
+          // provider, so a rate-limited call and the call before it routinely
+          // land in the same millisecond, and getting this wrong hides the
+          // denial the log exists to show.
+          const frozen = new Date(Date.UTC(2026, 7, 12, 10, 0, 0, 0));
+          const sink = fixture.open({ now: () => frozen });
+
+          await sink.append(draft({ capability: 'first' }));
+          await sink.append(draft({ capability: 'second' }));
+          await sink.append(draft({ capability: 'third', authorization: 'denied_rate_limited' }));
+
+          expect((await sink.tail()).map((event) => event.capability)).toEqual([
+            'first',
+            'second',
+            'third',
+          ]);
+
+          // And a limit has to cut by that order too, not by the random half
+          // of a key: the newest is the denial.
+          expect((await sink.tail({ limit: 1 })).map((event) => event.capability)).toEqual([
+            'third',
+          ]);
+        });
+      });
+
+      test('redacted arguments survive nesting', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          const args = { query: '<string:12>', nested: { keep: 1, list: [1, 'two', null] } };
+          await sink.append(draft({ arguments: args }));
+
+          expect((await sink.tail())[0]?.arguments).toEqual(args);
+        });
+      });
+
+      test('optional fields are absent rather than null when unset', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ arguments: {} }));
+
+          const [event] = await sink.tail();
+          expect(event).not.toHaveProperty('clientLabel');
+          expect(event).not.toHaveProperty('error');
+        });
+      });
+
+      test('an error is carried through', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(
+            draft({ status: 'error', error: { kind: 'provider_error', message: 'upstream 500' } }),
+          );
+
+          expect((await sink.tail())[0]?.error).toEqual({
+            kind: 'provider_error',
+            message: 'upstream 500',
+          });
+        });
+      });
+
+      test('events written either side of midnight both come back', async () => {
+        await use(async (fixture) => {
+          // The store is date-partitioned, so a day boundary is the seam where
+          // a tail that only looked at one prefix would quietly lose half the log.
+          const times = [
+            new Date(Date.UTC(2026, 7, 12, 23, 59, 59)),
+            new Date(Date.UTC(2026, 7, 13, 0, 0, 1)),
+          ];
+          let index = 0;
+          const sink = fixture.open({ now: () => times[index++] ?? times[times.length - 1]! });
+
+          await sink.append(draft({ capability: 'before' }));
+          await sink.append(draft({ capability: 'after' }));
+
+          expect((await sink.tail()).map((event) => event.capability)).toEqual([
+            'before',
+            'after',
+          ]);
+        });
+      });
+    });
+
+    describe('filters', () => {
+      test('each predicate narrows the log', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ provider: 'gmail', capability: 'gmail.list' }));
+          await sink.append(
+            draft({ provider: 'drive', connection: 'drive.main', capability: 'drive.list' }),
+          );
+          await sink.append(
+            draft({ provider: 'vault', capability: 'vault.get', authorization: 'denied_by_policy' }),
+          );
+
+          expect((await sink.tail({ provider: 'drive' })).map((e) => e.capability)).toEqual([
+            'drive.list',
+          ]);
+          expect((await sink.tail({ connection: 'drive.main' })).map((e) => e.capability)).toEqual([
+            'drive.list',
+          ]);
+          expect((await sink.tail({ capability: 'gmail.list' })).map((e) => e.provider)).toEqual([
+            'gmail',
+          ]);
+          expect((await sink.tail({ deniedOnly: true })).map((e) => e.capability)).toEqual([
+            'vault.get',
+          ]);
+        });
+      });
+
+      test('since excludes anything older', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          const first = await sink.append(draft({ capability: 'old' }));
+          await sink.append(draft({ capability: 'new' }));
+
+          const after = new Date(first.timestamp.getTime() + 1);
+          expect((await sink.tail({ since: after })).map((e) => e.capability)).toEqual(['new']);
+        });
+      });
+    });
+
+    describe('the chain', () => {
+      test('an untouched log verifies', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          for (const capability of ['one', 'two', 'three']) {
+            await sink.append(draft({ capability }));
+          }
+
+          const report = await sink.verify();
+          expect(report.ok).toBe(true);
+          expect(report.events).toBe(3);
+          expect(report.runs).toBe(1);
+          expect(report.breaks).toEqual([]);
+        });
+      });
+
+      test('editing a record is caught', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ capability: 'one' }));
+          await sink.append(draft({ capability: 'two' }));
+          await sink.append(draft({ capability: 'three' }));
+
+          // Rewrite the middle event as though it had been allowed, which is
+          // the edit somebody covering their tracks would actually make.
+          const keys = (await fixture.keys()).filter((key) => key.endsWith('.json')).sort();
+          const target = keys[1]!;
+          const original = new TextDecoder().decode((await fixture.read(target))!);
+          await fixture.write(
+            target,
+            new TextEncoder().encode(original.replace('"two"', '"rewritten"')),
+          );
+
+          const report = await sink.verify();
+          expect(report.ok).toBe(false);
+          expect(report.breaks[0]?.kind).toBe('hash');
+        });
+      });
+
+      test('deleting a record from the middle is caught', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ capability: 'one' }));
+          await sink.append(draft({ capability: 'two' }));
+          await sink.append(draft({ capability: 'three' }));
+
+          const keys = (await fixture.keys()).filter((key) => key.endsWith('.json')).sort();
+          await fixture.remove(keys[1]!);
+
+          const report = await sink.verify();
+          expect(report.ok).toBe(false);
+          expect(report.breaks[0]?.kind).toBe('gap');
+        });
+      });
+
+      test('truncating a closed run is caught', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ capability: 'one' }));
+          await sink.append(draft({ capability: 'two' }));
+          await sink.append(draft({ capability: 'three' }));
+          await sink.close();
+
+          const keys = (await fixture.keys())
+            .filter((key) => key.endsWith('.json') && !key.startsWith('runs.closed/'))
+            .sort();
+          await fixture.remove(keys[keys.length - 1]!);
+
+          // Nothing inside a chain points forward, so the close marker is the
+          // only thing that can notice the tail is missing.
+          const report = await sink.verify();
+          expect(report.ok).toBe(false);
+          expect(report.breaks[0]?.detail).toContain('closed at 3 events');
+        });
+      });
+
+      test('an unreadable record is reported rather than thrown', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.append(draft({ capability: 'one' }));
+
+          const key = (await fixture.keys()).find((candidate) => candidate.endsWith('.json'))!;
+          await fixture.write(key, new TextEncoder().encode('{ not json'));
+
+          const report = await sink.verify();
+          expect(report.ok).toBe(false);
+          expect(report.breaks[0]?.kind).toBe('malformed');
+
+          // And a corrupt object must not take a tail down with it.
+          expect(await sink.tail()).toEqual([]);
+        });
+      });
+
+      test('a run that wrote nothing leaves no marker', async () => {
+        await use(async (fixture) => {
+          const sink = fixture.open({ now: ticking() });
+          await sink.close();
+
+          expect(await fixture.keys()).toEqual([]);
+        });
+      });
+
+      test('two runs over the same store each verify on their own', async () => {
+        await use(async (fixture) => {
+          const first = fixture.open({ now: ticking(), run: 'r_first' });
+          await first.append(draft({ capability: 'one' }));
+          await first.close();
+
+          const second = fixture.open({ now: ticking(Date.UTC(2026, 7, 12, 11, 0, 0)) });
+          await second.append(draft({ capability: 'two' }));
+
+          const report = await second.verify();
+          expect(report.ok).toBe(true);
+          expect(report.runs).toBe(2);
+          expect(report.events).toBe(2);
+        });
+      });
+    });
+
+    test('the sink exposes no way to mutate or remove an event', async () => {
+      await use(async (fixture) => {
+        // The append-only guarantee is the absence of these methods, so assert
+        // the absence directly rather than trusting the interface to stay
+        // honest. `docs/detailed/security.md` lists `audit.append-only` as ENFORCED on
+        // the grounds that the store interface has no update or delete — this
+        // is the check behind that claim, and it holds for every adapter.
+        const sink = fixture.open();
+        const surface = sink as unknown as Record<string, unknown>;
+
+        expect(Object.keys(sink).sort()).toEqual(['append', 'close', 'tail', 'verify']);
+        expect(surface['update']).toBeUndefined();
+        expect(surface['delete']).toBeUndefined();
+        expect(surface['truncate']).toBeUndefined();
+      });
+    });
+  });
+}

package/src/audit/fanout.ts

@@ -0,0 +1,97 @@
+import type { AuditDraft, AuditEvent, AuditSink } from './index.ts';
+
+/**
+ * One record of truth, and any number of copies.
+ *
+ * The guarantee is one awaited event per invocation, written in a `finally`
+ * (`#dispatch`). A network sink cannot carry that: it fails when a collector is
+ * down, it adds its latency to every capability call, and making the log a
+ * precondition for answering would mean an observability outage takes the
+ * gateway with it.
+ *
+ * So the first sink is awaited and everything after it is best-effort behind a
+ * bounded queue. That ordering is not configuration-shaped politeness — it is
+ * the difference between a sink and *the* log, and `openAudit` is the only
+ * place that decides which is which.
+ */
+
+/**
+ * How many events may be waiting on a secondary sink before they are dropped.
+ *
+ * Bounded because the alternative is worse in exactly the case that matters: a
+ * collector that has stopped answering while a gateway keeps serving. An
+ * unbounded queue turns that into memory growth and then a crash, taking the
+ * durable log with it — a copy is not worth the thing it is a copy of.
+ */
+const MAX_QUEUED = 1000;
+
+export interface FanOutOptions {
+  /** Written and awaited. This one is the log. */
+  readonly primary: AuditSink;
+  /** Copies. Failures are reported once and never raised to the caller. */
+  readonly secondaries: readonly AuditSink[];
+  /** Where a dropped or failed copy is mentioned. Once per sink, not per event. */
+  readonly onError?: (message: string) => void;
+}
+
+export function fanOutAudit(options: FanOutOptions): AuditSink {
+  const { primary, secondaries } = options;
+  if (secondaries.length === 0) return primary;
+
+  const report = options.onError ?? ((): void => {});
+  let queued = 0;
+  let dropped = 0;
+  let complained = false;
+
+  const copy = (event: AuditEvent): void => {
+    if (queued >= MAX_QUEUED) {
+      dropped += 1;
+      if (!complained) {
+        complained = true;
+        report(`audit fan-out is behind; dropping copies (the primary log is unaffected)`);
+      }
+      return;
+    }
+
+    queued += 1;
+    void Promise.allSettled(
+      // `append` on a secondary re-stamps an id and a timestamp it will not
+      // use — the event is already written. Passing the draft keeps the sink
+      // interface single, and the cost is one uuid nobody reads.
+      secondaries.map((sink) => sink.append(event)),
+    )
+      .then((results) => {
+        for (const result of results) {
+          if (result.status === 'rejected' && !complained) {
+            complained = true;
+            report(`audit fan-out failed: ${String(result.reason)}`);
+          }
+        }
+      })
+      .finally(() => {
+        queued -= 1;
+      });
+  };
+
+  return {
+    async append(draft: AuditDraft): Promise<AuditEvent> {
+      const event = await primary.append(draft);
+      copy(event);
+      return event;
+    },
+
+    async close(): Promise<void> {
+      // Give the queue a moment to drain rather than waiting on it: a
+      // collector that is down must not hold a shutdown open, and Cloud Run
+      // gives a bounded grace period before it stops caring.
+      const deadline = Date.now() + 2000;
+      while (queued > 0 && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+
+      if (dropped > 0) report(`audit fan-out dropped ${dropped} copies this run`);
+      await Promise.allSettled(secondaries.map((sink) => sink.close()));
+      await primary.close();
+    },
+  };
+}

package/src/audit/index.ts

@@ -0,0 +1,218 @@
+/**
+ * Audit — append-only, generic across providers.
+ *
+ * Every capability invocation produces exactly one event, whether it was
+ * allowed, denied, rate-limited, or failed. Denials are the interesting half:
+ * an audit log that only records successes cannot answer "what did this agent
+ * try to do".
+ *
+ * Audit records support investigation. They do not prevent an action, and this
+ * module makes no claim that they do.
+ */
+
+import type { AuditVerification } from './chain.ts';
+
+export type {
+  AuditVerification,
+  ChainBreak,
+  ChainedEvent,
+  ChainFields,
+  RunMarker,
+  StoredRecord,
+} from './chain.ts';
+export {
+  auditKey,
+  dayPrefix,
+  decodeEvent,
+  encodeEvent,
+  hashBytes,
+  newRunId,
+  runMarkerKey,
+  stampOf,
+  verifyChain,
+} from './chain.ts';
+
+/** Why a request ended the way it did. */
+export type AuthorizationResult =
+  | 'allowed'
+  | 'denied_by_policy'
+  | 'denied_default' // nothing granted it — the default-deny path
+  | 'denied_unauthenticated'
+  | 'denied_rate_limited'
+  | 'denied_connection_unauthorized'; // credential missing or expired
+
+export type InvocationStatus = 'ok' | 'error' | 'not_invoked';
+
+export interface AuditEvent {
+  readonly id: string;
+  readonly timestamp: Date;
+
+  /** Which profile's endpoint served this. */
+  readonly profile: string;
+
+  /**
+   * The authenticated principal. In M1 there is exactly one per profile (the
+   * owner), but the field is recorded rather than assumed so that adding
+   * delegated access later does not change the log's shape.
+   */
+  readonly principal: string;
+
+  /**
+   * The MCP `clientInfo` name, when the caller supplied one.
+   *
+   * OBSERVABILITY ONLY. This is self-reported by the client and is never
+   * consulted for authorization — it exists so you can see which agent made a
+   * call, not to decide what that agent may do.
+   */
+  readonly clientLabel?: string;
+
+  readonly provider: string;
+  readonly connection?: string;
+  readonly capability: string;
+
+  /**
+   * Redacted argument metadata. Never raw arguments: a Gmail search query can
+   * contain the very content the caller was not allowed to read, and a vault
+   * lookup key can name a secret. Providers declare what survives redaction.
+   */
+  readonly arguments: Readonly<Record<string, unknown>>;
+
+  readonly authorization: AuthorizationResult;
+  readonly status: InvocationStatus;
+  readonly durationMs: number;
+  readonly error?: { readonly kind: string; readonly message: string };
+}
+
+/** What is known before dispatch; the rest is filled in by the writer. */
+export type AuditDraft = Omit<AuditEvent, 'id' | 'timestamp'>;
+
+/**
+ * Where events go.
+ *
+ * There is no `update` and no `delete`, and that absence IS the
+ * `audit.append-only` guarantee — it is enforced by the type system rather
+ * than by convention or by a database trigger. Do not add one. Retention, if
+ * it is ever needed, belongs in a separate operator-run command that is
+ * explicitly outside this interface.
+ *
+ * Writing is separate from reading because not every sink can be read back. A
+ * log shipped to stdout or to an OTLP collector is somebody else's to query,
+ * and giving those a `tail` that throws would be a worse interface than not
+ * offering one.
+ */
+export interface AuditSink {
+  append(draft: AuditDraft): Promise<AuditEvent>;
+  /**
+   * Finish this writer's run.
+   *
+   * Not merely releasing a handle: it is what lets `verify` tell a run that
+   * ended from a run whose tail was cut off. See `./chain.ts`.
+   */
+  close(): Promise<void>;
+}
+
+/** A sink whose events can be read back — a local directory, or a bucket. */
+export interface AuditReader {
+  tail(options?: AuditQuery): Promise<AuditEvent[]>;
+  /**
+   * Check every chain in the log.
+   *
+   * Deliberately takes no range. A chain is only checkable while it is
+   * contiguous, so verifying "since Tuesday" would drop the records each
+   * remaining link is defined against and report breaks that are artefacts of
+   * the filter. All of it, or none of it. If that ever becomes slow, retention
+   * is the answer, and it lives outside this interface.
+   */
+  verify(): Promise<AuditVerification>;
+}
+
+export interface AuditStore extends AuditSink, AuditReader {}
+
+export interface AuditQuery {
+  readonly limit?: number;
+  readonly since?: Date;
+  readonly provider?: string;
+  readonly connection?: string;
+  readonly capability?: string;
+  /** Restrict to denials — the common investigative question. */
+  readonly deniedOnly?: boolean;
+}
+
+/**
+ * What a provider is handed. A provider can add detail to its own invocation's
+ * record; it cannot read the log, and it cannot write an event attributed to
+ * anything other than the call in progress.
+ */
+export interface AuditLogger {
+  /** Attach provider-specific, already-redacted detail to this invocation. */
+  annotate(detail: Readonly<Record<string, unknown>>): void;
+}
+
+/**
+ * A provider's redaction rules: given raw capability arguments, return what is
+ * safe to persist.
+ *
+ * The default, applied when a provider declares nothing, is to record argument
+ * *names* and value types but no values. Providers opt into recording specific
+ * values (a message id is useful and harmless; a search query is neither).
+ */
+export type RedactionRule = (args: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+
+export const redactAllValues: RedactionRule = (args) => {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    out[key] = `<${describeType(value)}>`;
+  }
+  return out;
+};
+
+/** Keep the listed keys verbatim; reduce everything else to a type marker. */
+export function keepKeys(...keys: readonly string[]): RedactionRule {
+  const keep = new Set(keys);
+  return (args) => {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(args)) {
+      out[key] = keep.has(key) ? value : `<${describeType(value)}>`;
+    }
+    return out;
+  };
+}
+
+/**
+ * Keep some keys verbatim, withhold others entirely, type-mark the rest.
+ *
+ * `keepKeys` covers the common case and cannot express the vault's: reducing a
+ * secret to `<string:40>` still discloses its length, while the id beside it is
+ * a name worth recording verbatim — an audit log that cannot say *which* item
+ * was written answers very little. Withheld keys record `<withheld>` and
+ * nothing else.
+ *
+ *     redaction({ keep: ['id'], withhold: ['value'] })
+ *
+ * A key in both is withheld: the stricter rule wins, so a mistake here fails
+ * closed.
+ */
+export function redaction(options: {
+  readonly keep?: readonly string[];
+  readonly withhold?: readonly string[];
+}): RedactionRule {
+  const keep = new Set(options.keep ?? []);
+  const withhold = new Set(options.withhold ?? []);
+
+  return (args) => {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (withhold.has(key)) out[key] = '<withheld>';
+      else if (keep.has(key)) out[key] = value;
+      else out[key] = `<${describeType(value)}>`;
+    }
+    return out;
+  };
+}
+
+function describeType(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return `array:${value.length}`;
+  if (typeof value === 'string') return `string:${value.length}`;
+  return typeof value;
+}