@zackbart/connecta 0.28.0 → 0.29.0

package/dist/sqlite.d.ts

@@ -0,0 +1,48 @@
+import { DatabaseSync } from "node:sqlite";
+import type { ActivityStore } from "./activity.js";
+import type { KVStorage } from "./types.js";
+import { type SqlActivityOptions } from "./storage/sql.js";
+export type SqliteActivityOptions = SqlActivityOptions;
+/** A database path, or a `DatabaseSync` that `openSqlite` (or you) opened. */
+export type SqliteDatabase = string | DatabaseSync;
+/**
+ * Open (creating if needed) a SQLite database for connecta. The directory is
+ * created owner-only and the file is owner-only before SQLite first writes
+ * it, because it holds downstream OAuth state and sealed credentials; SQLite
+ * gives its `-wal` and `-shm` files the database file's mode. Write-ahead
+ * logging lets activity reads proceed beside writes, and a busy timeout lets a
+ * second process on the same file wait for a lock instead of failing.
+ *
+ * `":memory:"` opens a private in-memory database, for tests.
+ */
+export declare function openSqlite(path: string): DatabaseSync;
+/**
+ * `KVStorage` in a SQLite file, with the atomic `compareAndSet` every
+ * subsystem relies on. Each write commits one row; nothing rewrites the file.
+ */
+export declare function sqliteStorage(database: SqliteDatabase): KVStorage;
+/**
+ * Payload-free activity history in the same SQLite file, for
+ * `activityHistory({ store })`. Each write prunes a bounded batch of rows
+ * older than `retentionDays`.
+ */
+export declare function sqliteActivityStore(database: SqliteDatabase, options?: SqliteActivityOptions): ActivityStore;
+export interface StateFileImport {
+    /** Entries copied into the database. */
+    imported: number;
+    /** Entries left alone because the database already held their key. */
+    kept: number;
+    /** Entries whose TTL had already passed. */
+    expired: number;
+}
+/**
+ * One-shot migration from the 0.28 `fileStorage` JSON state file: copy every
+ * live entry, with its expiry, into the database's key-value table. Run it
+ * once, with the old deployment stopped, before the first start on SQLite.
+ *
+ * Keys the database already holds are kept, so a second run copies nothing
+ * twice and never overwrites state written since. The file is read, never
+ * changed; delete it once the deployment is verified. A file that is not a
+ * state file throws before anything is written.
+ */
+export declare function importStateFile(database: SqliteDatabase, statePath: string, now?: number): StateFileImport;

package/dist/sqlite.js

@@ -0,0 +1,166 @@
+// `@zackbart/connecta/sqlite`: connecta's storage on Node, in one SQLite file.
+//
+// Built on `node:sqlite` (Node 22.13 or later), so there is nothing to
+// install. `sqliteStorage` is the deployment's `KVStorage` and
+// `sqliteActivityStore` its activity history; both create their tables on
+// first use. Node-only: nothing reachable from the root entry imports this.
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { validateStorageKey } from "./storage/keys.js";
+import { KV_SCHEMA, sqlActivityStore, sqlStorage, } from "./storage/sql.js";
+/** Milliseconds a write waits for another process's write lock. */
+const BUSY_TIMEOUT_MS = 5_000;
+/**
+ * Open (creating if needed) a SQLite database for connecta. The directory is
+ * created owner-only and the file is owner-only before SQLite first writes
+ * it, because it holds downstream OAuth state and sealed credentials; SQLite
+ * gives its `-wal` and `-shm` files the database file's mode. Write-ahead
+ * logging lets activity reads proceed beside writes, and a busy timeout lets a
+ * second process on the same file wait for a lock instead of failing.
+ *
+ * `":memory:"` opens a private in-memory database, for tests.
+ */
+export function openSqlite(path) {
+    if (path !== ":memory:") {
+        path = resolve(path);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        closeSync(openSync(path, "a", 0o600));
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            // Non-POSIX filesystem — leave the mode as it is.
+        }
+    }
+    const db = new DatabaseSync(path);
+    db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    if (path !== ":memory:")
+        db.exec("PRAGMA journal_mode = WAL");
+    return db;
+}
+const drivers = new WeakMap();
+function sqliteDriver(database) {
+    const db = typeof database === "string" ? openSqlite(database) : database;
+    const existing = drivers.get(db);
+    if (existing)
+        return existing;
+    // The statement set is the fixed SQL in ./sql.ts, so the cache is bounded.
+    const statements = new Map();
+    const prepare = (statement) => {
+        let prepared = statements.get(statement.sql);
+        if (!prepared) {
+            prepared = db.prepare(statement.sql);
+            statements.set(statement.sql, prepared);
+        }
+        return prepared;
+    };
+    const run = (statement) => {
+        return Number(prepare(statement).run(...statement.params).changes);
+    };
+    const driver = {
+        async all(statement) {
+            return prepare(statement).all(...statement.params);
+        },
+        async run(statement) {
+            return run(statement);
+        },
+        async batch(batch) {
+            // Synchronous from BEGIN to COMMIT: no other call on this connection
+            // can interleave, and IMMEDIATE takes the write lock up front so
+            // another process cannot either.
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                const changes = batch.map(run);
+                db.exec("COMMIT");
+                return changes;
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
+        },
+    };
+    drivers.set(db, driver);
+    return driver;
+}
+/**
+ * `KVStorage` in a SQLite file, with the atomic `compareAndSet` every
+ * subsystem relies on. Each write commits one row; nothing rewrites the file.
+ */
+export function sqliteStorage(database) {
+    return sqlStorage(sqliteDriver(database), "sqlite");
+}
+/**
+ * Payload-free activity history in the same SQLite file, for
+ * `activityHistory({ store })`. Each write prunes a bounded batch of rows
+ * older than `retentionDays`.
+ */
+export function sqliteActivityStore(database, options) {
+    return sqlActivityStore(sqliteDriver(database), "sqlite", options);
+}
+/**
+ * One-shot migration from the 0.28 `fileStorage` JSON state file: copy every
+ * live entry, with its expiry, into the database's key-value table. Run it
+ * once, with the old deployment stopped, before the first start on SQLite.
+ *
+ * Keys the database already holds are kept, so a second run copies nothing
+ * twice and never overwrites state written since. The file is read, never
+ * changed; delete it once the deployment is verified. A file that is not a
+ * state file throws before anything is written.
+ */
+export function importStateFile(database, statePath, now = Date.now()) {
+    const text = readFileSync(statePath, "utf8");
+    // The file holds stored state (tokens, sealed credentials), and these
+    // errors reach the operator's terminal, so they name the file and an entry's
+    // position, never a key or the parser's account, which quotes the text.
+    let loaded;
+    try {
+        loaded = JSON.parse(text);
+    }
+    catch {
+        throw new TypeError(`${statePath} is not a connecta state file: it is not valid JSON`);
+    }
+    if (loaded === null || typeof loaded !== "object" || Array.isArray(loaded)) {
+        throw new TypeError(`${statePath} is not a connecta state file`);
+    }
+    const entries = Object.entries(loaded);
+    for (const [index, [key, entry]] of entries.entries()) {
+        validateStorageKey(key);
+        const valid = entry !== null &&
+            typeof entry === "object" &&
+            typeof entry.value === "string" &&
+            (!("exp" in entry) || Number.isFinite(entry.exp));
+        if (!valid) {
+            throw new TypeError(`${statePath} is not a connecta state file: entry ${index + 1} has no string value`);
+        }
+    }
+    const db = typeof database === "string" ? openSqlite(database) : database;
+    const result = { imported: 0, kept: 0, expired: 0 };
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const statement of KV_SCHEMA)
+            db.exec(statement);
+        const insert = db.prepare(`INSERT INTO connecta_kv (key, value, expires_at_ms) VALUES (?, ?, ?)
+       ON CONFLICT (key) DO NOTHING`);
+        for (const [key, entry] of entries) {
+            const { value, exp } = entry;
+            if (exp !== undefined && exp <= now) {
+                result.expired += 1;
+                continue;
+            }
+            if (Number(insert.run(key, value, exp === undefined ? null : Math.ceil(exp)).changes) > 0) {
+                result.imported += 1;
+            }
+            else {
+                result.kept += 1;
+            }
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    return result;
+}

package/dist/storage/keys.js

@@ -0,0 +1,428 @@
+// Every key connecta stores, in one module.
+//
+// A deployment has one KVStorage (D1 on Workers, SQLite on Node, memory in
+// tests), and every subsystem shares it. Sharing is safe because no two
+// families claim overlapping keys, and that is only checkable if every key is
+// built here: `test/storage-keys.node.test.ts` fails when another source file
+// spells one of these prefixes itself.
+//
+// Each family records:
+//
+// - scope: where its keys sit. `root` keys are physical. `partition` keys sit
+//   under a result partition (`results:`, or `subject:<key>:` for a scoped
+//   subject). `connector` keys sit under a connector's namespace
+//   (`conn:<id>:`), which a personal registry nests again under
+//   `principal:<key>:`.
+// - version: the layout the keys and values follow. `in: "key"` families spell
+//   it in the key, so a new layout can be written beside the old one and
+//   migrated; `in: "value"` families carry it inside each record; `untagged`
+//   families predate tags, and their next layout change adds one. A version
+//   changes with a one-shot migration or with a family declared transient.
+// - codec: how a value is written. `json` values are validated by the
+//   subsystem that reads them; nothing here trusts stored bytes.
+// - ttl: `durable` (no expiry), `fixed` seconds, or `configured` by the
+//   deployment. Transient families can change layout freely, because their
+//   data expires within one TTL of a deploy.
+/** Stored as given. */
+const textCodec = {
+    name: "text",
+    encode: (value) => value,
+    decode: (raw) => raw,
+};
+/** JSON. Decoding returns `unknown`: the reader validates the shape. */
+export const jsonCodec = {
+    name: "json",
+    encode: (value) => JSON.stringify(value),
+    decode: (raw) => JSON.parse(raw),
+};
+/** SQL TEXT keys must round-trip on every supported Node and D1 runtime. */
+export function validateStorageKey(key) {
+    if (key.includes("\0")) {
+        throw new TypeError("Storage keys and list prefixes must not contain U+0000 (NUL)");
+    }
+    return key;
+}
+// --- scopes -------------------------------------------------------------
+/** Namespaces core hands to the subsystems below. */
+export const scopes = {
+    /** A personal registry's partition of the root store. */
+    principal: (principalKey) => validateStorageKey(`principal:${principalKey}:`),
+    /** One connector's namespace: its `ctx.storage`. */
+    connector: (connectorId) => validateStorageKey(`conn:${connectorId}:`),
+    /** The root result partition. */
+    results: "results:",
+    /** A scoped subject's result partition. */
+    subject: (subjectKey) => validateStorageKey(`subject:${subjectKey}:`),
+};
+// --- partition families ---------------------------------------------------
+/** Seconds a stashed result stays readable through paging. */
+export const RESULT_TTL_SECONDS = 900;
+/**
+ * A stashed result: chunk 0 at `result:<id>`, chunk n at `result:<id>#<n>`.
+ * The value is the paging envelope `src/meta-tools.ts` writes and reads.
+ */
+export const resultKeys = {
+    family: {
+        name: "result",
+        scope: "partition",
+        prefixes: ["result:"],
+        version: { number: 4, in: "value" },
+        codec: textCodec,
+        ttl: { kind: "fixed", seconds: RESULT_TTL_SECONDS },
+        durable: false,
+    },
+    chunk: (id, index) => validateStorageKey(index === 0 ? `result:${id}` : `result:${id}#${index}`),
+};
+// --- root families --------------------------------------------------------
+/**
+ * The runtime-wide result stash ledger: every live stash entry's partition
+ * key, byte charge, and expiry. One record, swapped by compare-and-set, so the
+ * stash bounds hold across isolates and processes sharing the store.
+ */
+export const stashLedgerKeys = {
+    family: {
+        name: "result-stash-ledger",
+        scope: "root",
+        prefixes: ["result-stash:v1:"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        // Durable as a record, self-pruning by content: an entry leaves the
+        // ledger once its result's TTL has passed.
+        ttl: { kind: "durable" },
+        durable: false,
+    },
+    ledger: "result-stash:v1:ledger",
+};
+/**
+ * A persisted downstream catalog: the manifest at `catalog:<id>`, then its
+ * chunks at `catalog:<id>:chunk:<revision>:<index>`.
+ */
+export const catalogKeys = {
+    family: {
+        name: "catalog",
+        scope: "root",
+        prefixes: ["catalog:"],
+        // Retired v2/v3 listings are inventoried for migration; no runtime reads them.
+        version: { number: 3, in: "value" },
+        codec: textCodec,
+        ttl: {
+            kind: "configured",
+            by: "retired catalog layout; expires on its original TTL",
+        },
+        durable: false,
+    },
+    manifest: (connectorId) => validateStorageKey(`catalog:${connectorId}`),
+    chunk: (connectorId, revision, index) => validateStorageKey(`catalog:${connectorId}:chunk:${revision}:${index}`),
+};
+/** SDK catalog response cache, complete manifests published after their chunks. */
+export const responseCacheKeys = {
+    family: {
+        name: "response-cache",
+        scope: "root",
+        prefixes: ["response-cache:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: {
+            kind: "configured",
+            by: "bounded downstream ttlMs; generations and hash refresh baselines expire after 48 hours",
+        },
+        durable: false,
+    },
+    prefix: (id) => validateStorageKey(`response-cache:v1:${id}:`),
+    generation: (id) => validateStorageKey(`response-cache:v1:${id}:generation`),
+    namespace: (id, config, generation) => validateStorageKey(`response-cache:v1:${id}:${config}:${generation}:`),
+    entry: (namespace, partition) => validateStorageKey(`${namespace}${partition}`),
+    refreshDigest: (id, config, partition) => validateStorageKey(`response-cache:v1:${id}:refresh-digest:${config}:${partition}`),
+    chunk: (entry, revision, index) => validateStorageKey(`${entry}:chunk:${revision}:${index}`),
+};
+/** Seconds an OAuth callback's owner binding stays claimable. */
+export const OAUTH_HANDOFF_TTL_SECONDS = 15 * 60;
+/** The principal that started an OAuth flow, by connector and state digest. */
+export const oauthHandoffKeys = {
+    family: {
+        name: "oauth-handoff",
+        scope: "root",
+        prefixes: ["oauth-handoff:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: { kind: "fixed", seconds: OAUTH_HANDOFF_TTL_SECONDS },
+        durable: false,
+    },
+    handoff: (connectorId, stateHash) => validateStorageKey(`oauth-handoff:v1:${connectorId}:${stateHash}`),
+};
+/** Connecta-issued `cta_` access tokens: records, digest lookups, capacity. */
+export const accessTokenKeys = {
+    family: {
+        name: "access-token",
+        scope: "root",
+        prefixes: ["access-token:v1:"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    recordPrefix: "access-token:v1:record:",
+    record: (id) => validateStorageKey(`access-token:v1:record:${id}`),
+    lookup: (tokenHash) => validateStorageKey(`access-token:v1:lookup:${tokenHash}`),
+    active: "access-token:v1:active",
+};
+/**
+ * A vault credential, sealed: `credential:v1` inside its connector's
+ * namespace, under the owner's principal partition when it is personal.
+ */
+export const credentialKeys = {
+    family: {
+        name: "credential",
+        scope: "connector",
+        prefixes: ["credential:v1"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    credential: (connectorId, owner) => `${owner ? scopes.principal(owner) : ""}${scopes.connector(connectorId)}credential:v1`,
+};
+/** Seconds a Workers KV → D1 copy's resume point stays usable. */
+export const KV_COPY_CURSOR_TTL_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Where a one-shot Workers KV → D1 copy (`copyKvToD1` in `src/d1.ts`) resumes,
+ * held in D1 under a random token. Workers KV's own list cursor can spell the
+ * last key it listed, so the caller holds the token and never the cursor.
+ */
+export const kvCopyKeys = {
+    family: {
+        name: "kv-copy",
+        scope: "root",
+        prefixes: ["kv-copy:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: { kind: "fixed", seconds: KV_COPY_CURSOR_TTL_SECONDS },
+        durable: false,
+    },
+    cursor: (token) => validateStorageKey(`kv-copy:v1:cursor:${token}`),
+};
+/** Once traffic uses D1, copying stale KV state is refused. */
+export const kvCutoverKeys = {
+    family: {
+        name: "kv-cutover",
+        scope: "root",
+        prefixes: ["kv-cutover:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    source: (source) => validateStorageKey(`kv-cutover:v1:${encodeURIComponent(source)}`),
+};
+// --- connector families ---------------------------------------------------
+/** Seconds a consent's flow record stays claimable, the same as its link. */
+export const OAUTH_FLOW_TTL_SECONDS = 15 * 60;
+/**
+ * Downstream OAuth's grant in a connector's namespace, layout 3: one record
+ * per owner at `oauth:grant`, holding the epoch, the latest consent's state
+ * digest, and the sealed client, tokens, and discovery. Every write is a
+ * compare-and-set against the exact record read, so a write a restart
+ * overtook cannot land.
+ */
+export const oauthGrantKeys = {
+    family: {
+        name: "oauth-grant",
+        scope: "connector",
+        prefixes: ["oauth:grant"],
+        version: { number: 3, in: "value" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    grant: "oauth:grant",
+};
+/**
+ * One consent: `oauth:flow:<sha256(state)>`, holding its epoch, consent URL,
+ * and sealed PKCE verifier. The callback claims it by compare-and-set before
+ * the code leaves, so consumption is recorded on that consent alone.
+ */
+export const oauthFlowKeys = {
+    family: {
+        name: "oauth-flow",
+        scope: "connector",
+        prefixes: ["oauth:flow:"],
+        version: { number: 1, in: "value" },
+        codec: jsonCodec,
+        ttl: { kind: "fixed", seconds: OAUTH_FLOW_TTL_SECONDS },
+        durable: false,
+    },
+    prefix: "oauth:flow:",
+    flow: (stateDigest) => validateStorageKey(`oauth:flow:${stateDigest}`),
+};
+/** Shared-storage lifetime of a refresh holder, longer than its HTTP deadline. */
+export const OAUTH_REFRESH_LEASE_SECONDS = 120;
+export const oauthRefreshKeys = {
+    family: {
+        name: "oauth-refresh",
+        scope: "connector",
+        prefixes: ["oauth:refresh:"],
+        version: { number: 1, in: "value" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    prefix: "oauth:refresh:",
+    lease: (epoch, tokenDigest) => validateStorageKey(`oauth:refresh:${epoch}:${tokenDigest}`),
+};
+/** One fingerprint's dispatch and resolution across epochs. Never expire or delete these records. */
+export const oauthRefreshSpentKeys = {
+    family: {
+        name: "oauth-refresh-spent",
+        scope: "connector",
+        prefixes: ["oauth:refresh-spent:"],
+        version: { number: 1, in: "value" },
+        codec: jsonCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    spent: (tokenDigest) => validateStorageKey(`oauth:refresh-spent:${tokenDigest}`),
+};
+/** Expiry is storage-owned; dispatched fingerprints themselves never expire. */
+export const oauthRefreshActiveKeys = {
+    family: {
+        name: "oauth-refresh-active",
+        scope: "connector",
+        prefixes: ["oauth:refresh-active:"],
+        version: { number: 1, in: "value" },
+        codec: jsonCodec,
+        ttl: { kind: "fixed", seconds: OAUTH_REFRESH_LEASE_SECONDS },
+        durable: false,
+    },
+    prefix: "oauth:refresh-active:",
+    holder: (epoch, holder) => validateStorageKey(`oauth:refresh-active:${epoch}:${holder}`),
+};
+/** The values layout 2 stored, each under its historical key. */
+const oauthV2Field = {
+    client: "oauth:client",
+    tokens: "oauth:tokens",
+    pending: "oauth:pending",
+    verifier: "oauth:verifier",
+    state: "oauth:state",
+    discovery: "oauth:discovery",
+};
+/**
+ * Layout 2, read once to migrate it into a grant record and then deleted:
+ * each value at its field key, suffixed `:epoch:<generation>` once a modern
+ * generation owned it; the active generation at `oauth:generation`; a reset's
+ * cleanup lineage at `oauth:cleanup:` and `oauth:cleanup-at:`.
+ */
+export const oauthV2Keys = {
+    family: {
+        name: "oauth-v2",
+        scope: "connector",
+        prefixes: [...Object.values(oauthV2Field), "oauth:generation", "oauth:cleanup:", "oauth:cleanup-at:"],
+        version: { number: 2, in: "value" },
+        codec: textCodec,
+        ttl: { kind: "durable" },
+        durable: true,
+    },
+    field: oauthV2Field,
+    /** One listing covers every layout 2 key; the reader keeps those above. */
+    scan: "oauth:",
+    /** A value's physical key; `epoch` null is the historical unsuffixed name. */
+    value: (key, epoch) => validateStorageKey(epoch === null ? key : `${key}:epoch:${epoch}`),
+    generation: "oauth:generation",
+};
+/** Single-use browser links (`used`/`started`/`failed`/`closed`) and MRTR rounds. */
+export const oauthConnectKeys = {
+    family: {
+        name: "oauth-connect",
+        scope: "connector",
+        prefixes: ["oauth:connect-used:", "oauth:request-used:"],
+        version: { number: 1, in: "untagged" },
+        codec: textCodec,
+        // The link's remaining lifetime, or fifteen minutes when retiring it.
+        ttl: { kind: "fixed", seconds: 15 * 60 },
+        durable: false,
+    },
+    used: (nonce) => validateStorageKey(`oauth:connect-used:${nonce}`),
+    retry: (nonce) => validateStorageKey(`oauth:request-used:${nonce}`),
+};
+/** A bounded, credential-partitioned downstream protocol verdict. */
+export const NEGOTIATION_TTL_SECONDS = 300;
+export const negotiationKeys = {
+    family: {
+        name: "negotiation",
+        scope: "connector",
+        prefixes: ["negotiation:v1:"],
+        version: { number: 1, in: "key" },
+        codec: jsonCodec,
+        ttl: { kind: "fixed", seconds: NEGOTIATION_TTL_SECONDS },
+        durable: false,
+    },
+    verdict: (partitionDigest) => validateStorageKey(`negotiation:v1:${partitionDigest}`),
+};
+/** A downstream MRTR round is consumed once before continuation dispatch. */
+export const inputRetryKeys = {
+    family: {
+        name: "downstream-input-retry",
+        scope: "connector",
+        prefixes: ["input-retry:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: { kind: "fixed", seconds: 10 * 60 },
+        durable: false,
+    },
+    used: (nonce) => validateStorageKey(`input-retry:v1:${nonce}`),
+};
+/**
+ * Every family, for the overlap and coverage checks and for migrations that
+ * copy only what a deployment cannot recreate. Keys a custom connector writes
+ * through its own `ctx.storage` belong to that connector, inside its
+ * namespace, and are not listed here.
+ */
+export const KEY_FAMILIES = [
+    resultKeys.family,
+    stashLedgerKeys.family,
+    catalogKeys.family,
+    responseCacheKeys.family,
+    oauthHandoffKeys.family,
+    accessTokenKeys.family,
+    credentialKeys.family,
+    oauthGrantKeys.family,
+    oauthFlowKeys.family,
+    oauthRefreshKeys.family,
+    oauthRefreshSpentKeys.family,
+    oauthRefreshActiveKeys.family,
+    oauthV2Keys.family,
+    oauthConnectKeys.family,
+    negotiationKeys.family,
+    inputRetryKeys.family,
+    kvCopyKeys.family,
+    kvCutoverKeys.family,
+];
+// Principal, connector, and subject segments are hex digests and connector
+// ids, so none holds a colon.
+const PRINCIPAL_SCOPE = /^principal:[^:]*:/;
+const CONNECTOR_SCOPE = /^conn:[^:]*:/;
+const PARTITION_SCOPE = /^(?:results:|subject:[^:]*:)/;
+/**
+ * The family a physical key belongs to, for reports that count keys without
+ * naming them: one-shot migrations report per family, never per key. A key
+ * no family claims is `connector-owned` when a custom connector wrote it
+ * through its own `ctx.storage`, and `unclassified` otherwise (a key an older release wrote).
+ */
+export function familyOfKey(key) {
+    let rest = key.replace(PRINCIPAL_SCOPE, "");
+    let scope = "root";
+    for (const [pattern, nested] of [
+        [CONNECTOR_SCOPE, "connector"],
+        [PARTITION_SCOPE, "partition"],
+    ]) {
+        const match = pattern.exec(rest);
+        if (match) {
+            rest = rest.slice(match[0].length);
+            scope = nested;
+            break;
+        }
+    }
+    const family = KEY_FAMILIES.find((candidate) => candidate.scope === scope && candidate.prefixes.some((prefix) => rest.startsWith(prefix)));
+    if (family)
+        return family.name;
+    return scope === "connector" ? "connector-owned" : "unclassified";
+}

package/dist/storage/memory.js

@@ -1,3 +1,4 @@
+import { validateStorageKey } from "./keys.js";
 /** In-memory KV store with expiry. The default for dev and Node. */
 export function memoryStorage() {
     const map = new Map();
@@ -36,16 +37,21 @@ export function memoryStorage() {
         });
     };
     return {
+        describe: () => ({ kind: "memory" }),
         async get(key) {
+            validateStorageKey(key);
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
+            validateStorageKey(key);
             write(key, value, opts?.ttlSeconds);
         },
         async delete(key) {
+            validateStorageKey(key);
             map.delete(key);
         },
         async list(prefix) {
+            validateStorageKey(prefix);
             return [...map.keys()]
                 .filter((key) => {
                 fresh(key);
@@ -56,6 +62,7 @@ export function memoryStorage() {
         // Atomic because nothing between the read and the write yields: the body
         // runs to completion before any other call on this map can start.
         async compareAndSet(key, expected, next, opts) {
+            validateStorageKey(key);
             if ((fresh(key)?.value ?? null) !== expected)
                 return false;
             if (next === null)