studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/core/secrets/dual-write.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Dual-write helpers — Phase 5 of the secrets refactor.
+ *
+ * Every legacy writer of a configuration file (user.json, workspace.json,
+ * connectors/*.json) also mirrors the registry-mapped fields into the
+ * encrypted store. The legacy file remains authoritative through Phase 5;
+ * Phase 6 flipped the read path so the store is the source of truth at
+ * read time.
+ *
+ * Failure modes are deliberately non-fatal: a dropped dual-write must
+ * never block the legacy write, because the file is still the source of
+ * truth. Failures route to `console.warn` for now — Phase 11 swaps in the
+ * sanitizing log wrapper.
+ *
+ * Idempotency is provided by the store itself: writes use INSERT … ON
+ * CONFLICT DO UPDATE, so writing the same key twice yields a single row
+ * whose `updated_at` advances.
+ *
+ * `looksLikeEnvPlaceholder()` filters `$ENV_VAR` strings out — connector
+ * configs use those as placeholders, and the literal `$FOO_AUTH` is not
+ * actually a credential value worth mirroring into the store.
+ *
+ * After the scope-collapse refactor, the store is single-tier (the
+ * process IS the workspace), so the mirror helpers no longer thread a
+ * scope or scopeId — every write lands in the single secrets.db.
+ */
+import type { ActorContext } from './SecretStore.js';
+/**
+ * Returns true when the store singleton was successfully initialized at
+ * boot. Every dual-write entry point guards on this before touching the
+ * store. Historically gated on the `STUDIOGRAPH_NEW_STORE` env flag too;
+ * the flag was removed once Phase 6 stabilized in production.
+ */
+export declare function dualWriteEnabled(): boolean;
+interface MirrorContext {
+    actor: ActorContext;
+}
+/**
+ * Dual-write `user.json` fields into the encrypted store. The mapping
+ * from user.json path → registry key is inlined below; Phase 12b
+ * (2026-05-12) dropped the registry's `migrationSource` annotation
+ * that used to drive this iteration, since it was the annotation's
+ * sole remaining consumer (the importer was removed in Phase 12a).
+ *
+ * The actor is `{ type: 'system', systemId: 'dual-write' }` because the
+ * caller is a file writer, not a user action; UI-driven changes that
+ * route through the Phase 7 APIs supply a real user actor.
+ */
+export declare function mirrorUserConfig(config: unknown, ctx?: MirrorContext): Promise<void>;
+/**
+ * Dual-write a connector config. Iterates the connector-secret registry
+ * entries and resolves their paths under the specific connector's config
+ * (e.g., `headers.Authorization` → `connector.<name>.auth`).
+ *
+ * The registry uses pattern names like `connector.<name>.auth`; we expand
+ * to a concrete key per connector at write time. `<name>` is the connector
+ * name verbatim, lowercased for stability — connector names are already
+ * url-safe slugs per `parseConfigBlock`.
+ */
+export declare function mirrorConnectorConfig(config: {
+    name: string;
+    headers?: Record<string, string>;
+    oauth?: {
+        client_secret?: string;
+    };
+} & Record<string, unknown>, ctx?: MirrorContext): Promise<void>;
+/**
+ * Dual-write workspace.json into the store. Covers the R2 credentials
+ * (always-secret), the three R2 structural fields (workspace-setting,
+ * added 2026-05-12 so the Settings UI can fully configure R2), and the
+ * legacy search.* block.
+ *
+ * Why structural fields dual-write too: post-2026-05-12 the store is
+ * the source of truth for R2 structural config, but `studiograph r2
+ * setup` (and any other workspace.writeConfig caller) still writes the
+ * file. Without this mirror, every CLI invocation would silently leave
+ * the store stale. Pair this with the one-shot r2-structural-migration
+ * that covers the first-boot case.
+ */
+export declare function mirrorWorkspaceConfig(config: unknown, ctx?: MirrorContext): Promise<void>;
+export {};

package/dist/core/secrets/dual-write.js

@@ -0,0 +1,247 @@
+/**
+ * Dual-write helpers — Phase 5 of the secrets refactor.
+ *
+ * Every legacy writer of a configuration file (user.json, workspace.json,
+ * connectors/*.json) also mirrors the registry-mapped fields into the
+ * encrypted store. The legacy file remains authoritative through Phase 5;
+ * Phase 6 flipped the read path so the store is the source of truth at
+ * read time.
+ *
+ * Failure modes are deliberately non-fatal: a dropped dual-write must
+ * never block the legacy write, because the file is still the source of
+ * truth. Failures route to `console.warn` for now — Phase 11 swaps in the
+ * sanitizing log wrapper.
+ *
+ * Idempotency is provided by the store itself: writes use INSERT … ON
+ * CONFLICT DO UPDATE, so writing the same key twice yields a single row
+ * whose `updated_at` advances.
+ *
+ * `looksLikeEnvPlaceholder()` filters `$ENV_VAR` strings out — connector
+ * configs use those as placeholders, and the literal `$FOO_AUTH` is not
+ * actually a credential value worth mirroring into the store.
+ *
+ * After the scope-collapse refactor, the store is single-tier (the
+ * process IS the workspace), so the mirror helpers no longer thread a
+ * scope or scopeId — every write lands in the single secrets.db.
+ */
+import { getKeyDef } from './registry.js';
+import { getSecretStore, hasSecretStore } from './index.js';
+/**
+ * Returns true when the store singleton was successfully initialized at
+ * boot. Every dual-write entry point guards on this before touching the
+ * store. Historically gated on the `STUDIOGRAPH_NEW_STORE` env flag too;
+ * the flag was removed once Phase 6 stabilized in production.
+ */
+export function dualWriteEnabled() {
+    return hasSecretStore();
+}
+/**
+ * `$ENV_VAR` placeholder values are written into connector configs as the
+ * sanitized form of a real secret. Mirroring them into the encrypted store
+ * would be pointless and would shadow whatever the env variable actually
+ * resolves to. Skip them.
+ */
+function looksLikeEnvPlaceholder(s) {
+    return typeof s === 'string' && /^\$[A-Z_][A-Z0-9_]*$/.test(s);
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Pull a nested value out of a plain object using a dot-separated path.
+ * Returns undefined for any missing intermediate.
+ */
+function readPath(obj, path) {
+    if (!obj || typeof obj !== 'object')
+        return undefined;
+    const parts = path.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+/**
+ * Whether a registry entry lives in the workspace secrets.db at all
+ * (vs bootstrap or user-* which live elsewhere).
+ */
+function isStoreManaged(c) {
+    return c === 'workspace-secret' || c === 'workspace-setting';
+}
+/**
+ * Best-effort wrapper that swallows store errors. Logs to stderr so a
+ * lost mirror is visible without bringing the legacy write down with it.
+ */
+async function safeMirror(label, fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console
+        console.warn(`[secrets] dual-write ${label} failed: ${msg}`);
+    }
+}
+const DEFAULT_ACTOR = { type: 'system', systemId: 'dual-write' };
+/**
+ * Mirror a single value into the store under a canonical registry key.
+ * Routes to the secret or settings table based on classification. Empty
+ * strings and undefined skip the write entirely — callers that want to
+ * clear a value should call the delete API explicitly. `$ENV_VAR`
+ * placeholders are skipped too (see module comment).
+ */
+async function mirrorOne(def, value, ctx) {
+    if (value === undefined || value === null || value === '')
+        return;
+    if (looksLikeEnvPlaceholder(value))
+        return;
+    if (!isStoreManaged(def.classification))
+        return; // bootstrap or user-* — not the store's job.
+    const store = getSecretStore();
+    const isSecret = def.classification.endsWith('-secret');
+    if (isSecret) {
+        if (!isNonEmptyString(value))
+            return;
+        await store.set({ key: def.name, value }, ctx.actor);
+        return;
+    }
+    // Setting: any JSON-serializable value goes through.
+    await store.set({ key: def.name, value }, ctx.actor);
+}
+/**
+ * Dual-write `user.json` fields into the encrypted store. The mapping
+ * from user.json path → registry key is inlined below; Phase 12b
+ * (2026-05-12) dropped the registry's `migrationSource` annotation
+ * that used to drive this iteration, since it was the annotation's
+ * sole remaining consumer (the importer was removed in Phase 12a).
+ *
+ * The actor is `{ type: 'system', systemId: 'dual-write' }` because the
+ * caller is a file writer, not a user action; UI-driven changes that
+ * route through the Phase 7 APIs supply a real user actor.
+ */
+export async function mirrorUserConfig(config, ctx = { actor: DEFAULT_ACTOR }) {
+    if (!dualWriteEnabled())
+        return;
+    await safeMirror('user.json', async () => {
+        const mappings = [
+            { key: 'railway.token', path: 'railway_token' },
+            { key: 'model.provider', path: 'model_provider' },
+            { key: 'model.id', path: 'model_id' },
+            { key: 'voyage.api_key', path: 'voyage_api_key' },
+            { key: 'r2.access_key_id', path: 'r2.access_key_id' },
+            { key: 'r2.secret_access_key', path: 'r2.secret_access_key' },
+        ];
+        for (const m of mappings) {
+            const def = getKeyDef(m.key);
+            if (!def)
+                continue;
+            const value = readPath(config, m.path);
+            await mirrorOne(def, value, ctx);
+        }
+    });
+}
+/**
+ * Dual-write a connector config. Iterates the connector-secret registry
+ * entries and resolves their paths under the specific connector's config
+ * (e.g., `headers.Authorization` → `connector.<name>.auth`).
+ *
+ * The registry uses pattern names like `connector.<name>.auth`; we expand
+ * to a concrete key per connector at write time. `<name>` is the connector
+ * name verbatim, lowercased for stability — connector names are already
+ * url-safe slugs per `parseConfigBlock`.
+ */
+export async function mirrorConnectorConfig(config, ctx = { actor: DEFAULT_ACTOR }) {
+    if (!dualWriteEnabled())
+        return;
+    if (!config?.name)
+        return;
+    const connector = String(config.name).toLowerCase();
+    await safeMirror(`connector ${connector}`, async () => {
+        const store = getSecretStore();
+        // Authorization header → connector.<name>.auth
+        const auth = config.headers?.['Authorization'] ?? config.headers?.['authorization'];
+        if (isNonEmptyString(auth) && !looksLikeEnvPlaceholder(auth)) {
+            await store.set({
+                key: `connector.${connector}.auth`,
+                value: auth,
+                provider: connector,
+            }, ctx.actor);
+        }
+        // OAuth client secret → connector.<name>.oauth_secret
+        const oauthSecret = config.oauth?.client_secret;
+        if (isNonEmptyString(oauthSecret) && !looksLikeEnvPlaceholder(oauthSecret)) {
+            await store.set({
+                key: `connector.${connector}.oauth_secret`,
+                value: oauthSecret,
+                provider: connector,
+            }, ctx.actor);
+        }
+    });
+}
+/**
+ * Dual-write workspace.json into the store. Covers the R2 credentials
+ * (always-secret), the three R2 structural fields (workspace-setting,
+ * added 2026-05-12 so the Settings UI can fully configure R2), and the
+ * legacy search.* block.
+ *
+ * Why structural fields dual-write too: post-2026-05-12 the store is
+ * the source of truth for R2 structural config, but `studiograph r2
+ * setup` (and any other workspace.writeConfig caller) still writes the
+ * file. Without this mirror, every CLI invocation would silently leave
+ * the store stale. Pair this with the one-shot r2-structural-migration
+ * that covers the first-boot case.
+ */
+export async function mirrorWorkspaceConfig(config, ctx = { actor: DEFAULT_ACTOR }) {
+    if (!dualWriteEnabled())
+        return;
+    await safeMirror('workspace.json', async () => {
+        // workspace.json has its own nesting (`r2_config.access_key_id`) that
+        // doesn't match the registry's flat paths. Translate explicitly.
+        const r2Mappings = [
+            { key: 'r2.access_key_id', path: 'r2_config.access_key_id' },
+            { key: 'r2.secret_access_key', path: 'r2_config.secret_access_key' },
+            { key: 'r2.account_id', path: 'r2_config.account_id' },
+            { key: 'r2.bucket', path: 'r2_config.bucket' },
+            { key: 'r2.public_url', path: 'r2_config.public_url' },
+        ];
+        for (const m of r2Mappings) {
+            const def = getKeyDef(m.key);
+            if (!def)
+                continue;
+            const value = readPath(config, m.path);
+            if (!isNonEmptyString(value))
+                continue;
+            await mirrorOne(def, value, ctx);
+        }
+        // Non-secret search settings live in workspace.json today (provider,
+        // api_key, google_cx). Per plan §3 the search api_key is
+        // secret-class; mirror it when present and non-placeholder.
+        const searchApiKey = readPath(config, 'search.api_key');
+        const searchProvider = readPath(config, 'search.provider');
+        if (isNonEmptyString(searchApiKey) && !looksLikeEnvPlaceholder(searchApiKey)) {
+            const key = searchProviderKey(typeof searchProvider === 'string' ? searchProvider : undefined);
+            if (key) {
+                const def = getKeyDef(key);
+                if (def)
+                    await mirrorOne(def, searchApiKey, ctx);
+            }
+        }
+        const googleCx = readPath(config, 'search.google_cx');
+        if (isNonEmptyString(googleCx)) {
+            const def = getKeyDef('search.google.cx');
+            if (def)
+                await mirrorOne(def, googleCx, ctx);
+        }
+    });
+}
+function searchProviderKey(provider) {
+    switch (provider) {
+        case 'brave': return 'search.brave.api_key';
+        case 'google': return 'search.google.api_key';
+        case 'tavily': return 'search.tavily.api_key';
+        default: return undefined;
+    }
+}
+//# sourceMappingURL=dual-write.js.map

package/dist/core/secrets/dual-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-write.js","sourceRoot":"","sources":["../../../src/core/secrets/dual-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAoC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5D;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,SAAS,uBAAuB,CAAC,CAAU;IACzC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,GAAY,EAAE,IAAY;IAC1C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAQ,GAAG,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7D,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,CAAiB;IACvC,OAAO,CAAC,KAAK,kBAAkB,IAAI,CAAC,KAAK,mBAAmB,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,UAAU,CAAC,KAAa,EAAE,EAA0B;IACjE,IAAI,CAAC;QACH,MAAM,EAAE,EAAE,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,wBAAwB,KAAK,YAAY,GAAG,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAMD,MAAM,aAAa,GAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAE/E;;;;;;GAMG;AACH,KAAK,UAAU,SAAS,CACtB,GAAW,EACX,KAAc,EACd,GAAkB;IAElB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO;IAClE,IAAI,uBAAuB,CAAC,KAAK,CAAC;QAAE,OAAO;IAC3C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC;QAAE,OAAO,CAAC,6CAA6C;IAE9F,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAExD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;YAAE,OAAO;QACrC,MAAM,KAAK,CAAC,GAAG,CACb,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EACxB,GAAG,CAAC,KAAK,CACV,CAAC;QACF,OAAO;IACT,CAAC;IACD,qDAAqD;IACrD,MAAM,KAAK,CAAC,GAAG,CACb,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EACxB,GAAG,CAAC,KAAK,CACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAe,EACf,MAAqB,EAAE,KAAK,EAAE,aAAa,EAAE;IAE7C,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO;IAChC,MAAM,UAAU,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;QACvC,MAAM,QAAQ,GAAyC;YACrD,EAAE,GAAG,EAAE,eAAe,EAAQ,IAAI,EAAE,eAAe,EAAE;YACrD,EAAE,GAAG,EAAE,gBAAgB,EAAO,IAAI,EAAE,gBAAgB,EAAE;YACtD,EAAE,GAAG,EAAE,UAAU,EAAa,IAAI,EAAE,UAAU,EAAE;YAChD,EAAE,GAAG,EAAE,gBAAgB,EAAO,IAAI,EAAE,gBAAgB,EAAE;YACtD,EAAE,GAAG,EAAE,kBAAkB,EAAK,IAAI,EAAE,kBAAkB,EAAE;YACxD,EAAE,GAAG,EAAE,sBAAsB,EAAE,IAAI,EAAE,sBAAsB,EAAE;SAC9D,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAwH,EACxH,MAAqB,EAAE,KAAK,EAAE,aAAa,EAAE;IAE7C,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO;IAChC,IAAI,CAAC,MAAM,EAAE,IAAI;QAAE,OAAO;IAC1B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACpD,MAAM,UAAU,CAAC,aAAa,SAAS,EAAE,EAAE,KAAK,IAAI,EAAE;QACpD,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;QAC/B,+CAA+C;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,eAAe,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC,eAAe,CAAC,CAAC;QACpF,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,KAAK,CAAC,GAAG,CACb;gBACE,GAAG,EAAE,aAAa,SAAS,OAAO;gBAClC,KAAK,EAAE,IAAI;gBACX,QAAQ,EAAE,SAAS;aACpB,EACD,GAAG,CAAC,KAAK,CACV,CAAC;QACJ,CAAC;QACD,sDAAsD;QACtD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC;QAChD,IAAI,gBAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,uBAAuB,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3E,MAAM,KAAK,CAAC,GAAG,CACb;gBACE,GAAG,EAAE,aAAa,SAAS,eAAe;gBAC1C,KAAK,EAAE,WAAW;gBAClB,QAAQ,EAAE,SAAS;aACpB,EACD,GAAG,CAAC,KAAK,CACV,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAe,EACf,MAAqB,EAAE,KAAK,EAAE,aAAa,EAAE;IAE7C,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO;IAChC,MAAM,UAAU,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC5C,sEAAsE;QACtE,iEAAiE;QACjE,MAAM,UAAU,GAAyC;YACvD,EAAE,GAAG,EAAE,kBAAkB,EAAM,IAAI,EAAE,yBAAyB,EAAE;YAChE,EAAE,GAAG,EAAE,sBAAsB,EAAE,IAAI,EAAE,6BAA6B,EAAE;YACpE,EAAE,GAAG,EAAE,eAAe,EAAS,IAAI,EAAE,sBAAsB,EAAE;YAC7D,EAAE,GAAG,EAAE,WAAW,EAAa,IAAI,EAAE,kBAAkB,EAAE;YACzD,EAAE,GAAG,EAAE,eAAe,EAAS,IAAI,EAAE,sBAAsB,EAAE;SAC9D,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;gBAAE,SAAS;YACvC,MAAM,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,qEAAqE;QACrE,yDAAyD;QACzD,4DAA4D;QAC5D,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACxD,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;QAC3D,IAAI,gBAAgB,CAAC,YAAY,CAAC,IAAI,CAAC,uBAAuB,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7E,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC/F,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC3B,IAAI,GAAG;oBAAE,MAAM,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;QACtD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAAC;YAC1C,IAAI,GAAG;gBAAE,MAAM,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,iBAAiB,CAAC,QAA4B;IACrD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO,CAAC,CAAC,OAAO,sBAAsB,CAAC;QAC5C,KAAK,QAAQ,CAAC,CAAC,OAAO,uBAAuB,CAAC;QAC9C,KAAK,QAAQ,CAAC,CAAC,OAAO,uBAAuB,CAAC;QAC9C,OAAO,CAAC,CAAC,OAAO,SAAS,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/core/secrets/encryption.d.ts

@@ -0,0 +1,44 @@
+/**
+ * XChaCha20-Poly1305 AEAD with row-bound AAD.
+ *
+ * Every encrypted row binds (scope, scopeId, key, keyVersion) into the AAD.
+ * Swapping a row from one slot to another (e.g. via `UPDATE secrets SET key=...`)
+ * invalidates the AAD and triggers an AEAD failure on decrypt — making
+ * row-substitution attacks observable.
+ *
+ * Wire format (base64-encoded): `nonce[24] || ciphertext || tag[16]`.
+ * The nonce is randomly generated per encrypt; XChaCha20's 192-bit nonce
+ * makes random selection collision-safe across realistic key lifetimes.
+ */
+export interface AADInput {
+    scope: string;
+    scopeId: string;
+    key: string;
+    keyVersion: string;
+}
+export interface EncryptedRow {
+    ciphertext: string;
+    keyVersion: string;
+}
+/**
+ * Encrypt `plaintext` under `masterKey` with AAD bound to `ctx`.
+ * Returns base64(nonce || ciphertext || tag) and the keyVersion that was
+ * baked into the AAD. Caller is responsible for storing both.
+ */
+export declare function encrypt(masterKey: Uint8Array, plaintext: string, ctx: AADInput): EncryptedRow;
+/**
+ * Decrypt a row. Throws on:
+ *   - AAD mismatch (row moved between slots; key/scope/version doesn't match)
+ *   - tag failure (ciphertext or nonce tampered)
+ *   - wrong master key
+ *   - malformed wire format (truncated, bad base64)
+ *
+ * The thrown error MUST NOT carry the ciphertext or any partial plaintext.
+ */
+export declare function decrypt(masterKey: Uint8Array, row: EncryptedRow, ctx: AADInput): string;
+/**
+ * Generate a fresh master key suitable for `encrypt()`. 32 random bytes.
+ * Caller is responsible for base64-encoding for env-var transport and
+ * persistence (see master-key.ts).
+ */
+export declare function generateMasterKey(): Uint8Array;

package/dist/core/secrets/encryption.js

@@ -0,0 +1,97 @@
+/**
+ * XChaCha20-Poly1305 AEAD with row-bound AAD.
+ *
+ * Every encrypted row binds (scope, scopeId, key, keyVersion) into the AAD.
+ * Swapping a row from one slot to another (e.g. via `UPDATE secrets SET key=...`)
+ * invalidates the AAD and triggers an AEAD failure on decrypt — making
+ * row-substitution attacks observable.
+ *
+ * Wire format (base64-encoded): `nonce[24] || ciphertext || tag[16]`.
+ * The nonce is randomly generated per encrypt; XChaCha20's 192-bit nonce
+ * makes random selection collision-safe across realistic key lifetimes.
+ */
+import { xchacha20poly1305 } from '@noble/ciphers/chacha';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+const NONCE_LEN = 24;
+const utf8 = new TextEncoder();
+const utf8d = new TextDecoder();
+/**
+ * Canonical AAD encoding. We bind the four-tuple via JSON-array encoding
+ * so the result is unambiguous regardless of what characters the
+ * components carry. Earlier versions used a `|` join, which collided
+ * silently if any component happened to contain the pipe character —
+ * `(scope=instance, key='a|b', scopeId='c', mk_v1)` produced the same
+ * AAD bytes as `(scope=instance, key='a', scopeId='b|c', mk_v1)`,
+ * opening a row-swap window. JSON.stringify on a fixed-shape array is
+ * trivially auditable and robust to any future key/scopeId additions
+ * (e.g., connector keys with `|` or quoted scopeIds).
+ *
+ * Encoding choice is part of the wire format — changing it invalidates
+ * every existing ciphertext. The branch this lands in has not yet
+ * shipped Phase 5/6, so no rotation runbook is needed.
+ */
+function aad(input) {
+    return utf8.encode(JSON.stringify([input.scope, input.scopeId, input.key, input.keyVersion]));
+}
+function toBase64(bytes) {
+    // Buffer is the fastest path on Node and is already a transitive dep.
+    return Buffer.from(bytes).toString('base64');
+}
+function fromBase64(b64) {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+/**
+ * Encrypt `plaintext` under `masterKey` with AAD bound to `ctx`.
+ * Returns base64(nonce || ciphertext || tag) and the keyVersion that was
+ * baked into the AAD. Caller is responsible for storing both.
+ */
+export function encrypt(masterKey, plaintext, ctx) {
+    if (masterKey.length !== 32) {
+        throw new Error(`encryption: master key must be 32 bytes (got ${masterKey.length})`);
+    }
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = xchacha20poly1305(masterKey, nonce, aad(ctx));
+    const ct = cipher.encrypt(utf8.encode(plaintext));
+    return { ciphertext: toBase64(concat(nonce, ct)), keyVersion: ctx.keyVersion };
+}
+/**
+ * Decrypt a row. Throws on:
+ *   - AAD mismatch (row moved between slots; key/scope/version doesn't match)
+ *   - tag failure (ciphertext or nonce tampered)
+ *   - wrong master key
+ *   - malformed wire format (truncated, bad base64)
+ *
+ * The thrown error MUST NOT carry the ciphertext or any partial plaintext.
+ */
+export function decrypt(masterKey, row, ctx) {
+    if (masterKey.length !== 32) {
+        throw new Error(`encryption: master key must be 32 bytes (got ${masterKey.length})`);
+    }
+    const buf = fromBase64(row.ciphertext);
+    if (buf.length < NONCE_LEN + 16) {
+        throw new Error('encryption: ciphertext too short');
+    }
+    const nonce = buf.slice(0, NONCE_LEN);
+    const ct = buf.slice(NONCE_LEN);
+    // The keyVersion in the AAD comes from `ctx`, not `row` — caller decides
+    // which version to attempt. (rotate_master flips ctx.keyVersion to mk_v(N+1)
+    // and, on failure, retries with mk_v(N) using the previous master key.)
+    const cipher = xchacha20poly1305(masterKey, nonce, aad(ctx));
+    const pt = cipher.decrypt(ct);
+    return utf8d.decode(pt);
+}
+/**
+ * Generate a fresh master key suitable for `encrypt()`. 32 random bytes.
+ * Caller is responsible for base64-encoding for env-var transport and
+ * persistence (see master-key.ts).
+ */
+export function generateMasterKey() {
+    return randomBytes(32);
+}
+//# sourceMappingURL=encryption.js.map

package/dist/core/secrets/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../../src/core/secrets/encryption.ts"],"names":[],"mappings":"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"}

package/dist/core/secrets/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Secrets / settings store — barrel export. Phase 1 surface.
+ */
+export { REGISTRY, RECOMMENDED_MODELS, PROVIDER_MODELS, utilityModelFor, SYSTEM_ALLOWLIST, OPERATIONAL_ALLOWLIST, getKeyDef, getKeyDefByEnvAlias, getKeyConstraint, listWorkspaceSettingsSchema, getAllConsoleUrls, allRegisteredEnvAliases, } from './registry.js';
+export type { Classification, RedactionMode, KeyDef, KeyConstraint, SettingSchemaEntry, SettingRecommendations, RecommendedModelOption, ProviderModelEntry, } from './registry.js';
+export { encrypt, decrypt, generateMasterKey } from './encryption.js';
+export type { AADInput, EncryptedRow } from './encryption.js';
+export { loadMasterKey, loadPreviousMasterKey } from './master-key.js';
+export type { LoadedMasterKey } from './master-key.js';
+export { SqliteEncryptedStore } from './SqliteEncryptedStore.js';
+export type { SqliteEncryptedStoreOptions } from './SqliteEncryptedStore.js';
+export { AuditLogger } from './audit.js';
+export type { AuditAction, AuditEvent } from './audit.js';
+export { SettingsResolver } from './SettingsResolver.js';
+export type { ResolutionSource, ResolvedValue, ResolverContext, ResolverDeps, } from './SettingsResolver.js';
+export { tryResolve, tryResolveWithSource } from './read-flip.js';
+export type { ActorContext, SecretMetadata, SecretStore, SetSecretInput, } from './SecretStore.js';
+export type { SettingMetadata, SettingsStore, SetSettingInput, } from './SettingsStore.js';
+import type { SqliteEncryptedStore as SqliteEncryptedStoreType } from './SqliteEncryptedStore.js';
+export declare function setSecretStore(store: SqliteEncryptedStoreType | undefined): void;
+/**
+ * Module-level accessor. Throws when the boot path didn't initialize the
+ * store (test harness, early-init code paths). Hard error rather than
+ * silent undefined to surface mis-wired callsites quickly.
+ */
+export declare function getSecretStore(): SqliteEncryptedStoreType;
+export declare function hasSecretStore(): boolean;
+import { SettingsResolver } from './SettingsResolver.js';
+/**
+ * Mutation notification — fires after any successful set/delete on the
+ * store. Consumers subscribe here so they can react to store changes
+ * without polling. Primary use case: the agent pool cache eviction
+ * when a model.* key changes (otherwise running agents keep using the
+ * apiKey they captured at construction time).
+ *
+ * Listener errors are swallowed — never let a stray listener take down
+ * a write path. Listeners must not be slow (we run them synchronously
+ * on the write request's hot path).
+ */
+type SecretMutationListener = (key: string) => void;
+export declare function onSecretMutation(fn: SecretMutationListener): () => void;
+export declare function notifySecretMutation(key: string): void;
+export declare function getSettingsResolver(): SettingsResolver | undefined;
+/**
+ * Reset the cached resolver. Tests call this after swapping the store
+ * out — without it the cached resolver retains the prior `_store`
+ * reference and reads against a closed handle.
+ */
+export declare function _resetCachedResolver(): void;

package/dist/core/secrets/index.js

@@ -0,0 +1,74 @@
+/**
+ * Secrets / settings store — barrel export. Phase 1 surface.
+ */
+export { REGISTRY, RECOMMENDED_MODELS, PROVIDER_MODELS, utilityModelFor, SYSTEM_ALLOWLIST, OPERATIONAL_ALLOWLIST, getKeyDef, getKeyDefByEnvAlias, getKeyConstraint, listWorkspaceSettingsSchema, getAllConsoleUrls, allRegisteredEnvAliases, } from './registry.js';
+export { encrypt, decrypt, generateMasterKey } from './encryption.js';
+export { loadMasterKey, loadPreviousMasterKey } from './master-key.js';
+export { SqliteEncryptedStore } from './SqliteEncryptedStore.js';
+export { AuditLogger } from './audit.js';
+export { SettingsResolver } from './SettingsResolver.js';
+export { tryResolve, tryResolveWithSource } from './read-flip.js';
+let _store;
+export function setSecretStore(store) {
+    _store = store;
+    // Drop the cached resolver so a freshly-installed store isn't shadowed.
+    _resolver = undefined;
+}
+/**
+ * Module-level accessor. Throws when the boot path didn't initialize the
+ * store (test harness, early-init code paths). Hard error rather than
+ * silent undefined to surface mis-wired callsites quickly.
+ */
+export function getSecretStore() {
+    if (!_store) {
+        throw new Error('Secrets store not initialized. The serve.ts bootstrap should have set this up — call site is running too early or in a test without store wiring.');
+    }
+    return _store;
+}
+export function hasSecretStore() {
+    return _store !== undefined;
+}
+import { SettingsResolver } from './SettingsResolver.js';
+const _mutationListeners = new Set();
+export function onSecretMutation(fn) {
+    _mutationListeners.add(fn);
+    return () => { _mutationListeners.delete(fn); };
+}
+export function notifySecretMutation(key) {
+    for (const fn of _mutationListeners) {
+        try {
+            fn(key);
+        }
+        catch {
+            // Listener bugs must not break the caller's write.
+        }
+    }
+}
+/**
+ * Lazily-instantiated process-wide SettingsResolver. Reads the same
+ * singleton SqliteEncryptedStore that `setSecretStore()` registered. The
+ * resolver is cheap (just a wrapper) — we cache it so callers don't
+ * have to plumb a `SettingsResolver` instance through their call graph.
+ *
+ * Returns undefined when the new-store flag is off / boot didn't
+ * initialize the store — call sites in Phase 6 use
+ * `tryResolveFromStore()` which guards on this.
+ */
+let _resolver;
+export function getSettingsResolver() {
+    if (!_store)
+        return undefined;
+    if (!_resolver) {
+        _resolver = new SettingsResolver({ secrets: _store, settings: _store });
+    }
+    return _resolver;
+}
+/**
+ * Reset the cached resolver. Tests call this after swapping the store
+ * out — without it the cached resolver retains the prior `_store`
+ * reference and reads against a closed handle.
+ */
+export function _resetCachedResolver() {
+    _resolver = undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/secrets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/secrets/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,QAAQ,EACR,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EAChB,2BAA2B,EAC3B,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAYvB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGjE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAQzD,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAkBlE,IAAI,MAA4C,CAAC;AAEjD,MAAM,UAAU,cAAc,CAAC,KAA2C;IACxE,MAAM,GAAG,KAAK,CAAC;IACf,wEAAwE;IACxE,SAAS,GAAG,SAAS,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mJAAmJ,CACpJ,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,MAAM,KAAK,SAAS,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAczD,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA0B,CAAC;AAE7D,MAAM,UAAU,gBAAgB,CAAC,EAA0B;IACzD,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3B,OAAO,GAAG,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,KAAK,MAAM,EAAE,IAAI,kBAAkB,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,EAAE,CAAC,GAAG,CAAC,CAAC;QACV,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,IAAI,SAAuC,CAAC;AAC5C,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,SAAS,GAAG,SAAS,CAAC;AACxB,CAAC"}

package/dist/core/secrets/master-key.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Master-key bootstrap.
+ *
+ * Resolution order:
+ *   1. STUDIOGRAPH_MASTER_KEY env var (base64-encoded 32 bytes).
+ *      Always wins. In production this is the only acceptable source.
+ *   2. ~/.studiograph/master-key file (mode 0600). Local-dev only.
+ *      If absent, a fresh 32-byte key is generated, written, and a one-time
+ *      warning printed to stderr with backup instructions.
+ *
+ * Production gate: when RAILWAY_ENVIRONMENT is set and the env-var is
+ * unset, throw. We do NOT silently generate a key in production — that
+ * would be ephemeral, would invalidate every encrypted row on the next
+ * restart, and would mask a misconfigured deploy.
+ */
+export interface LoadedMasterKey {
+    key: Uint8Array;
+    /** Where it came from; useful for boot logging without leaking the value. */
+    source: 'env' | 'file' | 'generated';
+    /** Path to the on-disk file (only set when source !== 'env'). */
+    filePath?: string;
+}
+/**
+ * Load the master key. Idempotent — safe to call multiple times.
+ *
+ * In a long-running process you should call once at boot and cache the
+ * result. The local-dev side-effect (file generate + warn) only fires if
+ * the file does not exist.
+ */
+export declare function loadMasterKey(opts?: {
+    filePath?: string;
+}): LoadedMasterKey;
+/**
+ * Optional companion: load a previous master key for rotation transitions.
+ * Returns undefined when STUDIOGRAPH_MASTER_KEY_PREVIOUS is unset — that's
+ * the steady state. Caller must tolerate undefined.
+ */
+export declare function loadPreviousMasterKey(): Uint8Array | undefined;