@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/vault/service.js

@@ -1,5 +1,67 @@
+/**
+ * The Runtime vault (docs/design/runtime/vault.md, architecture §12.9):
+ * administer vaults and credentials, attach them to sessions, and authorize
+ * outbound MCP calls. Storage is the async Session Store (`store/types.ts`);
+ * this module holds no SQL.
+ *
+ * ## Public surface
+ *
+ * ```ts
+ * new VaultService({ store: SessionStore, kek: () => Buffer, fetch: typeof fetch })
+ *
+ * // Administration: each opens its own transaction and writes its audit rows
+ * // in that transaction. Creates and rotations replay by idempotency key.
+ * createVault(body: CreateVaultRequest): Promise<VaultInfo>
+ * listVaults(ownerUserId: string): Promise<VaultInfo[]>
+ * getVault(id: string): Promise<VaultInfo>
+ * assertOwner(id: string, ownerUserId: string): Promise<void>
+ * deleteVault(id: string): Promise<{ id: string }>
+ * createCredential(vaultId: string, body: CreateCredentialRequest): Promise<CredentialInfo>
+ * listCredentials(vaultId: string): Promise<CredentialInfo[]>
+ * getCredential(vaultId: string, id: string): Promise<CredentialInfo>
+ * rotateCredential(vaultId: string, id: string, body: RotateCredentialRequest): Promise<CredentialInfo>
+ * deleteCredential(vaultId: string, id: string): Promise<{ id: string }>
+ *
+ * // Attachment: run inside the caller's session PUT transaction.
+ * assertAttachment(t: Tx, ownerUserId: string, vaultIds: readonly string[], selections: readonly CredentialSelection[], options?: { opaque?: boolean }): Promise<void>
+ * recordAttachment(t: Tx, sessionId: string, vaultIds: readonly string[]): Promise<void>
+ *
+ * // Use: opens its own transactions; never call it inside one.
+ * authorize(input: { sessionId; vaultIds; credentialSelections; url; serverName? }): Promise<AuthorizeResult>
+ *
+ * // Host model credential: each opens its own transaction.
+ * getHostModel(): Promise<HostModelView>
+ * listHostProviders(): Promise<{ providers: HostModelProviderInfo[] }>
+ * putHostModel(body: PutHostModelRequest): Promise<HostModelView>
+ * selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>
+ * readHostModel(): Promise<HostModelSecret | undefined>
+ * updateHostCredential(credential): Promise<void>
+ *
+ * // Rejected caller audit: opens its own transaction.
+ * reject(route: string): Promise<void>
+ * ```
+ *
+ * ## Transactions and I/O
+ *
+ * - No network I/O runs inside a transaction. The KEK getter may touch the
+ *   filesystem (it creates the key file on first use), so methods that
+ *   encrypt or decrypt resolve the KEK before opening their transaction and
+ *   do only in-memory crypto inside it.
+ * - `authorize` reads the attached vaults and the matching credential rows
+ *   (ciphertext only) in one transaction and decides there. A refusal decided
+ *   from those rows (missing vault, ambiguous, selection mismatch) writes its
+ *   audit row in that same transaction. Decryption happens after it commits,
+ *   so the plaintext never enters a transaction. An OAuth refresh calls the
+ *   token endpoint outside any transaction, then stores the rotated secret and
+ *   its `refresh` audit row in one follow-up transaction (re-reading the
+ *   current row there). The `use`/`approved` audit row is written in a final
+ *   transaction before the header is returned: if that write fails,
+ *   `authorize` rejects and no header leaves the vault, so every approved use
+ *   has an audit row. Unreadable ciphertext and refresh failures are audited
+ *   in their own transaction before the refusal is returned.
+ */
 import { createHash, randomUUID } from "node:crypto";
-import { canonical } from "../core/store.js";
+import { canonical } from "../store/canonical.js";
 import { decryptSecret, encryptSecret, VaultCryptoError, } from "./crypto.js";
 import { VaultError } from "./error.js";
 import { hostModelCatalog } from "../model/catalog.js";
@@ -8,50 +70,54 @@ const REFRESH_SKEW_MS = 60_000;
 const HOST_VAULT_ID = "host";
 const HOST_MODEL_ID = "host-model";
 export class VaultService {
-    db;
-    tx;
+    store;
     kek;
     fetchImpl;
-    constructor(db, tx, kek, fetchImpl) {
-        this.db = db;
-        this.tx = tx;
-        this.kek = kek;
-        this.fetchImpl = fetchImpl;
-    }
-    createVault(body) {
-        return this.tx(() => this.replay(`create-vault:${body.idempotencyKey}`, body, () => {
-            const now = new Date().toISOString();
-            const id = randomUUID();
-            this.db
-                .prepare(`INSERT INTO vaults(id,name,owner_user_id,metadata_json,created_at) VALUES(?,?,?,?,?)`)
-                .run(id, body.name, body.ownerUserId, body.metadata ? JSON.stringify(body.metadata) : null, now);
-            const info = this.vaultInfo(id);
-            this.audit({
+    constructor(options) {
+        this.store = options.store;
+        this.kek = options.kek;
+        this.fetchImpl = options.fetch;
+    }
+    // --- administration --------------------------------------------------------
+    async createVault(body) {
+        return this.store.tx((t) => this.replay(t, `create-vault:${body.idempotencyKey}`, body, async () => {
+            const row = {
+                id: randomUUID(),
+                name: body.name,
+                ownerUserId: body.ownerUserId,
+                metadataJson: body.metadata ? JSON.stringify(body.metadata) : null,
+                createdAt: new Date().toISOString(),
+                scope: "user",
+            };
+            await t.insertVault(row);
+            await this.audit(t, {
                 actor: "application",
                 action: "create",
-                vaultId: id,
+                vaultId: row.id,
                 outcome: "created",
             });
-            return info;
+            return vaultInfoOf(row);
         }));
     }
-    listVaults(ownerUserId) {
-        const rows = this.db
-            .prepare(`SELECT id FROM vaults WHERE owner_user_id=? AND scope='user' ORDER BY created_at, id`)
-            .all(ownerUserId);
-        return rows.map((row) => this.vaultInfo(row.id));
-    }
-    getVault(id) {
-        return this.vaultInfo(id);
-    }
-    deleteVault(id) {
-        return this.tx(() => {
-            this.vaultInfo(id);
-            const credentials = this.db
-                .prepare(`SELECT id FROM vault_credentials WHERE vault_id=?`)
-                .all(id);
-            for (const credential of credentials) {
-                this.audit({
+    async listVaults(ownerUserId) {
+        return this.store.tx(async (t) => (await t.vaultsByOwner(ownerUserId)).map(vaultInfoOf));
+    }
+    async getVault(id) {
+        return this.store.tx((t) => this.vaultInfo(t, id));
+    }
+    /** Another owner's vault, or the host vault, is the same 404 as a missing one. */
+    async assertOwner(id, ownerUserId) {
+        await this.store.tx(async (t) => {
+            const row = await t.getVault(id);
+            if (!row || row.scope !== "user" || row.ownerUserId !== ownerUserId)
+                throw new VaultError(404, "Vault not found");
+        });
+    }
+    async deleteVault(id) {
+        return this.store.tx(async (t) => {
+            await this.vaultInfo(t, id);
+            for (const credential of await t.credentialsForVault(id)) {
+                await this.audit(t, {
                     actor: "application",
                     action: "delete",
                     vaultId: id,
@@ -59,9 +125,8 @@ export class VaultService {
                     outcome: "deleted",
                 });
             }
-            this.db.prepare(`DELETE FROM vault_credentials WHERE vault_id=?`).run(id);
-            this.db.prepare(`DELETE FROM vaults WHERE id=?`).run(id);
-            this.audit({
+            await t.deleteVault(id);
+            await this.audit(t, {
                 actor: "application",
                 action: "delete",
                 vaultId: id,
@@ -70,50 +135,55 @@ export class VaultService {
             return { id };
         });
     }
-    createCredential(vaultId, body) {
-        return this.tx(() => this.replay(`create-credential:${vaultId}:${body.idempotencyKey}`, body, () => {
-            this.vaultInfo(vaultId);
+    async createCredential(vaultId, body) {
+        const kek = this.kek();
+        return this.store.tx((t) => this.replay(t, `create-credential:${vaultId}:${body.idempotencyKey}`, body, async () => {
+            await this.vaultInfo(t, vaultId);
             const id = randomUUID();
             const url = normalizeVaultUrl(body.auth.url);
-            const payload = payloadFromCreate(body);
-            this.insertCredential({
+            const type = body.auth.type;
+            const sealed = encryptSecret(kek, credentialAad(vaultId, id, type, url), Buffer.from(JSON.stringify(payloadFromCreate(body)), "utf8"));
+            const row = {
                 id,
                 vaultId,
                 name: body.name,
-                type: body.auth.type,
-                url,
+                type,
+                bindingJson: JSON.stringify({ url }),
                 expiresAt: expiresFromCreate(body),
-                payload,
+                createdAt: new Date().toISOString(),
                 rotatedAt: null,
-            });
-            this.audit({
+                ...sealed,
+            };
+            await t.insertCredential(row);
+            await this.audit(t, {
                 actor: "application",
                 action: "create",
                 vaultId,
                 credentialId: id,
                 outcome: "created",
             });
-            return this.credentialInfo(vaultId, id);
+            return credentialInfoOf(row);
         }));
     }
-    listCredentials(vaultId) {
-        this.vaultInfo(vaultId);
-        const rows = this.db
-            .prepare(`SELECT id FROM vault_credentials WHERE vault_id=? ORDER BY created_at, id`)
-            .all(vaultId);
-        return rows.map((row) => this.credentialInfo(vaultId, row.id));
+    async listCredentials(vaultId) {
+        return this.store.tx(async (t) => {
+            await this.vaultInfo(t, vaultId);
+            return (await t.credentialsForVault(vaultId))
+                .filter(isUserCredential)
+                .map(credentialInfoOf);
+        });
     }
-    getCredential(vaultId, id) {
-        return this.credentialInfo(vaultId, id);
+    async getCredential(vaultId, id) {
+        return this.store.tx(async (t) => credentialInfoOf(await this.credentialRow(t, vaultId, id)));
     }
-    rotateCredential(vaultId, id, body) {
-        return this.tx(() => this.replay(`rotate:${vaultId}:${id}:${body.idempotencyKey}`, body, () => {
-            const row = this.credentialRow(vaultId, id);
+    async rotateCredential(vaultId, id, body) {
+        const kek = this.kek();
+        return this.store.tx((t) => this.replay(t, `rotate:${vaultId}:${id}:${body.idempotencyKey}`, body, async () => {
+            const row = await this.credentialRow(t, vaultId, id);
             if (row.type !== body.auth.type)
                 throw new VaultError(409, "Credential type cannot change");
-            const current = this.readPayload(row);
-            const next = { ...current };
-            let expiresAt = row.expires_at;
+            const next = { ...readPayload(kek, row) };
+            let expiresAt = row.expiresAt;
             if (body.auth.type === "bearer")
                 next.token = body.auth.token;
             else {
@@ -123,24 +193,22 @@ export class VaultService {
                         ? null
                         : requireTimestamp(body.auth.expiresAt);
             }
-            this.writePayload(row, next, expiresAt, new Date().toISOString());
-            this.audit({
+            const updated = await this.writePayload(t, kek, row, next, expiresAt, new Date().toISOString());
+            await this.audit(t, {
                 actor: "application",
                 action: "rotate",
                 vaultId,
                 credentialId: id,
                 outcome: "rotated",
             });
-            return this.credentialInfo(vaultId, id);
+            return credentialInfoOf(updated);
         }));
     }
-    deleteCredential(vaultId, id) {
-        return this.tx(() => {
-            this.credentialRow(vaultId, id);
-            this.db
-                .prepare(`DELETE FROM vault_credentials WHERE id=? AND vault_id=?`)
-                .run(id, vaultId);
-            this.audit({
+    async deleteCredential(vaultId, id) {
+        return this.store.tx(async (t) => {
+            await this.credentialRow(t, vaultId, id);
+            await t.deleteCredential(vaultId, id);
+            await this.audit(t, {
                 actor: "application",
                 action: "delete",
                 vaultId,
@@ -150,30 +218,36 @@ export class VaultService {
             return { id };
         });
     }
-    assertAttachment(ownerUserId, vaultIds, selections) {
+    // --- attachment (caller's transaction) --------------------------------------
+    /**
+     * Checks a session's vaults and selections. Run in the session PUT transaction. `opaque`
+     * (a request acting for a subject) reports another owner's vault as the 404 of a missing one.
+     */
+    async assertAttachment(t, ownerUserId, vaultIds, selections, options = {}) {
         if (new Set(vaultIds).size !== vaultIds.length)
             throw new VaultError(400, "Duplicate vault id");
         if (new Set(selections.map((item) => item.serverName)).size !== selections.length)
             throw new VaultError(400, "Duplicate credential selection");
         for (const id of vaultIds) {
-            const vault = this.vaultRow(id);
+            const vault = await t.getVault(id);
             if (!vault)
                 throw new VaultError(404, "Vault not found");
             if (vault.scope === "host")
                 throw new VaultError(400, "Host vault cannot be attached to a session");
-            if (vault.owner_user_id !== ownerUserId)
-                throw new VaultError(403, "Vault belongs to another user");
+            if (vault.ownerUserId !== ownerUserId)
+                throw options.opaque
+                    ? new VaultError(404, "Vault not found")
+                    : new VaultError(403, "Vault belongs to another user");
         }
         for (const selection of selections) {
-            const row = this.db
-                .prepare(`SELECT vault_id FROM vault_credentials WHERE id=?`)
-                .get(selection.credentialId);
-            if (!row || !vaultIds.includes(row.vault_id))
+            const row = await t.getCredential(selection.credentialId);
+            if (!row || !vaultIds.includes(row.vaultId))
                 throw new VaultError(400, "Credential is not in an attached vault");
         }
     }
-    recordAttachment(sessionId, vaultIds) {
-        this.audit({
+    /** Writes the `attach` audit row. Run in the session PUT transaction. */
+    async recordAttachment(t, sessionId, vaultIds) {
+        await this.audit(t, {
             actor: "application",
             action: "attach",
             sessionId,
@@ -181,66 +255,81 @@ export class VaultService {
             outcome: "attached",
         });
     }
+    // --- use ---------------------------------------------------------------------
     async authorize(input) {
         const url = normalizeVaultUrl(input.url);
-        const missing = input.vaultIds.filter((id) => !this.vaultRow(id));
-        if (missing.length > 0) {
-            this.audit({
-                actor: "host",
-                action: "use",
-                sessionId: input.sessionId,
-                target: url,
-                outcome: "refused",
-            });
-            return {
-                status: "refused",
-                url,
-                credentialIds: [],
-                reason: "vault_missing",
-            };
-        }
-        const matches = input.vaultIds
-            .flatMap((vaultId) => this.rowsForVault(vaultId))
-            .filter((row) => JSON.parse(row.binding_json).url === url)
-            .sort((a, b) => a.id.localeCompare(b.id));
-        const selection = input.serverName
-            ? input.credentialSelections.find((item) => item.serverName === input.serverName)
-            : undefined;
-        if (matches.length === 0)
-            return { status: "unauthenticated", url, headers: {} };
-        const chosen = choose(matches, selection);
-        if (chosen.kind === "refused") {
-            this.audit({
-                actor: "host",
-                action: "use",
-                sessionId: input.sessionId,
-                target: url,
-                outcome: "refused",
-            });
-            return {
-                status: "refused",
-                url,
-                credentialIds: chosen.credentialIds,
-                reason: chosen.reason,
-            };
-        }
-        let row = chosen.row;
+        const decided = await this.store.tx(async (t) => {
+            for (const id of input.vaultIds) {
+                if (await t.getVault(id))
+                    continue;
+                await this.audit(t, {
+                    actor: "host",
+                    action: "use",
+                    sessionId: input.sessionId,
+                    target: url,
+                    outcome: "refused",
+                });
+                return {
+                    result: {
+                        status: "refused",
+                        url,
+                        credentialIds: [],
+                        reason: "vault_missing",
+                    },
+                };
+            }
+            const matches = [];
+            for (const vaultId of input.vaultIds)
+                for (const row of await t.credentialsForVault(vaultId))
+                    if (bindingUrl(row) === url)
+                        matches.push(row);
+            matches.sort((a, b) => a.id.localeCompare(b.id));
+            if (matches.length === 0)
+                return { result: { status: "unauthenticated", url, headers: {} } };
+            const selection = input.serverName
+                ? input.credentialSelections.find((item) => item.serverName === input.serverName)
+                : undefined;
+            const chosen = choose(matches, selection);
+            if (chosen.kind === "refused") {
+                await this.audit(t, {
+                    actor: "host",
+                    action: "use",
+                    sessionId: input.sessionId,
+                    target: url,
+                    outcome: "refused",
+                });
+                return {
+                    result: {
+                        status: "refused",
+                        url,
+                        credentialIds: chosen.credentialIds,
+                        reason: chosen.reason,
+                    },
+                };
+            }
+            return { row: chosen.row };
+        });
+        if ("result" in decided)
+            return decided.result;
+        // Committed. Plaintext exists only from here to the return.
+        const row = decided.row;
+        const kek = this.kek();
         let payload;
         try {
-            payload = this.readPayload(row);
+            payload = readPayload(kek, row);
         }
         catch (error) {
             if (!(error instanceof VaultCryptoError))
                 throw error;
-            this.audit({
+            await this.store.tx((t) => this.audit(t, {
                 actor: "host",
                 action: "use",
-                vaultId: row.vault_id,
+                vaultId: row.vaultId,
                 credentialId: row.id,
                 sessionId: input.sessionId,
                 target: url,
                 outcome: "refused",
-            });
+            }));
             return {
                 status: "refused",
                 url,
@@ -248,11 +337,10 @@ export class VaultService {
                 reason: "unreadable",
             };
         }
-        if (row.type === "oauth" && dueForRefresh(row.expires_at)) {
-            const refreshed = await this.refresh(row, payload, input.sessionId, url);
+        if (row.type === "oauth" && dueForRefresh(row.expiresAt)) {
+            const refreshed = await this.refresh(kek, row, payload, input.sessionId, url);
             if (refreshed.status === "refused")
                 return refreshed;
-            row = this.credentialRow(row.vault_id, row.id);
             payload = refreshed.payload;
         }
         const token = row.type === "bearer" ? payload.token : payload.accessToken;
@@ -264,68 +352,62 @@ export class VaultService {
                 reason: "unreadable",
             };
         }
-        this.audit({
+        await this.store.tx((t) => this.audit(t, {
             actor: "host",
             action: "use",
-            vaultId: row.vault_id,
+            vaultId: row.vaultId,
             credentialId: row.id,
             sessionId: input.sessionId,
             target: url,
             outcome: "approved",
-        });
+        }));
         return {
             status: "authorized",
             url,
             headers: { authorization: `Bearer ${token}` },
         };
     }
-    getHostModel() {
-        const row = this.activeHostCredentialRow();
-        if (!row)
-            return { configured: false };
-        const binding = modelBinding(row);
-        return {
-            configured: true,
-            provider: binding.provider,
-            model: binding.model,
-            authType: binding.authType,
-            ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
-        };
-    }
-    listHostProviders() {
-        const active = this.activeProviderId();
-        const catalog = new Map(hostModelCatalog().providers.map((provider) => [provider.id, provider.name]));
-        const providers = this.hostModelRows().map((row) => {
-            const binding = modelBinding(row);
-            return {
-                id: binding.provider,
-                name: catalog.get(binding.provider) ??
-                    (binding.provider === "custom"
-                        ? "Custom OpenAI-compatible"
-                        : binding.provider),
-                model: binding.model,
-                authType: binding.authType,
-                ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
-                lastUpdated: row.rotated_at ?? row.created_at,
-                active: binding.provider === active,
-            };
+    // --- host model ----------------------------------------------------------------
+    async getHostModel() {
+        return this.store.tx((t) => this.hostModelView(t));
+    }
+    async listHostProviders() {
+        return this.store.tx(async (t) => {
+            const active = await this.activeProviderId(t);
+            const catalog = new Map(hostModelCatalog().providers.map((provider) => [provider.id, provider.name]));
+            const providers = (await this.hostModelRows(t)).map((row) => {
+                const binding = modelBinding(row);
+                return {
+                    id: binding.provider,
+                    name: catalog.get(binding.provider) ??
+                        (binding.provider === "custom"
+                            ? "Custom OpenAI-compatible"
+                            : binding.provider),
+                    model: binding.model,
+                    authType: binding.authType,
+                    ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
+                    lastUpdated: row.rotatedAt ?? row.createdAt,
+                    active: binding.provider === active,
+                };
+            });
+            providers.sort((left, right) => left.name.localeCompare(right.name));
+            return { providers };
         });
-        providers.sort((left, right) => left.name.localeCompare(right.name));
-        return { providers };
     }
-    putHostModel(body) {
-        return this.tx(() => this.replay(`host-model:${body.idempotencyKey}`, body, () => {
+    async putHostModel(body) {
+        const kek = this.kek();
+        return this.store.tx((t) => this.replay(t, `host-model:${body.idempotencyKey}`, body, async () => {
             this.validateHostModel(body);
-            this.ensureHostVault();
+            await this.ensureHostVault(t);
             const credentialId = hostModelCredentialId(body.provider);
-            this.deleteHostProviderRows(body.provider);
+            await this.deleteHostProviderRows(t, body.provider);
             const payload = body.auth.type === "api_key"
                 ? {
                     apiKey: body.auth.key,
                     ...(body.auth.env ? { env: body.auth.env } : {}),
                 }
                 : { oauth: body.auth };
-            this.insertHostCredential({
+            await this.insertHostCredential(t, kek, {
                 id: credentialId,
                 provider: body.provider,
                 model: body.model,
@@ -333,28 +415,29 @@ export class VaultService {
                 authType: body.auth.type,
                 payload,
             });
-            this.setActiveProvider(body.provider);
-            this.audit({
+            await this.setActiveProvider(t, body.provider);
+            await this.audit(t, {
                 actor: "application",
                 action: "rotate",
                 vaultId: HOST_VAULT_ID,
                 credentialId,
                 outcome: "rotated",
             });
-            return this.getHostModel();
+            return this.hostModelView(t);
         }));
     }
-    selectHostModel(body) {
-        return this.tx(() => this.replay(`host-model-select:${body.idempotencyKey}`, body, () => {
+    async selectHostModel(body) {
+        const kek = this.kek();
+        return this.store.tx((t) => this.replay(t, `host-model-select:${body.idempotencyKey}`, body, async () => {
             this.validateHostModel(body);
-            const row = this.hostCredentialRowFor(body.provider);
+            const row = await this.hostCredentialRowFor(t, body.provider);
             if (!row)
                 throw new VaultError(404, "Model provider is not configured");
             const binding = modelBinding(row);
-            const payload = this.readHostPayload(row, binding);
+            const payload = readHostPayload(kek, row, binding);
             const credentialId = hostModelCredentialId(body.provider);
-            this.deleteHostProviderRows(body.provider);
-            this.insertHostCredential({
+            await this.deleteHostProviderRows(t, body.provider);
+            await this.insertHostCredential(t, kek, {
                 id: credentialId,
                 provider: body.provider,
                 model: body.model,
@@ -362,23 +445,24 @@ export class VaultService {
                 authType: binding.authType,
                 payload,
             });
-            this.setActiveProvider(body.provider);
-            this.audit({
+            await this.setActiveProvider(t, body.provider);
+            await this.audit(t, {
                 actor: "application",
                 action: "rotate",
                 vaultId: HOST_VAULT_ID,
                 credentialId,
                 outcome: "rotated",
             });
-            return this.getHostModel();
+            return this.hostModelView(t);
         }));
     }
-    readHostModel() {
-        const row = this.activeHostCredentialRow();
+    /** Reads the active host model secret. Decrypts after the read commits. */
+    async readHostModel() {
+        const row = await this.store.tx((t) => this.activeHostCredentialRow(t));
         if (!row)
             return undefined;
         const binding = modelBinding(row);
-        const payload = this.readHostPayload(row, binding);
+        const payload = readHostPayload(this.kek(), row, binding);
         const credential = binding.authType === "oauth"
             ? { type: "oauth", ...payload.oauth }
             : {
@@ -394,9 +478,10 @@ export class VaultService {
             credential,
         };
     }
-    updateHostCredential(credential) {
-        this.tx(() => {
-            const row = this.activeHostCredentialRow();
+    async updateHostCredential(credential) {
+        const kek = this.kek();
+        await this.store.tx(async (t) => {
+            const row = await this.activeHostCredentialRow(t);
             if (!row)
                 throw new VaultError(404, "Model provider is not configured");
             const binding = modelBinding(row);
@@ -406,34 +491,37 @@ export class VaultService {
                     apiKey: credential.key,
                     ...(credential.env ? { env: credential.env } : {}),
                 };
-            const aad = hostModelAad(binding.provider, binding.model);
-            const sealed = encryptSecret(this.kek(), aad, Buffer.from(JSON.stringify(payload), "utf8"));
-            this.db
-                .prepare(`UPDATE vault_credentials
-           SET type='model', binding_json=?, kek_id=?, nonce=?, ciphertext=?, wrapped_dek=?, rotated_at=?
-           WHERE id=?`)
-                .run(JSON.stringify({ ...binding, authType: credential.type }), sealed.kekId, sealed.nonce, sealed.ciphertext, sealed.wrappedDek, new Date().toISOString(), row.id);
+            const sealed = encryptSecret(kek, hostModelAad(binding.provider, binding.model), Buffer.from(JSON.stringify(payload), "utf8"));
+            await t.updateCredential(HOST_VAULT_ID, row.id, {
+                type: "model",
+                bindingJson: JSON.stringify({ ...binding, authType: credential.type }),
+                ...sealed,
+                rotatedAt: new Date().toISOString(),
+            });
         });
     }
-    reject(route) {
-        this.audit({
+    // --- rejected callers ---------------------------------------------------------
+    async reject(route) {
+        await this.store.tx((t) => this.audit(t, {
             actor: "executor",
             action: "reject",
             target: route,
             outcome: "rejected",
-        });
+        }));
     }
-    async refresh(row, payload, sessionId, url) {
-        const failRefresh = () => {
-            this.audit({
+    // --- internals -----------------------------------------------------------------
+    /** Calls the token endpoint outside any transaction, then stores the result. */
+    async refresh(kek, row, payload, sessionId, url) {
+        const failRefresh = async () => {
+            await this.store.tx((t) => this.audit(t, {
                 actor: "host",
                 action: "refresh",
-                vaultId: row.vault_id,
+                vaultId: row.vaultId,
                 credentialId: row.id,
                 sessionId,
                 target: payload.tokenEndpoint,
                 outcome: "refresh_failed",
-            });
+            }));
             return {
                 status: "refused",
                 url,
@@ -443,6 +531,7 @@ export class VaultService {
         };
         if (!payload.refreshToken || !payload.tokenEndpoint || !payload.clientId)
             return failRefresh();
+        let next;
         try {
             const body = new URLSearchParams({
                 grant_type: "refresh_token",
@@ -474,7 +563,7 @@ export class VaultService {
             const json = (await response.json());
             if (typeof json.access_token !== "string" || json.access_token.length === 0)
                 return failRefresh();
-            const next = {
+            next = {
                 ...payload,
                 accessToken: json.access_token,
                 refreshToken: typeof json.refresh_token === "string"
@@ -484,102 +573,71 @@ export class VaultService {
             const expiresAt = typeof json.expires_in === "number" && Number.isFinite(json.expires_in)
                 ? new Date(Date.now() + json.expires_in * 1000).toISOString()
                 : null;
-            this.tx(() => {
-                const current = this.credentialRow(row.vault_id, row.id);
-                this.writePayload(current, next, expiresAt, new Date().toISOString());
-                this.audit({
+            await this.store.tx(async (t) => {
+                const current = await this.credentialRow(t, row.vaultId, row.id);
+                await this.writePayload(t, kek, current, next, expiresAt, new Date().toISOString());
+                await this.audit(t, {
                     actor: "host",
                     action: "refresh",
-                    vaultId: row.vault_id,
+                    vaultId: row.vaultId,
                     credentialId: row.id,
                     sessionId,
                     target: payload.tokenEndpoint,
                     outcome: "approved",
                 });
             });
-            return { status: "ok", payload: next };
         }
         catch {
             return failRefresh();
         }
+        return { status: "ok", payload: next };
     }
-    replay(key, body, create) {
+    async replay(t, key, body, create) {
         const hash = createHash("sha256")
             .update(requestHash(body))
             .digest("hex");
-        const existing = this.db
-            .prepare(`SELECT body_hash, response FROM vault_idempotency WHERE id=?`)
-            .get(key);
+        const existing = await t.getVaultIdempotency(key);
         if (existing) {
-            if (existing.body_hash !== hash)
+            if (existing.bodyHash !== hash)
                 throw new VaultError(409, "Idempotency key already binds another request");
             return JSON.parse(existing.response);
         }
-        const created = create();
-        this.db
-            .prepare(`INSERT INTO vault_idempotency(id, body_hash, response) VALUES(?,?,?)`)
-            .run(key, hash, JSON.stringify(created));
+        const created = await create();
+        await t.insertVaultIdempotency({
+            id: key,
+            bodyHash: hash,
+            response: JSON.stringify(created),
+        });
         return created;
     }
-    insertCredential(input) {
-        const aad = credentialAad(input.vaultId, input.id, input.type, input.url);
-        const sealed = encryptSecret(this.kek(), aad, Buffer.from(JSON.stringify(input.payload), "utf8"));
-        this.db
-            .prepare(`INSERT INTO vault_credentials(
-          id, vault_id, name, type, binding_json, expires_at, created_at, rotated_at,
-          kek_id, nonce, ciphertext, wrapped_dek
-        ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`)
-            .run(input.id, input.vaultId, input.name, input.type, JSON.stringify({ url: input.url }), input.expiresAt, new Date().toISOString(), input.rotatedAt, sealed.kekId, sealed.nonce, sealed.ciphertext, sealed.wrappedDek);
-    }
-    writePayload(row, payload, expiresAt, rotatedAt) {
-        const url = JSON.parse(row.binding_json).url;
-        const aad = credentialAad(row.vault_id, row.id, row.type, url);
-        const sealed = encryptSecret(this.kek(), aad, Buffer.from(JSON.stringify(payload), "utf8"));
-        this.db
-            .prepare(`UPDATE vault_credentials
-         SET expires_at=?, rotated_at=?, kek_id=?, nonce=?, ciphertext=?, wrapped_dek=?
-         WHERE id=?`)
-            .run(expiresAt, rotatedAt, sealed.kekId, sealed.nonce, sealed.ciphertext, sealed.wrappedDek, row.id);
-    }
-    readPayload(row) {
-        const url = JSON.parse(row.binding_json).url;
-        const aad = credentialAad(row.vault_id, row.id, row.type, url);
-        const plaintext = decryptSecret(this.kek(), aad, Buffer.from(row.nonce), Buffer.from(row.ciphertext), Buffer.from(row.wrapped_dek), row.kek_id);
-        try {
-            return JSON.parse(plaintext.toString("utf8"));
-        }
-        finally {
-            plaintext.fill(0);
-        }
+    /** Re-seals a user credential's payload and returns the updated row. */
+    async writePayload(t, kek, row, payload, expiresAt, rotatedAt) {
+        const sealed = encryptSecret(kek, credentialAad(row.vaultId, row.id, row.type, bindingUrl(row)), Buffer.from(JSON.stringify(payload), "utf8"));
+        const patch = { expiresAt, rotatedAt, ...sealed };
+        if (!(await t.updateCredential(row.vaultId, row.id, patch)))
+            throw new VaultError(404, "Credential not found");
+        return { ...row, ...patch };
     }
-    vaultInfo(id) {
-        const row = this.vaultRow(id);
+    async vaultInfo(t, id) {
+        const row = await t.getVault(id);
         if (!row || row.scope === "host")
             throw new VaultError(404, "Vault not found");
-        return {
-            id: row.id,
-            name: row.name,
-            ownerUserId: row.owner_user_id,
-            ...(row.metadata_json
-                ? { metadata: JSON.parse(row.metadata_json) }
-                : {}),
-            createdAt: row.created_at,
-        };
+        return vaultInfoOf(row);
     }
-    vaultRow(id) {
-        return this.db
-            .prepare(`SELECT id, name, owner_user_id, metadata_json, created_at, scope FROM vaults WHERE id=?`)
-            .get(id);
-    }
-    ensureHostVault() {
-        const existing = this.vaultRow(HOST_VAULT_ID);
+    async ensureHostVault(t) {
+        const existing = await t.getVault(HOST_VAULT_ID);
         if (existing?.scope === "host")
             return;
         if (existing)
             throw new VaultError(409, "Host vault id is already used");
-        this.db
-            .prepare(`INSERT INTO vaults(id,name,owner_user_id,metadata_json,created_at,scope) VALUES(?,?,?,?,?,?)`)
-            .run(HOST_VAULT_ID, "Host", "host", null, new Date().toISOString(), "host");
+        await t.insertVault({
+            id: HOST_VAULT_ID,
+            name: "Host",
+            ownerUserId: "host",
+            metadataJson: null,
+            createdAt: new Date().toISOString(),
+            scope: "host",
+        });
     }
     validateHostModel(body) {
         if (body.provider === "custom") {
@@ -604,37 +662,40 @@ export class VaultService {
         if (!provider.models.some((item) => item.id === body.model))
             throw new VaultError(400, "Unknown model.");
     }
-    insertHostCredential(input) {
-        const aad = hostModelAad(input.provider, input.model);
-        const sealed = encryptSecret(this.kek(), aad, Buffer.from(JSON.stringify(input.payload), "utf8"));
-        this.db
-            .prepare(`INSERT INTO vault_credentials(
-          id, vault_id, name, type, binding_json, expires_at, created_at, rotated_at,
-          kek_id, nonce, ciphertext, wrapped_dek
-        ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`)
-            .run(input.id, HOST_VAULT_ID, input.provider, "model", JSON.stringify({
-            provider: input.provider,
-            model: input.model,
-            ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
-            authType: input.authType,
-        }), null, new Date().toISOString(), null, sealed.kekId, sealed.nonce, sealed.ciphertext, sealed.wrappedDek);
-    }
-    readHostPayload(row, binding) {
-        const plaintext = decryptSecret(this.kek(), hostModelAad(binding.provider, binding.model), Buffer.from(row.nonce), Buffer.from(row.ciphertext), Buffer.from(row.wrapped_dek), row.kek_id);
-        try {
-            return JSON.parse(plaintext.toString("utf8"));
-        }
-        finally {
-            plaintext.fill(0);
-        }
+    async insertHostCredential(t, kek, input) {
+        const sealed = encryptSecret(kek, hostModelAad(input.provider, input.model), Buffer.from(JSON.stringify(input.payload), "utf8"));
+        await t.insertCredential({
+            id: input.id,
+            vaultId: HOST_VAULT_ID,
+            name: input.provider,
+            type: "model",
+            bindingJson: JSON.stringify({
+                provider: input.provider,
+                model: input.model,
+                ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+                authType: input.authType,
+            }),
+            expiresAt: null,
+            createdAt: new Date().toISOString(),
+            rotatedAt: null,
+            ...sealed,
+        });
     }
-    hostModelRows() {
-        return this.db
-            .prepare(`SELECT id, vault_id, name, type, binding_json, expires_at, created_at, rotated_at,
-                  kek_id, nonce, ciphertext, wrapped_dek
-           FROM vault_credentials WHERE vault_id=? AND type='model'
-           ORDER BY created_at, id`)
-            .all(HOST_VAULT_ID).filter((row) => {
+    async hostModelView(t) {
+        const row = await this.activeHostCredentialRow(t);
+        if (!row)
+            return { configured: false };
+        const binding = modelBinding(row);
+        return {
+            configured: true,
+            provider: binding.provider,
+            model: binding.model,
+            authType: binding.authType,
+            ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
+        };
+    }
+    async hostModelRows(t) {
+        return (await t.credentialsForVault(HOST_VAULT_ID, { type: "model" })).filter((row) => {
             try {
                 modelBinding(row);
                 return true;
@@ -644,33 +705,39 @@ export class VaultService {
             }
         });
     }
-    hostCredentialRowFor(provider) {
+    async hostCredentialRowFor(t, provider) {
         const preferred = hostModelCredentialId(provider);
-        const rows = this.hostModelRows();
+        const rows = await this.hostModelRows(t);
         return (rows.find((row) => row.id === preferred) ??
             rows.find((row) => modelBinding(row).provider === provider));
     }
-    activeHostCredentialRow() {
-        const active = this.activeProviderId();
+    async activeHostCredentialRow(t) {
+        const active = await this.activeProviderId(t);
         if (!active)
             return undefined;
-        return this.hostCredentialRowFor(active);
+        return this.hostCredentialRowFor(t, active);
     }
-    activeProviderId() {
-        const vault = this.vaultRow(HOST_VAULT_ID);
-        if (vault?.metadata_json) {
+    async activeProviderId(t) {
+        const vault = await t.getVault(HOST_VAULT_ID);
+        if (vault?.metadataJson) {
+            let activeProvider;
             try {
-                const metadata = JSON.parse(vault.metadata_json);
-                if (typeof metadata.activeProvider === "string" &&
-                    metadata.activeProvider &&
-                    this.hostCredentialRowFor(metadata.activeProvider))
-                    return metadata.activeProvider;
+                activeProvider = JSON.parse(vault.metadataJson).activeProvider;
             }
             catch {
                 /* Fall through to the only configured provider. */
             }
+            if (typeof activeProvider === "string" && activeProvider) {
+                try {
+                    if (await this.hostCredentialRowFor(t, activeProvider))
+                        return activeProvider;
+                }
+                catch {
+                    /* An invalid provider id falls through, as before. */
+                }
+            }
         }
-        const rows = this.hostModelRows();
+        const rows = await this.hostModelRows(t);
         if (rows.length === 0)
             return undefined;
         if (rows.length === 1)
@@ -680,57 +747,84 @@ export class VaultService {
             return modelBinding(legacy).provider;
         return modelBinding(rows[0]).provider;
     }
-    setActiveProvider(provider) {
-        this.ensureHostVault();
-        this.db
-            .prepare(`UPDATE vaults SET metadata_json=? WHERE id=?`)
-            .run(JSON.stringify({ activeProvider: provider }), HOST_VAULT_ID);
+    async setActiveProvider(t, provider) {
+        await this.ensureHostVault(t);
+        await t.updateVaultMetadata(HOST_VAULT_ID, JSON.stringify({ activeProvider: provider }));
     }
-    deleteHostProviderRows(provider) {
-        const ids = this.hostModelRows()
+    async deleteHostProviderRows(t, provider) {
+        const ids = (await this.hostModelRows(t))
             .filter((row) => modelBinding(row).provider === provider)
             .map((row) => row.id);
         ids.push(hostModelCredentialId(provider));
         for (const id of new Set(ids))
-            this.db
-                .prepare(`DELETE FROM vault_credentials WHERE id=? AND vault_id=?`)
-                .run(id, HOST_VAULT_ID);
+            await t.deleteCredential(HOST_VAULT_ID, id);
     }
-    credentialInfo(vaultId, id) {
-        const row = this.credentialRow(vaultId, id);
-        return {
-            id: row.id,
-            vaultId: row.vault_id,
-            name: row.name,
-            type: row.type,
-            binding: JSON.parse(row.binding_json),
-            ...(row.expires_at ? { expiresAt: row.expires_at } : {}),
-            createdAt: row.created_at,
-            ...(row.rotated_at ? { rotatedAt: row.rotated_at } : {}),
-        };
-    }
-    credentialRow(vaultId, id) {
-        const row = this.db
-            .prepare(`SELECT id, vault_id, name, type, binding_json, expires_at, created_at, rotated_at,
-                kek_id, nonce, ciphertext, wrapped_dek
-         FROM vault_credentials WHERE id=? AND vault_id=?`)
-            .get(id, vaultId);
-        if (!row || row.type === "model")
+    async credentialRow(t, vaultId, id) {
+        const row = await t.getCredential(id);
+        if (!row || row.vaultId !== vaultId || !isUserCredential(row))
             throw new VaultError(404, "Credential not found");
         return row;
     }
-    rowsForVault(vaultId) {
-        return this.db
-            .prepare(`SELECT id, vault_id, name, type, binding_json, expires_at, created_at, rotated_at,
-                kek_id, nonce, ciphertext, wrapped_dek
-         FROM vault_credentials WHERE vault_id=?`)
-            .all(vaultId);
+    async audit(t, entry) {
+        await t.insertVaultAudit({
+            id: randomUUID(),
+            at: new Date().toISOString(),
+            actor: entry.actor,
+            action: entry.action,
+            vaultId: entry.vaultId ?? null,
+            credentialId: entry.credentialId ?? null,
+            sessionId: entry.sessionId ?? null,
+            target: entry.target ?? null,
+            outcome: entry.outcome,
+        });
+    }
+}
+function isUserCredential(row) {
+    return row.type !== "model";
+}
+function bindingUrl(row) {
+    return JSON.parse(row.bindingJson).url;
+}
+function vaultInfoOf(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        ownerUserId: row.ownerUserId,
+        ...(row.metadataJson
+            ? { metadata: JSON.parse(row.metadataJson) }
+            : {}),
+        createdAt: row.createdAt,
+    };
+}
+function credentialInfoOf(row) {
+    return {
+        id: row.id,
+        vaultId: row.vaultId,
+        name: row.name,
+        type: row.type,
+        binding: JSON.parse(row.bindingJson),
+        ...(row.expiresAt ? { expiresAt: row.expiresAt } : {}),
+        createdAt: row.createdAt,
+        ...(row.rotatedAt ? { rotatedAt: row.rotatedAt } : {}),
+    };
+}
+function readPayload(kek, row) {
+    const aad = credentialAad(row.vaultId, row.id, row.type, bindingUrl(row));
+    const plaintext = decryptSecret(kek, aad, Buffer.from(row.nonce), Buffer.from(row.ciphertext), Buffer.from(row.wrappedDek), row.kekId);
+    try {
+        return JSON.parse(plaintext.toString("utf8"));
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+function readHostPayload(kek, row, binding) {
+    const plaintext = decryptSecret(kek, hostModelAad(binding.provider, binding.model), Buffer.from(row.nonce), Buffer.from(row.ciphertext), Buffer.from(row.wrappedDek), row.kekId);
+    try {
+        return JSON.parse(plaintext.toString("utf8"));
     }
-    audit(entry) {
-        this.db
-            .prepare(`INSERT INTO vault_audit(id, at, actor, action, vault_id, credential_id, session_id, target, outcome)
-         VALUES(?,?,?,?,?,?,?,?,?)`)
-            .run(randomUUID(), new Date().toISOString(), entry.actor, entry.action, entry.vaultId ?? null, entry.credentialId ?? null, entry.sessionId ?? null, entry.target ?? null, entry.outcome);
+    finally {
+        plaintext.fill(0);
     }
 }
 function choose(matches, selection) {
@@ -796,7 +890,7 @@ function requireTimestamp(value) {
     return new Date(Date.parse(value)).toISOString();
 }
 function modelBinding(row) {
-    const binding = JSON.parse(row.binding_json);
+    const binding = JSON.parse(row.bindingJson);
     if (!binding.provider || !binding.model || !binding.authType)
         throw new VaultError(500, "Host model credential is unreadable");
     return binding;