@lanes-sh/link 0.1.0

package/src/stores/state/index.ts

@@ -0,0 +1,247 @@
+/**
+ * Runtime state — what *is*, as against what should be.
+ *
+ * The split of responsibilities matters and is easy to erode:
+ *
+ *   config file      what exists (declared, diffable, source of truth)
+ *   credential store credential values
+ *   state (here)     connection status, token expiry, cursors, provider state
+ *   audit log        what happened — objects in the blob store, see `#audit`
+ *
+ * Nothing here is a source of truth for what *should* exist. All of it can be
+ * deleted and rebuilt: reconcile restores the connection rows from the config
+ * file, a discovery cache re-discovers, and a logged-out connector authorises
+ * again. Keep it that way — the deployed target scales to zero, so
+ * administering it by connecting to a database is not a workable model.
+ *
+ * **There is no database.** Every access below is a point read or write on one
+ * key, plus one prefix listing; nothing joins, aggregates, orders, or searches.
+ * That was true when this was four SQL tables too — the tables were carrying a
+ * query engine nothing queried. It is one object per key in the `BlobStore` the
+ * target already opened, which means the local and deployed paths are the same
+ * code and the deployed target needs no second service. ADR-020 has the
+ * reasoning for the log; this is the same argument applied to the rest.
+ */
+
+import type { BlobStore } from '../blobs/index.ts';
+import { keyFromEntry, namespacePrefix, objectKey } from './keys.ts';
+
+export type ConnectionStatus =
+  | 'active'
+  /** Declared, but its credential is missing or rejected. Does not block startup. */
+  | 'unauthorized'
+  /** No longer declared in config. Never deleted, so audit history stays meaningful. */
+  | 'disabled';
+
+export interface ConnectionRecord {
+  readonly provider: string;
+  readonly id: string;
+  readonly displayName: string;
+  readonly status: ConnectionStatus;
+  readonly credentialExpiresAt?: Date;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+/** `provider.id`, e.g. `gmail.main`. The addressing form used everywhere. */
+export function connectionKey(provider: string, id: string): string {
+  return `${provider}.${id}`;
+}
+
+export interface ConnectionRepository {
+  upsert(record: Omit<ConnectionRecord, 'createdAt' | 'updatedAt'>): Promise<ConnectionRecord>;
+  get(provider: string, id: string): Promise<ConnectionRecord | null>;
+  list(): Promise<ConnectionRecord[]>;
+  setStatus(provider: string, id: string, status: ConnectionStatus): Promise<void>;
+}
+
+/**
+ * Namespaced key-value, scoped by core to `<provider>/<connection>` before a
+ * provider ever sees it. A provider cannot read another provider's state, and
+ * cannot read another connection's state within its own provider.
+ */
+export interface KeyValueStore {
+  get(namespace: string, key: string): Promise<string | null>;
+  set(namespace: string, key: string, value: string): Promise<void>;
+  delete(namespace: string, key: string): Promise<void>;
+  keys(namespace: string): Promise<string[]>;
+  clearNamespace(namespace: string): Promise<void>;
+}
+
+/** Sync cursors for providers that page through upstream data incrementally. */
+export interface CursorRepository {
+  get(namespace: string): Promise<string | null>;
+  set(namespace: string, cursor: string): Promise<void>;
+}
+
+export interface RuntimeState {
+  readonly connections: ConnectionRepository;
+  /**
+   * Namespaced key-value. Named `kv` rather than `state` because the whole of
+   * this is state — a member called `state` on a thing called `RuntimeState`
+   * reads as the whole rather than the part, which is what it was doing when
+   * the type was still called `RuntimeState`.
+   */
+  readonly kv: KeyValueStore;
+  readonly cursors: CursorRepository;
+}
+
+/**
+ * Reserved namespaces, carrying a dot so a provider cannot collide with one.
+ *
+ * A provider's state is namespaced `<provider>/<connection>` and a provider id
+ * is `[a-z][a-z0-9_]*`, so a dot is a character no provider namespace can
+ * contain. The same rule keeps `audit.log` and `state.kv` out of reach in
+ * `#profile`'s layout.
+ */
+const CONNECTIONS = 'connections.v1';
+const CURSORS = 'cursors.v1';
+
+export function createRuntimeState(
+  blobs: BlobStore,
+  now: () => Date = () => new Date(),
+): RuntimeState {
+  const kv = createKeyValue(blobs);
+
+  const readConnection = async (provider: string, id: string): Promise<ConnectionRecord | null> =>
+    decodeConnection(await kv.get(CONNECTIONS, connectionKey(provider, id)));
+
+  const connections: ConnectionRepository = {
+    async upsert(record) {
+      const existing = await readConnection(record.provider, record.id);
+      const stored: ConnectionRecord = {
+        ...record,
+        // Preserved across updates: when a connection was first seen is a fact
+        // about the connection, not about the last time reconcile ran.
+        createdAt: existing?.createdAt ?? now(),
+        updatedAt: now(),
+      };
+      await kv.set(CONNECTIONS, connectionKey(record.provider, record.id), encodeConnection(stored));
+      return stored;
+    },
+
+    get: readConnection,
+
+    async list() {
+      const records: ConnectionRecord[] = [];
+      for (const key of await kv.keys(CONNECTIONS)) {
+        const record = decodeConnection(await kv.get(CONNECTIONS, key));
+        if (record) records.push(record);
+      }
+      return records.sort(
+        (a, b) => a.provider.localeCompare(b.provider) || a.id.localeCompare(b.id),
+      );
+    },
+
+    async setStatus(provider, id, status) {
+      const existing = await readConnection(provider, id);
+      if (!existing) return;
+      await kv.set(
+        CONNECTIONS,
+        connectionKey(provider, id),
+        encodeConnection({ ...existing, status, updatedAt: now() }),
+      );
+    },
+  };
+
+  const cursors: CursorRepository = {
+    get: (namespace) => kv.get(CURSORS, namespace),
+    set: (namespace, cursor) => kv.set(CURSORS, namespace, cursor),
+  };
+
+  return { connections, kv, cursors };
+}
+
+/**
+ * One object per key.
+ *
+ * Per key rather than one document per namespace, so there is no
+ * read-modify-write anywhere: two writers touching different keys never
+ * contend, and a torn write can lose at most the one value being written.
+ */
+export function createKeyValue(blobs: BlobStore): KeyValueStore {
+  return {
+    async get(namespace, key) {
+      const bytes = await blobs.get(objectKey(namespace, key));
+      return bytes === null ? null : new TextDecoder().decode(bytes);
+    },
+
+    async set(namespace, key, value) {
+      await blobs.put(objectKey(namespace, key), new TextEncoder().encode(value), {
+        contentType: 'application/json',
+      });
+    },
+
+    async delete(namespace, key) {
+      await blobs.delete(objectKey(namespace, key));
+    },
+
+    async keys(namespace) {
+      const prefix = namespacePrefix(namespace);
+      const found: string[] = [];
+      for (const entry of await blobs.list(prefix)) {
+        const key = keyFromEntry(prefix, entry.key);
+        if (key !== null) found.push(key);
+      }
+      return found.sort();
+    },
+
+    async clearNamespace(namespace) {
+      const prefix = namespacePrefix(namespace);
+      for (const entry of await blobs.list(prefix)) {
+        // Direct children only, matching `keys`. A nested namespace is a
+        // different namespace and clearing one must not empty the other.
+        if (keyFromEntry(prefix, entry.key) === null) continue;
+        await blobs.delete(entry.key);
+      }
+    },
+  };
+}
+
+interface StoredConnection {
+  provider: string;
+  id: string;
+  displayName: string;
+  status: string;
+  credentialExpiresAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function encodeConnection(record: ConnectionRecord): string {
+  const stored: StoredConnection = {
+    provider: record.provider,
+    id: record.id,
+    displayName: record.displayName,
+    status: record.status,
+    ...(record.credentialExpiresAt
+      ? { credentialExpiresAt: record.credentialExpiresAt.toISOString() }
+      : {}),
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  };
+  return JSON.stringify(stored);
+}
+
+function decodeConnection(raw: string | null): ConnectionRecord | null {
+  if (raw === null) return null;
+  try {
+    const stored = JSON.parse(raw) as StoredConnection;
+    return {
+      provider: stored.provider,
+      id: stored.id,
+      displayName: stored.displayName,
+      status: stored.status as ConnectionStatus,
+      ...(stored.credentialExpiresAt
+        ? { credentialExpiresAt: new Date(stored.credentialExpiresAt) }
+        : {}),
+      createdAt: new Date(stored.createdAt),
+      updatedAt: new Date(stored.updatedAt),
+    };
+  } catch {
+    // A record that will not parse is one nothing can use. Treating it as
+    // absent fails closed and lets reconcile rebuild it, which is the whole
+    // reason this store is allowed to be lossy.
+    return null;
+  }
+}

package/src/stores/state/keys.ts

@@ -0,0 +1,68 @@
+/**
+ * Turning a namespace and a key into an object key, reversibly.
+ *
+ * Both halves come from callers this module does not control. A provider
+ * namespace is `<provider>/<connection>` and its keys are whatever that
+ * provider chose; the OAuth server stores under a SHA-256 hex digest; a
+ * discovery cache stores under a provider id. Percent-encoding everything
+ * outside a small safe set is the only rule that holds for all of them.
+ *
+ * **Why not the shorter thing.** `gcp-secret-manager.ts` maps `/` to `__` and
+ * round-trips to refuse anything ambiguous, which is fine for refs that are
+ * already `[a-z0-9_-]` by schema. Keys here are not, so the same trick would
+ * have to refuse keys that already work today. In particular `.` must be
+ * escaped: a key of `..` is a directory traversal that `encodeURIComponent`
+ * would pass through untouched.
+ *
+ * The namespace keeps its `/` as a real path separator, so a bucket listing is
+ * browsable and `keys()` is one prefix list. Each *segment* is still encoded,
+ * so a `/` inside a segment cannot forge one.
+ */
+
+const SAFE = /^[A-Za-z0-9_-]$/;
+
+export function encodeSegment(segment: string): string {
+  let out = '';
+  for (const character of segment) {
+    if (SAFE.test(character)) {
+      out += character;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(character)) {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+  }
+  return out;
+}
+
+export function decodeSegment(segment: string): string {
+  return decodeURIComponent(segment);
+}
+
+/** `oauth/tokens` becomes `oauth/tokens/`, one encoded path segment each. */
+export function namespacePrefix(namespace: string): string {
+  if (namespace.length === 0) throw new Error('State namespace must not be empty');
+  return `${namespace.split('/').map(encodeSegment).join('/')}/`;
+}
+
+export function objectKey(namespace: string, key: string): string {
+  if (key.length === 0) throw new Error('State key must not be empty');
+  return `${namespacePrefix(namespace)}${encodeSegment(key)}.json`;
+}
+
+/**
+ * The key a listing entry came from, or `null` if it is not a direct child.
+ *
+ * Namespaces nest — `oauth` and `oauth/tokens` can both exist — so listing a
+ * prefix returns grandchildren too. A namespace that leaked its children's
+ * keys would break the isolation `KeyValueStore` exists to provide, so
+ * anything below the first level is skipped rather than flattened.
+ */
+export function keyFromEntry(prefix: string, entryKey: string): string | null {
+  if (!entryKey.startsWith(prefix)) return null;
+
+  const remainder = entryKey.slice(prefix.length);
+  if (remainder.includes('/') || !remainder.endsWith('.json')) return null;
+
+  return decodeSegment(remainder.slice(0, -'.json'.length));
+}

package/src/stores/state/testing.ts

@@ -0,0 +1,41 @@
+/**
+ * Runtime state over an in-memory blob store, for tests.
+ *
+ * Note what this is *not*: a second implementation. It is the real
+ * `createRuntimeState` over `createMemoryBlobStore`, so a test cannot
+ * demonstrate behaviour the shipped code does not have — which is what the
+ * hand-written in-memory `RuntimeState` beside it used to risk, and did: its
+ * `list()` returned insertion order where both SQL adapters sorted.
+ *
+ * Kept behind a separate entry point anyway, so application code cannot reach
+ * the memory store by accident.
+ */
+
+import { createMemoryBlobStore } from '../blobs/testing.ts';
+import { createRuntimeState, type RuntimeState } from './index.ts';
+
+export function createMemoryState(now: () => Date = () => new Date()): RuntimeState {
+  return createRuntimeState(createMemoryBlobStore(), now);
+}
+
+/** An in-memory credential store, for the same reason. */
+export function createMemoryCredentials(initial: Record<string, string> = {}) {
+  const map = new Map(Object.entries(initial));
+  return {
+    async get(ref: string) {
+      return map.get(ref) ?? null;
+    },
+    async set(ref: string, value: string) {
+      map.set(ref, value);
+    },
+    async has(ref: string) {
+      return map.has(ref);
+    },
+    async delete(ref: string) {
+      map.delete(ref);
+    },
+    async list(prefix?: string) {
+      return [...map.keys()].filter((k) => !prefix || k.startsWith(prefix));
+    },
+  };
+}