@lanes-sh/link 0.1.0

package/src/deployments/adapters/audit-blob.ts

@@ -0,0 +1,203 @@
+import {
+  auditKey,
+  decodeEvent,
+  encodeEvent,
+  hashBytes,
+  newRunId,
+  stampOf,
+  runMarkerKey,
+  verifyChain,
+  type AuditDraft,
+  type AuditEvent,
+  type AuditQuery,
+  type AuditStore,
+  type AuditVerification,
+  type ChainedEvent,
+  type RunMarker,
+  type StoredRecord,
+} from '#audit';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * The audit log as objects in a blob store.
+ *
+ * One event is one object. That is the same layout locally and deployed — a
+ * directory under the profile and a prefix in the bucket are the same tree —
+ * so there is one sink, one reader, and no question about whether the two
+ * behave alike.
+ *
+ * **Why objects rather than one appended file.** ADR-013 rejected file-backed
+ * audit on the grounds that "a log file cannot enforce that at all; anything
+ * that can open the file can rewrite it". True of one mutable file, and not
+ * true of a set of immutable objects: a bucket retention policy or an
+ * object hold makes each event genuinely unwritable, enforced by the platform
+ * rather than by this interface declining to offer an `update`. Appending to
+ * an object is also not a thing object storage does, so the alternative was a
+ * read-modify-write of the whole log per call.
+ *
+ * The cost, stated rather than discovered later: an event is a few hundred
+ * bytes against a filesystem block of four kilobytes, so locally this spends
+ * roughly five to ten times the space an appended file would. Retention is the
+ * answer when that matters, and `#audit` is explicit that it belongs in an
+ * operator-run command outside this interface — or, deployed, in a bucket
+ * lifecycle rule that needs no code at all.
+ */
+
+/**
+ * How far back `tail` will look for its newest N.
+ *
+ * A bound is needed because finding the newest keys without enumerating every
+ * key means guessing where to look. One list per year is cheap and returns
+ * keys without reading a single object, so ten of them costs little even when
+ * the log is empty.
+ *
+ * `tail` is a tail: returning fewer than asked because the log is older than
+ * this window is the correct answer, not a silent truncation of a search.
+ * `verify` does not use this — it enumerates everything, because it must.
+ */
+const TAIL_YEAR_WINDOW = 10;
+
+const MARKER_PREFIX = 'runs.closed/';
+
+export interface BlobAuditOptions {
+  /** Scoped to the audit root — `data/<profile>/audit.log` or its bucket prefix. */
+  readonly storage: BlobStore;
+  readonly now?: () => Date;
+  /** Overridable so a test can assert a chain across a known run id. */
+  readonly run?: string;
+}
+
+export function createBlobAuditStore(options: BlobAuditOptions): AuditStore {
+  const storage = options.storage;
+  const now = options.now ?? ((): Date => new Date());
+  const run = options.run ?? newRunId();
+
+  let seq = 0;
+  let lastHash: string | null = null;
+
+  return {
+    async append(draft: AuditDraft): Promise<AuditEvent> {
+      const event: AuditEvent = { ...draft, id: `evt_${crypto.randomUUID()}`, timestamp: now() };
+
+      // Every read and write of the chain state happens before the first
+      // await, so two overlapping appends still get consecutive `seq` values
+      // and correctly linked hashes. Objects may then land out of order, which
+      // does not matter: the chain is ordered by `seq`, not by arrival.
+      const bytes = encodeEvent({ ...event, run, seq, prev: lastHash });
+      seq += 1;
+      lastHash = hashBytes(bytes);
+
+      await storage.put(auditKey(event), bytes, { contentType: 'application/json' });
+      return event;
+    },
+
+    async close(): Promise<void> {
+      // A run that wrote nothing has no tail to truncate, so it needs no marker.
+      if (lastHash === null) return;
+
+      const marker: RunMarker = { run, events: seq, last: lastHash };
+      await storage.put(
+        runMarkerKey(run),
+        new TextEncoder().encode(JSON.stringify(marker)),
+        { contentType: 'application/json' },
+      );
+    },
+
+    async tail(query: AuditQuery = {}): Promise<AuditEvent[]> {
+      const limit = query.limit ?? 50;
+      const found: ChainedEvent[] = [];
+
+      const start = now().getUTCFullYear();
+      const floor = query.since ? query.since.getUTCFullYear() : start - TAIL_YEAR_WINDOW;
+
+      for (let year = start; year >= floor && found.length < limit; year -= 1) {
+        const keys = (await storage.list(`${year}/`))
+          .map((entry) => entry.key)
+          .filter((key) => !key.startsWith(MARKER_PREFIX))
+          // Keys are compact ISO within a day and the day is in the path, so
+          // lexicographic order is chronological — no parsing to sort.
+          .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
+
+        let lastStamp: string | null = null;
+
+        for (const key of keys) {
+          const stamp = stampOf(key);
+
+          // Stop at the limit, but never mid-millisecond. Events sharing a
+          // timestamp sort by the random half of their id, so cutting inside
+          // one of those groups would keep an arbitrary subset of it — which
+          // is how a rate-limited call, answered in well under a millisecond,
+          // goes missing from the tail that exists to show it.
+          if (found.length >= limit && stamp !== lastStamp) break;
+          lastStamp = stamp;
+
+          const bytes = await storage.get(key);
+          if (bytes === null) continue;
+
+          const record = decodeEvent(bytes);
+          if (record && matches(record, query)) found.push(record);
+        }
+      }
+
+      // `seq` is the tiebreaker the key cannot carry — the same job SQLite's
+      // implicit `rowid` did. Within one writer it is the true order; across
+      // two writers in the same millisecond there is no true order to find.
+      found.sort(
+        (a, b) => b.timestamp.getTime() - a.timestamp.getTime() || b.seq - a.seq,
+      );
+
+      // Collected newest-first so the limit keeps the most recent; presented
+      // oldest-first, which is how a log is read.
+      return found.slice(0, limit).reverse().map(strip);
+    },
+
+    async verify(): Promise<AuditVerification> {
+      // Deliberately a full enumeration, unlike `tail`. A verification that
+      // skipped part of the log would report `ok` for a range it never looked
+      // at, and a chain is only checkable while it is contiguous — so there is
+      // no range to narrow it by even if that were wanted.
+      const records: StoredRecord[] = [];
+      const markers: RunMarker[] = [];
+
+      for (const entry of await storage.list('')) {
+        const bytes = await storage.get(entry.key);
+        if (bytes === null) continue;
+
+        if (entry.key.startsWith(MARKER_PREFIX)) {
+          const marker = readMarker(bytes);
+          if (marker) markers.push(marker);
+          continue;
+        }
+        records.push({ key: entry.key, bytes });
+      }
+
+      return verifyChain(records, markers);
+    },
+  };
+}
+
+function strip(record: ChainedEvent): AuditEvent {
+  const { run: _run, seq: _seq, prev: _prev, ...event } = record;
+  return event;
+}
+
+function matches(event: AuditEvent, query: AuditQuery): boolean {
+  if (query.since && event.timestamp < query.since) return false;
+  if (query.provider && event.provider !== query.provider) return false;
+  if (query.connection && event.connection !== query.connection) return false;
+  if (query.capability && event.capability !== query.capability) return false;
+  if (query.deniedOnly && event.authorization === 'allowed') return false;
+  return true;
+}
+
+function readMarker(bytes: Uint8Array): RunMarker | null {
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;
+    if (typeof parsed['run'] !== 'string') return null;
+    if (typeof parsed['events'] !== 'number') return null;
+    if (typeof parsed['last'] !== 'string') return null;
+    return { run: parsed['run'], events: parsed['events'], last: parsed['last'] };
+  } catch {
+    return null;
+  }
+}

package/src/deployments/adapters/filesystem.ts

@@ -0,0 +1,184 @@
+import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import type { BlobKey, BlobMetadata, BlobStore } from '#stores/blobs';
+
+/**
+ * Filesystem blob store — the `local` target's adapter.
+ *
+ * Nothing consumes this in M1 or M2: the example and Gmail read providers store
+ * no bytes. It exists because the owner layer (M3 — memory attachments, vault
+ * documents) is the workload the interface was defined for, and defining
+ * storage after providers exist is more expensive than before.
+ *
+ * Do not add S3, Azure, or GCS adapters until a provider actually writes bytes.
+ */
+
+export interface FilesystemBlobStoreOptions {
+  readonly root: string;
+}
+
+export function createFilesystemBlobStore(options: FilesystemBlobStoreOptions): BlobStore {
+  const root = resolve(options.root);
+
+  /**
+   * Remove directories a delete has just emptied, up to but never including
+   * the root.
+   *
+   * An object store has no directories: `a/b/c.txt` is one flat key, and
+   * removing it leaves nothing called `a/b`. This adapter emulates that
+   * interface, so a surviving empty directory is a filesystem artifact leaking
+   * through it — and the one that matters is `data/<profile>`, which would
+   * otherwise outlive the profile whose objects it held.
+   *
+   * `rmdir` rather than a recursive remove, and the error swallowed: it fails
+   * when the directory is not empty, which is exactly the signal to stop.
+   */
+  const pruneEmptyParents = async (directory: string): Promise<void> => {
+    let current = directory;
+    while (current.startsWith(root) && current !== root) {
+      try {
+        await rmdir(current);
+      } catch {
+        return;
+      }
+      current = dirname(current);
+    }
+  };
+
+  /**
+   * Resolve a key to an absolute path, refusing anything that lands outside
+   * the root.
+   *
+   * `scopeBlobStore` already rejects traversal before a key reaches here, but
+   * this adapter is also usable directly, and a containment check belongs at
+   * the point where a path actually becomes a filesystem operation. Defence in
+   * depth is cheap; a provider escaping its directory is not.
+   */
+  const pathFor = (key: BlobKey): string => {
+    const resolved = resolve(root, key);
+    const rel = relative(root, resolved);
+
+    if (rel === '' || rel.startsWith('..') || rel.startsWith(`..${sep}`)) {
+      throw new Error(`Blob key resolves outside the store root: ${key}`);
+    }
+    return resolved;
+  };
+
+  return {
+    async put(key, data, blobOptions) {
+      const path = pathFor(key);
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+
+      // Write-then-rename so a reader never observes a half-written blob, and
+      // 0600 from the moment of creation rather than a chmod afterwards, which
+      // would leave a window where the bytes are readable.
+      //
+      // The credential store and the vault already do this; what lands here is
+      // everything else a profile owns — the audit log, `state.kv`, memory, and
+      // cached mail attachments. Left at the umask default those are 0644 in a
+      // 0755 directory, which on a shared machine is every local user's to read.
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile(temporary, data, { mode: 0o600 });
+      await rename(temporary, path);
+
+      // A sidecar only when the extension cannot say it. Every blob written
+      // today is Markdown, JSON, or text, so in practice none is written at all
+      // — a `note.md` beside a `note.md.meta` recording `text/markdown` was
+      // noise in a directory the operator is meant to be able to read.
+      if (blobOptions?.contentType && inferContentType(path) !== blobOptions.contentType) {
+        await writeFile(`${path}.meta`, JSON.stringify({ contentType: blobOptions.contentType }), {
+          mode: 0o600,
+        });
+      } else {
+        // A rewrite may be narrowing a type the extension now covers.
+        await rm(`${path}.meta`, { force: true });
+      }
+    },
+
+    async get(key) {
+      const path = pathFor(key);
+      if (!existsSync(path)) return null;
+      return new Uint8Array(await readFile(path));
+    },
+
+    async has(key) {
+      return existsSync(pathFor(key));
+    },
+
+    async delete(key) {
+      const path = pathFor(key);
+      await rm(path, { force: true });
+      await rm(`${path}.meta`, { force: true });
+      await pruneEmptyParents(dirname(path));
+    },
+
+    async list(prefix) {
+      const results: BlobMetadata[] = [];
+
+      const walk = async (directory: string): Promise<void> => {
+        let entries;
+        try {
+          entries = await readdir(directory, { withFileTypes: true });
+        } catch {
+          return; // Nothing stored yet.
+        }
+
+        for (const entry of entries) {
+          const absolute = join(directory, entry.name);
+          if (entry.isDirectory()) {
+            await walk(absolute);
+            continue;
+          }
+          if (entry.name.endsWith('.meta') || entry.name.endsWith('.tmp')) continue;
+
+          const key = relative(root, absolute).split(sep).join('/');
+          if (prefix && !key.startsWith(prefix)) continue;
+
+          const info = await stat(absolute);
+          const contentType = await readContentType(absolute);
+          results.push({
+            key,
+            size: info.size,
+            modifiedAt: info.mtime,
+            ...(contentType ? { contentType } : {}),
+          });
+        }
+      };
+
+      await walk(root);
+      return results.sort((a, b) => a.key.localeCompare(b.key));
+    },
+  };
+}
+
+/**
+ * What the extension says, for the handful of types anything here stores.
+ *
+ * Deliberately short: this is not a MIME database, it is the set of things a
+ * provider writes, and anything outside it falls back to a sidecar.
+ */
+const BY_EXTENSION: Record<string, string> = {
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.txt': 'text/plain',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml',
+};
+
+function inferContentType(path: string): string | undefined {
+  const dot = path.lastIndexOf('.');
+  return dot === -1 ? undefined : BY_EXTENSION[path.slice(dot).toLowerCase()];
+}
+
+async function readContentType(path: string): Promise<string | undefined> {
+  const inferred = inferContentType(path);
+  if (inferred) return inferred;
+
+  try {
+    const parsed = JSON.parse(await readFile(`${path}.meta`, 'utf8')) as { contentType?: string };
+    return parsed.contentType;
+  } catch {
+    return undefined;
+  }
+}