studiograph 1.3.46 → 1.3.48-beta.0

package/dist/core/schemas/workspace.js

@@ -0,0 +1,211 @@
+/**
+ * Phase 9a — workspace.json schema (WARN-MODE).
+ *
+ * Registry-driven validator that flags secret-shaped material anywhere in a
+ * workspace.json blob. In 9a the validator runs but only *logs* violations;
+ * the write proceeds. Phase 9b will route writers through the validator, and
+ * 9c will flip rejections on.
+ *
+ * The detector reuses `findSecretLeaks()` from `bundle.ts` — the goal is
+ * that import-time, export-time, and save-time agree on what "looks like a
+ * secret" so leaks can't slip through one path while another rejects them.
+ *
+ * Output format is the structured single-line shape from the plan §5:
+ *   [schema-warn] workspace_config: field '<path>' has secret-shaped value
+ *     (registry: <key.name>, classification: <classification>)
+ *
+ * One line per violation. No multi-line stack traces. Cheap to grep, cheap
+ * for downstream log routing to redact further once Phase 11's sanitize()
+ * is wired.
+ */
+import { z } from 'zod';
+import { findSecretLeaks } from '../secrets/bundle.js';
+import { getKeyDef } from '../secrets/registry.js';
+/**
+ * Phase 9c — strict-mode error.
+ *
+ * Thrown when `STUDIOGRAPH_SCHEMA_STRICT` is on (default) and the
+ * workspace or connector validator finds at least one violation.
+ *
+ * **The error message MUST NOT contain the offending value.** Only the
+ * field path, registry classification, and a remediation hint are
+ * exposed — exactly what a route handler can log and surface to the
+ * user without re-leaking the secret.
+ *
+ * Routes that catch this translate it to:
+ *   - HTTP 400 with error code `schema_violation` (config-api, etc.)
+ *   - CLI exit 1 with a red message (sync, clone, join, ...)
+ *
+ * Callers can read `violations` and `scope` to build their own message.
+ */
+export class SchemaViolationError extends Error {
+    static code = 'schema_violation';
+    code = SchemaViolationError.code;
+    scope;
+    violations;
+    constructor(scope, violations) {
+        super(formatSchemaViolationMessage(scope, violations));
+        this.name = 'SchemaViolationError';
+        this.scope = scope;
+        this.violations = violations;
+    }
+}
+function formatSchemaViolationMessage(scope, violations) {
+    const lines = violations.map((v) => {
+        const meta = [];
+        if (v.registryKey)
+            meta.push(`registry: ${v.registryKey}`);
+        if (v.classification)
+            meta.push(`classification: ${v.classification}`);
+        if (!meta.length)
+            meta.push(`reason: ${v.reason}`);
+        return `  - ${v.path} (${meta.join(', ')})`;
+    });
+    const remediation = scope === 'workspace_config'
+        ? 'Move secret values to environment variables or the encrypted store. ' +
+            'workspace.json is committed to the config repo and must not carry literals.'
+        : 'Use $ENV_VAR placeholders for secret-named fields (Authorization, ' +
+            'oauth.client_secret, token). Literal values belong in ~/.studiograph/connectors/ ' +
+            '(homedir layer), not the workspace-layer file.';
+    return [
+        `${scope} schema violation — secret-shaped content detected:`,
+        ...lines,
+        remediation,
+        'Set STUDIOGRAPH_SCHEMA_STRICT=0 to fall back to warn-mode while fixing.',
+    ].join('\n');
+}
+/**
+ * Phase 9c — runtime check for strict mode.
+ *
+ * Read at validation time (not cached at boot) so operators can flip the
+ * env in a hotfix without restarting the process. Default behaviour
+ * (env unset) is strict — `'0'` and `'false'` are the only opt-outs.
+ */
+export function isSchemaStrict() {
+    const raw = process.env.STUDIOGRAPH_SCHEMA_STRICT;
+    if (raw === undefined || raw === '')
+        return true;
+    const v = raw.toLowerCase();
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
+}
+/**
+ * Top-level shape. Loose by design in 9a — we keep unknown fields so
+ * upstream callers (workspace.ts writeConfig, dual-write mirrors) don't
+ * regress on perfectly valid existing data. Phase 9b/c can tighten this to
+ * `.strict()` once the warn-mode telemetry shows what real data looks like.
+ */
+export const WorkspaceConfigSchema = z
+    .object({
+    version: z.string().optional(),
+    team_name: z.string().optional(),
+    name: z.string().optional(),
+    slug: z.string().optional(),
+    created_at: z.string().optional(),
+    repos: z.array(z.unknown()).optional(),
+})
+    .passthrough();
+/**
+ * Run the secret-leak walker over a workspace.json blob and return a list of
+ * structured violations. The walker uses `findSecretLeaks()` from bundle.ts,
+ * which understands:
+ *   - registry-named paths (`r2_config.secret_access_key` → bootstrap)
+ *   - bootstrap field names (`jwtSecret`, `apiKey`)
+ *   - value-shape patterns (`sk-*`, `Bearer *`, `https://user:pass@…`, etc.)
+ *
+ * The validator does NOT mutate, throw, or reject — it just produces the
+ * violation list. Callers that want strict behaviour wrap it in their own
+ * `if (violations.length) throw` check (Phase 9c).
+ */
+export function validateWorkspaceConfig(input) {
+    const violations = [];
+    if (!input || typeof input !== 'object')
+        return violations;
+    for (const leak of findSecretLeaks('', input)) {
+        const def = lookupKey(leak.path);
+        violations.push({
+            path: leak.path,
+            registryKey: def?.name,
+            classification: def?.classification,
+            reason: leak.reason,
+        });
+    }
+    return violations;
+}
+/**
+ * Format a single violation as the warn-mode log line. Stable, greppable,
+ * one line per violation. Phase 11's `sanitize()` is responsible for any
+ * further redaction once the centralized logger lands.
+ */
+export function formatViolation(scope, v) {
+    const parts = [];
+    parts.push(`[schema-warn] ${scope}: field '${v.path}' has secret-shaped value`);
+    if (v.registryKey || v.classification) {
+        const meta = [];
+        if (v.registryKey)
+            meta.push(`registry: ${v.registryKey}`);
+        if (v.classification)
+            meta.push(`classification: ${v.classification}`);
+        parts.push(`(${meta.join(', ')})`);
+    }
+    else {
+        parts.push('(registry: <unmapped>, reason: value-shape)');
+    }
+    return parts.join(' ');
+}
+/**
+ * Warn-mode entry point: validate + log each violation via `console.warn`.
+ * Returns the violation list so callers (tests, telemetry) can also
+ * inspect what was found.
+ *
+ * The logger seam is `console.warn` for 9a; Phase 11 will swap this for the
+ * centralized `log.warn` once that lands. Using `console.warn` here keeps
+ * the import graph small and avoids a Phase-11 dependency.
+ */
+export function warnOnWorkspaceConfigViolations(input) {
+    const violations = validateWorkspaceConfig(input);
+    for (const v of violations) {
+        // eslint-disable-next-line no-console
+        console.warn(formatViolation('workspace_config', v));
+    }
+    return violations;
+}
+/**
+ * Phase 9c — strict-or-warn entry point used by save sites.
+ *
+ * When `STUDIOGRAPH_SCHEMA_STRICT` is on (default), throws
+ * `SchemaViolationError` on the first non-empty violation list. Otherwise
+ * delegates to `warnOnWorkspaceConfigViolations` for log-only behaviour.
+ *
+ * This is the canonical helper that `Workspace.writeConfig` should call.
+ * Tests can flip the env to exercise both modes.
+ */
+export function enforceWorkspaceConfig(input) {
+    if (!isSchemaStrict()) {
+        return warnOnWorkspaceConfigViolations(input);
+    }
+    const violations = validateWorkspaceConfig(input);
+    if (violations.length > 0) {
+        throw new SchemaViolationError('workspace_config', violations);
+    }
+    return violations;
+}
+/**
+ * Resolve a leak path to a registry entry. Tries direct match, the
+ * `workspace.`/`instance.` prefixes, and tail-walks suffixes — mirrors
+ * bundle.ts's lookup logic so the two stay in sync.
+ */
+function lookupKey(path) {
+    const direct = getKeyDef(path) ?? getKeyDef(`workspace.${path}`) ?? getKeyDef(`instance.${path}`);
+    if (direct)
+        return direct;
+    // Try the suffix walk: a.b.c → b.c, then c.
+    const parts = path.split('.');
+    for (let i = 1; i < parts.length; i++) {
+        const tail = parts.slice(i).join('.');
+        const m = getKeyDef(tail) ?? getKeyDef(`workspace.${tail}`) ?? getKeyDef(`instance.${tail}`);
+        if (m)
+            return m;
+    }
+    return undefined;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/schemas/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/core/schemas/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,MAAM,CAAU,IAAI,GAAG,kBAA2B,CAAC;IAE1C,IAAI,GAAG,oBAAoB,CAAC,IAAI,CAAC;IACjC,KAAK,CAA0C;IAC/C,UAAU,CAAiC;IAEpD,YAAY,KAA8C,EAAE,UAA6B;QACvF,KAAK,CAAC,4BAA4B,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;;AAGH,SAAS,4BAA4B,CACnC,KAA8C,EAC9C,UAA6B;IAE7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACjC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,CAAC,CAAC,WAAW;YAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,CAAC,cAAc;YAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,MAAM,WAAW,GACf,KAAK,KAAK,kBAAkB;QAC1B,CAAC,CAAC,sEAAsE;YACtE,6EAA6E;QAC/E,CAAC,CAAC,oEAAoE;YACpE,mFAAmF;YACnF,gDAAgD,CAAC;IACvD,OAAO;QACL,GAAG,KAAK,qDAAqD;QAC7D,GAAG,KAAK;QACR,WAAW;QACX,yEAAyE;KAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAClD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAC5B,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;AACpE,CAAC;AAkBD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC;KACD,WAAW,EAAE,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,MAAM,UAAU,GAAsB,EAAE,CAAC;IACzC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IAE3D,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,GAAG,EAAE,IAAI;YACtB,cAAc,EAAE,GAAG,EAAE,cAAc;YACnC,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAA8C,EAAE,CAAkB;IAChG,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,YAAY,CAAC,CAAC,IAAI,2BAA2B,CAAC,CAAC;IAChF,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;QACtC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,CAAC,CAAC,WAAW;YAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,CAAC,cAAc;YAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAAC,KAAc;IAC5D,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QACtB,OAAO,+BAA+B,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,oBAAoB,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,aAAa,IAAI,EAAE,CAAC,IAAI,SAAS,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IAClG,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,aAAa,IAAI,EAAE,CAAC,IAAI,SAAS,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;QAC7F,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,77 @@
+/**
+ * SecretStore — write-only-from-the-outside contract for secret-classified
+ * keys. The value never round-trips out via `describe()`; only metadata is
+ * exposed to the UI/API. Internal callers (resolver, encryption migration)
+ * read raw values via `unsafeGetForResolver()`.
+ *
+ * After the scope-collapse refactor, the store is single-tier: Studiograph
+ * is single-workspace-per-process, so secrets.db has no `scope` / `scope_id`
+ * dimension. The `Classification` registry tag (workspace-secret /
+ * workspace-setting) is the only categorization that matters.
+ */
+import type { Classification } from './registry.js';
+export interface ActorContext {
+    type: 'user' | 'system';
+    /** Set when type === 'user'. */
+    userId?: string;
+    /** Set when type === 'system'. e.g. 'importer', 'boot-migration', 'cli-rotate-master'. */
+    systemId?: string;
+    /** Optional, for HTTP-originated calls. */
+    ip?: string;
+    userAgent?: string;
+}
+export interface SecretMetadata {
+    key: string;
+    classification: Classification;
+    /** Human label set when written, e.g. "Production Anthropic". */
+    label?: string;
+    /** Provider hint for UI presentation. */
+    provider?: string;
+    /** Last successful test_connection timestamp (ms epoch). */
+    lastTestedAt?: number;
+    /** 'ok' | 'fail' | undefined when never tested. */
+    lastTestResult?: 'ok' | 'fail';
+    updatedAt: number;
+    updatedBy: string;
+    /** Master-key version used to encrypt the row. */
+    keyVersion: string;
+}
+export interface SetSecretInput {
+    key: string;
+    value: string;
+    label?: string;
+    provider?: string;
+}
+export interface SecretStore {
+    /**
+     * Write or overwrite a secret. Audit-logged. Validates that `key` is in
+     * the registry with a *-secret classification (workspace-secret) —
+     * bootstrap and user-secret keys reject.
+     */
+    set(input: SetSecretInput, actor: ActorContext): Promise<SecretMetadata>;
+    /**
+     * Return metadata for a given key. The actual ciphertext
+     * is NEVER returned through this method. Use `unsafeGetForResolver()` for
+     * resolver / migration paths.
+     */
+    describe(key: string): SecretMetadata | undefined;
+    /**
+     * Enumerate secret metadata. Audit-logged when actor is provided
+     * (UI/API metadata reads). Named `listSecrets` to avoid ambiguity with
+     * `SettingsStore.list()` when one class implements both interfaces.
+     */
+    listSecrets(actor?: ActorContext): SecretMetadata[];
+    /**
+     * Delete a secret. Audit-logged.
+     */
+    delete(key: string, actor: ActorContext): Promise<boolean>;
+    /**
+     * Resolver-only path: return the decrypted plaintext or undefined. NOT
+     * audit-logged (hot path). Throws on AEAD failure (caller should audit
+     * the failure as `decrypt_fail`).
+     *
+     * Named `unsafe*` because every UI/API caller MUST go through `describe()`
+     * instead — the value should not leave the resolver.
+     */
+    unsafeGetForResolver(key: string): string | undefined;
+}

package/dist/core/secrets/SecretStore.js

@@ -0,0 +1,13 @@
+/**
+ * SecretStore — write-only-from-the-outside contract for secret-classified
+ * keys. The value never round-trips out via `describe()`; only metadata is
+ * exposed to the UI/API. Internal callers (resolver, encryption migration)
+ * read raw values via `unsafeGetForResolver()`.
+ *
+ * After the scope-collapse refactor, the store is single-tier: Studiograph
+ * is single-workspace-per-process, so secrets.db has no `scope` / `scope_id`
+ * dimension. The `Classification` registry tag (workspace-secret /
+ * workspace-setting) is the only categorization that matters.
+ */
+export {};
+//# sourceMappingURL=SecretStore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SecretStore.js","sourceRoot":"","sources":["../../../src/core/secrets/SecretStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

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

@@ -0,0 +1,54 @@
+/**
+ * SettingsResolver — single read-side entry point. Implements the
+ * precedence chain:
+ *
+ *   bootstrap     → env > default        (env-only; no store layer)
+ *   workspace-*   → store > default      (env is NOT consulted at resolve time)
+ *   user-*        → handled by auth.db readers (not this module)
+ *
+ * Env values for workspace-* keys are read ONCE by the first-run importer
+ * and mirrored into the store on cold boot; after that, the store is
+ * canonical. This avoids the "env shadows store" confusion that the UI
+ * banner used to apologise for — if a user updates ANTHROPIC_API_KEY in
+ * Railway after the importer has run, the change is silently ignored
+ * until they update via the UI or CLI.
+ *
+ * Studiograph is single-workspace-per-process: the deployment IS the
+ * workspace, so there is no separate "instance" tier and no scope
+ * cascade. The old `'store-workspace'` and `'store-instance'` source
+ * values collapse to a single `'store'`.
+ */
+import type { SecretStore } from './SecretStore.js';
+import type { SettingsStore } from './SettingsStore.js';
+export type ResolutionSource = 'env' | 'store' | 'default' | 'unset';
+export interface ResolvedValue<T = unknown> {
+    value: T | undefined;
+    source: ResolutionSource;
+    /** Set when source === 'env' — which alias actually matched. */
+    envAlias?: string;
+}
+/**
+ * Reserved for forward compatibility. There is no scope cascade in v1 —
+ * the process IS the workspace — but the type stays around to keep call
+ * sites diff-free in case a future feature introduces sub-tenant scoping
+ * inside a single workspace.
+ */
+export interface ResolverContext {
+}
+export interface ResolverDeps {
+    secrets: SecretStore;
+    settings: SettingsStore;
+}
+export declare class SettingsResolver {
+    private readonly deps;
+    constructor(deps: ResolverDeps);
+    /**
+     * Resolve a key by canonical name. Returns the parsed value plus the
+     * source that won. Caller is responsible for handling `undefined` —
+     * the resolver does not throw on missing values.
+     */
+    resolveWithSource<T = unknown>(name: string, ctx?: ResolverContext): ResolvedValue<T>;
+    resolve<T = unknown>(name: string, ctx?: ResolverContext): T | undefined;
+    private resolveDef;
+    private readFromStore;
+}

package/dist/core/secrets/SettingsResolver.js

@@ -0,0 +1,80 @@
+/**
+ * SettingsResolver — single read-side entry point. Implements the
+ * precedence chain:
+ *
+ *   bootstrap     → env > default        (env-only; no store layer)
+ *   workspace-*   → store > default      (env is NOT consulted at resolve time)
+ *   user-*        → handled by auth.db readers (not this module)
+ *
+ * Env values for workspace-* keys are read ONCE by the first-run importer
+ * and mirrored into the store on cold boot; after that, the store is
+ * canonical. This avoids the "env shadows store" confusion that the UI
+ * banner used to apologise for — if a user updates ANTHROPIC_API_KEY in
+ * Railway after the importer has run, the change is silently ignored
+ * until they update via the UI or CLI.
+ *
+ * Studiograph is single-workspace-per-process: the deployment IS the
+ * workspace, so there is no separate "instance" tier and no scope
+ * cascade. The old `'store-workspace'` and `'store-instance'` source
+ * values collapse to a single `'store'`.
+ */
+import { getKeyDef } from './registry.js';
+export class SettingsResolver {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Resolve a key by canonical name. Returns the parsed value plus the
+     * source that won. Caller is responsible for handling `undefined` —
+     * the resolver does not throw on missing values.
+     */
+    resolveWithSource(name, ctx = {}) {
+        const def = getKeyDef(name);
+        if (!def) {
+            throw new Error(`SettingsResolver: unknown key "${name}". Add it to the registry.`);
+        }
+        return this.resolveDef(def, ctx);
+    }
+    resolve(name, ctx = {}) {
+        return this.resolveWithSource(name, ctx).value;
+    }
+    resolveDef(def, ctx) {
+        // Bootstrap: env-only. These keys (master.key, jwt.secret, the CLI
+        // credentials, railway.token) load before the encrypted store exists,
+        // so they have no store layer to read from. Env wins; fall through to
+        // default.
+        if (def.classification === 'bootstrap') {
+            for (const alias of def.envAliases) {
+                const raw = process.env[alias];
+                if (raw === undefined || raw === '')
+                    continue;
+                return { value: raw, source: 'env', envAlias: alias };
+            }
+            return { value: def.default, source: def.default !== undefined ? 'default' : 'unset' };
+        }
+        // Workspace-* keys: store > default. Env is NOT consulted at resolve
+        // time — the first-run importer mirrors env into the store on cold
+        // boot, then env stops being read. Operators who update env after
+        // the importer has run must update via UI or CLI for the change to
+        // take effect.
+        if (def.classification === 'workspace-secret' ||
+            def.classification === 'workspace-setting') {
+            const fromStore = this.readFromStore(def);
+            if (fromStore !== undefined)
+                return { value: fromStore, source: 'store' };
+        }
+        if (def.default !== undefined) {
+            return { value: def.default, source: 'default' };
+        }
+        return { value: undefined, source: 'unset' };
+    }
+    readFromStore(def) {
+        if (def.classification.endsWith('-secret')) {
+            const v = this.deps.secrets.unsafeGetForResolver(def.name);
+            return v;
+        }
+        return this.deps.settings.get(def.name);
+    }
+}
+//# sourceMappingURL=SettingsResolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsResolver.js","sourceRoot":"","sources":["../../../src/core/secrets/SettingsResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAgC1C,MAAM,OAAO,gBAAgB;IACE;IAA7B,YAA6B,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAEnD;;;;OAIG;IACH,iBAAiB,CAAc,IAAY,EAAE,MAAuB,EAAE;QACpE,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,4BAA4B,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAI,GAAG,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,CAAc,IAAY,EAAE,MAAuB,EAAE;QAC1D,OAAO,IAAI,CAAC,iBAAiB,CAAI,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC;IACpD,CAAC;IAEO,UAAU,CAAI,GAAW,EAAE,GAAoB;QACrD,mEAAmE;QACnE,sEAAsE;QACtE,sEAAsE;QACtE,WAAW;QACX,IAAI,GAAG,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;YACvC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;gBACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC/B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;oBAAE,SAAS;gBAC9C,OAAO,EAAE,KAAK,EAAE,GAAmB,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACxE,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,OAAwB,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1G,CAAC;QAED,qEAAqE;QACrE,mEAAmE;QACnE,kEAAkE;QAClE,mEAAmE;QACnE,eAAe;QACf,IACE,GAAG,CAAC,cAAc,KAAK,kBAAkB;YACzC,GAAG,CAAC,cAAc,KAAK,mBAAmB,EAC1C,CAAC;YACD,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAI,GAAG,CAAC,CAAC;YAC7C,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC5E,CAAC;QAED,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,OAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACxD,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;IAEO,aAAa,CAAI,GAAW;QAClC,IAAI,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3D,OAAO,CAA6B,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF"}

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

@@ -0,0 +1,30 @@
+/**
+ * SettingsStore — non-secret workspace key/value pairs.
+ * Plaintext on disk; UI can read and write.
+ *
+ * After the scope-collapse refactor, settings are single-tier: Studiograph
+ * is single-workspace-per-process, so secrets.db has no scope dimension.
+ */
+import type { ActorContext } from './SecretStore.js';
+export interface SettingMetadata {
+    key: string;
+    /** JSON-serialized value. Use `getValue<T>()` for typed access. */
+    valueJson: string;
+    updatedAt: number;
+    updatedBy: string;
+}
+export interface SetSettingInput {
+    key: string;
+    /** Any JSON-serializable value. */
+    value: unknown;
+}
+export interface SettingsStore {
+    set(input: SetSettingInput, actor: ActorContext): Promise<SettingMetadata>;
+    /**
+     * Return the parsed value, or undefined when unset. Synchronous —
+     * settings are read on the hot path.
+     */
+    get<T = unknown>(key: string): T | undefined;
+    list(): SettingMetadata[];
+    delete(key: string, actor: ActorContext): Promise<boolean>;
+}

package/dist/core/secrets/SettingsStore.js

@@ -0,0 +1,9 @@
+/**
+ * SettingsStore — non-secret workspace key/value pairs.
+ * Plaintext on disk; UI can read and write.
+ *
+ * After the scope-collapse refactor, settings are single-tier: Studiograph
+ * is single-workspace-per-process, so secrets.db has no scope dimension.
+ */
+export {};
+//# sourceMappingURL=SettingsStore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsStore.js","sourceRoot":"","sources":["../../../src/core/secrets/SettingsStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,90 @@
+/**
+ * SqliteEncryptedStore — concrete SecretStore + SettingsStore on
+ * better-sqlite3.
+ *
+ * Lives at /workspace/secrets.db on Railway, ~/.studiograph/secrets.db
+ * locally. File mode 0600 enforced after open. The audit table lives in
+ * the same DB so cross-table operations stay atomic.
+ *
+ * After the scope-collapse refactor, the schema has no `scope` /
+ * `scope_id` columns — Studiograph is single-workspace-per-process, so
+ * each key has at most one row. Existing populated databases (with the
+ * old `(scope, scope_id, key)` shape) are migrated transparently on
+ * first construction via `migrateScopeCollapse()`.
+ *
+ * AAD binding for encrypted rows keeps the four-tuple `AADInput` shape so
+ * the shared encryption module continues to serve auth.db (which uses
+ * different `scope: 'user'` AAD per user). Inside this store every row
+ * binds AAD with the constant `scope: 'workspace'`, `scopeId: ''` —
+ * cosmetic-only after the migration since each row is also uniquely
+ * keyed by `(key)`.
+ */
+import type { ActorContext, SecretMetadata, SecretStore, SetSecretInput } from './SecretStore.js';
+import type { SettingMetadata, SettingsStore, SetSettingInput } from './SettingsStore.js';
+import { AuditLogger } from './audit.js';
+export interface SqliteEncryptedStoreOptions {
+    dbPath: string;
+    masterKey: Uint8Array;
+    /** Defaults to 'mk_v1'. Bumped by master-key rotation. */
+    keyVersion?: string;
+    /** Optional secondary key for transition reads after a rotation. */
+    previousMasterKey?: Uint8Array;
+    previousKeyVersion?: string;
+}
+export declare class SqliteEncryptedStore implements SecretStore, SettingsStore {
+    private readonly db;
+    private readonly masterKey;
+    private readonly keyVersion;
+    private readonly previousMasterKey?;
+    private readonly previousKeyVersion?;
+    readonly audit: AuditLogger;
+    constructor(opts: SqliteEncryptedStoreOptions);
+    private initSchema;
+    /**
+     * One-shot migration: collapse the legacy `(scope, scope_id, key)` tables
+     * into the single-tier shape. Steps:
+     *
+     *   1. Detect legacy shape by querying `PRAGMA table_info` for the
+     *      `scope` column on settings or secrets.
+     *   2. Back up secrets.db → secrets.db.backup.<ts> with mode 0o600.
+     *   3. For each legacy row in `secrets`, decrypt with its original AAD
+     *      (4-tuple including the row's scope+scope_id), re-encrypt under
+     *      the new constant AAD, INSERT into the new table. Drop the old.
+     *   4. For `settings`, INSERT...SELECT keeping just `key`/`value_json`/
+     *      timestamps. Duplicate keys across scopes would collide; assert
+     *      none before commit.
+     *   5. For `audit_log`, ALTER TABLE DROP COLUMN scope/scope_id. SQLite
+     *      3.35+ supports this directly; PK is auto-increment so no rebuild.
+     *   6. Mark `meta.scope_collapse_migrated_at`. Re-running is a no-op.
+     *
+     * Failure modes: per-row decrypt failures during step 3 are logged as
+     * decrypt_fail audit rows and the row is skipped. The transaction
+     * still commits — the alternative is refusing to start when one
+     * historical row got out of sync, which is worse than dropping a key
+     * that already couldn't decrypt.
+     */
+    private migrateScopeCollapse;
+    private actorString;
+    set(input: SetSettingInput | SetSecretInput, actor: ActorContext): Promise<any>;
+    private setSetting;
+    get<T = unknown>(key: string): T | undefined;
+    list(): SettingMetadata[];
+    delete(key: string, actor: ActorContext): Promise<boolean>;
+    private setSecret;
+    describe(key: string): SecretMetadata | undefined;
+    listSecrets(actor?: ActorContext): SecretMetadata[];
+    unsafeGetForResolver(key: string): string | undefined;
+    /**
+     * Read a value from the `meta` key/value table — used by one-shot
+     * migrations to mark completion (e.g., scope-collapse, R2 structural
+     * import). Returns undefined when the row is absent. Not audited:
+     * meta rows are operational state, not configuration.
+     */
+    getMeta(key: string): string | undefined;
+    /**
+     * Write a value to the `meta` key/value table. Upserts. Paired with
+     * `getMeta` for migration completion markers.
+     */
+    setMeta(key: string, value: string): void;
+    close(): void;
+}