diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.md index 134f372f28..6ee12bfa59 100644 --- a/docs/deploy/environment-variables.md +++ b/docs/deploy/environment-variables.md @@ -20,6 +20,7 @@ All environment variables that Paperclip uses for server configuration. | `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` | | `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. | | `PAPERCLIP_HIDDEN_SETTINGS` | (unset) | Comma-separated settings surfaces to hide from the UI and floor at the API, for operators hosting Paperclip for others (managed cloud, internal shared server). See [Hiding settings surfaces](#hiding-settings-surfaces). | +| `PAPERCLIP_SETTING_DEFAULTS` | (unset) | JSON object replacing the schema default of selected instance settings, for hosting operators. See [Operator setting defaults](#operator-setting-defaults). | ### Hiding settings surfaces @@ -58,7 +59,30 @@ All environment variables that Paperclip uses for server configuration. Unknown keys are logged and ignored, so one list can be rolled across a fleet of mixed app versions. With the variable unset nothing is hidden and behavior is identical to earlier releases. Hiding a toggle does not change its value; -pair hiding with the desired default where it matters. +pair hiding with the desired default where it matters (for general settings, +see [Operator setting defaults](#operator-setting-defaults)). + +### Operator setting defaults + +`PAPERCLIP_SETTING_DEFAULTS` takes a JSON object whose fields come from the +registry in `packages/shared/src/setting-defaults.ts` (currently +`feedbackDataSharingPreference`). The operator value substitutes for the +schema default at read time: any field whose effective value is still the +schema default resolves to the operator value, while an explicit non-default +user choice always wins. The overlay is never persisted, so unsetting the +variable restores stock behavior wherever a user has not chosen otherwise. +A client that writes back the full settings object it read does not persist +the operator value either: writing the operator value over a still-unchosen +field is treated as an echo of the overlay and the field stays unchosen. + +Example: `PAPERCLIP_SETTING_DEFAULTS='{"feedbackDataSharingPreference":"allowed"}'` +defaults AI feedback sharing to allowed; pairing it with +`instance.general.feedbackDataSharingPreference` in `PAPERCLIP_HIDDEN_SETTINGS` +also hides the control and floors value-changing writes. + +Unknown field names are logged and ignored (mixed-version fleet safe). +Malformed JSON or an invalid value for a known field refuses startup — policy +configuration fails closed. ## Secrets diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 709acf468c..69ecf2d7d6 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -2527,6 +2527,16 @@ export { type HideableSettingKey, type ParsedHiddenSettings, } from "./settings-visibility.js"; +export { + DEFAULTABLE_GENERAL_SETTINGS, + SETTING_DEFAULTS_ENV_KEY, + applyOperatorGeneralDefaults, + parseSettingDefaults, + stripOperatorGeneralEchoes, + type DefaultableGeneralSetting, + type OperatorSettingDefaults, + type ParsedSettingDefaults, +} from "./setting-defaults.js"; // --- Runtime exposure (opt-in Tailscale HTTPS for managed branch runtimes) --- // PAP-17049 plan, PAP-17050 threat-model verdict. Contract shared across DB, diff --git a/packages/shared/src/setting-defaults.test.ts b/packages/shared/src/setting-defaults.test.ts new file mode 100644 index 0000000000..f5554686f7 --- /dev/null +++ b/packages/shared/src/setting-defaults.test.ts @@ -0,0 +1,136 @@ +import { describe, expect, it } from "vitest"; +import { + DEFAULTABLE_GENERAL_SETTINGS, + SETTING_DEFAULTS_ENV_KEY, + applyOperatorGeneralDefaults, + parseSettingDefaults, + stripOperatorGeneralEchoes, +} from "./setting-defaults.js"; +import { instanceGeneralSettingsSchema } from "./validators/instance.js"; + +describe("parseSettingDefaults", () => { + it("returns null defaults for an unset or blank variable", () => { + expect(parseSettingDefaults(undefined)).toEqual({ defaults: null, unknown: [] }); + expect(parseSettingDefaults("")).toEqual({ defaults: null, unknown: [] }); + expect(parseSettingDefaults(" ")).toEqual({ defaults: null, unknown: [] }); + }); + + it("parses known fields and validates their values", () => { + const { defaults, unknown } = parseSettingDefaults( + '{"feedbackDataSharingPreference":"allowed"}', + ); + expect(defaults).toEqual({ feedbackDataSharingPreference: "allowed" }); + expect(unknown).toEqual([]); + }); + + it("collects unknown fields instead of failing, for mixed-version fleets", () => { + const { defaults, unknown } = parseSettingDefaults( + '{"feedbackDataSharingPreference":"not_allowed","someFutureSetting":true}', + ); + expect(defaults).toEqual({ feedbackDataSharingPreference: "not_allowed" }); + expect(unknown).toEqual(["someFutureSetting"]); + }); + + it("fails closed on malformed JSON and non-object shapes", () => { + expect(() => parseSettingDefaults("{nope")).toThrow(SETTING_DEFAULTS_ENV_KEY); + expect(() => parseSettingDefaults('"allowed"')).toThrow(/JSON object/); + expect(() => parseSettingDefaults("[1,2]")).toThrow(/JSON object/); + expect(() => parseSettingDefaults("null")).toThrow(/JSON object/); + }); + + it("fails closed on an invalid value for a known field", () => { + expect(() => + parseSettingDefaults('{"feedbackDataSharingPreference":"sometimes"}'), + ).toThrow(/feedbackDataSharingPreference/); + }); + + it("keeps every registry entry a real general-settings field", () => { + const shape = Object.keys(instanceGeneralSettingsSchema.shape); + for (const key of DEFAULTABLE_GENERAL_SETTINGS) { + expect(shape).toContain(key); + } + }); +}); + +describe("applyOperatorGeneralDefaults", () => { + const schemaDefaults = instanceGeneralSettingsSchema.parse({}); + + it("is the identity when no operator defaults are configured", () => { + expect(applyOperatorGeneralDefaults(schemaDefaults, null)).toBe(schemaDefaults); + }); + + it("substitutes the operator value where the schema default still holds", () => { + const overlaid = applyOperatorGeneralDefaults(schemaDefaults, { + feedbackDataSharingPreference: "allowed", + }); + expect(overlaid.feedbackDataSharingPreference).toBe("allowed"); + // Other fields are untouched. + expect(overlaid.backupRetention).toEqual(schemaDefaults.backupRetention); + }); + + it("never overrides an explicit non-default choice", () => { + const chosen = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const }; + const overlaid = applyOperatorGeneralDefaults(chosen, { + feedbackDataSharingPreference: "allowed", + }); + expect(overlaid.feedbackDataSharingPreference).toBe("not_allowed"); + expect(overlaid).toBe(chosen); + }); + + it("does not mutate its input", () => { + const input = { ...schemaDefaults }; + applyOperatorGeneralDefaults(input, { feedbackDataSharingPreference: "allowed" }); + expect(input.feedbackDataSharingPreference).toBe( + schemaDefaults.feedbackDataSharingPreference, + ); + }); +}); + +describe("stripOperatorGeneralEchoes", () => { + const schemaDefaults = instanceGeneralSettingsSchema.parse({}); + const defaults = { feedbackDataSharingPreference: "allowed" as const }; + + it("is the identity when no operator defaults are configured", () => { + const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const }; + expect(stripOperatorGeneralEchoes(schemaDefaults, next, null)).toBe(next); + }); + + it("maps an echoed operator value on an unchosen field back to the schema default", () => { + // Stored is still the schema default (unchosen); the incoming full-object + // echo carries the overlaid operator value. Persisting it would make the + // operator value sticky, so it maps back to the schema default. + const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const }; + const stripped = stripOperatorGeneralEchoes(schemaDefaults, next, defaults); + expect(stripped.feedbackDataSharingPreference).toBe( + schemaDefaults.feedbackDataSharingPreference, + ); + }); + + it("keeps an incoming value that differs from the operator default", () => { + const next = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const }; + const stripped = stripOperatorGeneralEchoes(schemaDefaults, next, defaults); + expect(stripped).toBe(next); + expect(stripped.feedbackDataSharingPreference).toBe("not_allowed"); + }); + + it("keeps a write over an explicit stored choice, even at the operator value", () => { + // The user previously chose "not_allowed" and now picks the operator's + // value: stored is not the schema default, so this is a real transition + // and persists as given. + const stored = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const }; + const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const }; + const stripped = stripOperatorGeneralEchoes(stored, next, defaults); + expect(stripped).toBe(next); + expect(stripped.feedbackDataSharingPreference).toBe("allowed"); + }); + + it("does not mutate its inputs", () => { + const stored = { ...schemaDefaults }; + const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const }; + stripOperatorGeneralEchoes(stored, next, defaults); + expect(next.feedbackDataSharingPreference).toBe("allowed"); + expect(stored.feedbackDataSharingPreference).toBe( + schemaDefaults.feedbackDataSharingPreference, + ); + }); +}); diff --git a/packages/shared/src/setting-defaults.ts b/packages/shared/src/setting-defaults.ts new file mode 100644 index 0000000000..672726c2ea --- /dev/null +++ b/packages/shared/src/setting-defaults.ts @@ -0,0 +1,163 @@ +import { instanceGeneralSettingsSchema } from "./validators/instance.js"; +import type { InstanceGeneralSettings } from "./types/instance.js"; + +/** + * Operator-configurable setting defaults. + * + * A hosting operator (a managed cloud, an internal shared server) can replace + * the schema default of selected instance settings by setting the + * `PAPERCLIP_SETTING_DEFAULTS` environment variable to a JSON object, e.g. + * `{"feedbackDataSharingPreference":"allowed"}`. The operator value + * substitutes for the schema default at read time: any field whose effective + * value is still the schema default resolves to the operator value, while an + * explicit non-default user choice always wins. The overlay is never + * persisted, so unsetting the variable restores stock behavior everywhere a + * user has not chosen otherwise. + * + * Parsing is fail-closed for policy content: malformed JSON or an invalid + * value for a known field is an error (the server refuses to boot), because a + * silently dropped policy default is worse than a loud failure. Unknown field + * names are warned about and ignored, so one value can be rolled across a + * fleet of mixed app versions where older images predate a field. + * + * Pairing note: an operator that also wants the control invisible hides it + * with `PAPERCLIP_HIDDEN_SETTINGS` (see settings-visibility.ts); the two + * mechanisms are orthogonal. + */ + +export const SETTING_DEFAULTS_ENV_KEY = "PAPERCLIP_SETTING_DEFAULTS"; + +/** Instance → General fields whose schema default an operator may replace. */ +export const DEFAULTABLE_GENERAL_SETTINGS = [ + "feedbackDataSharingPreference", +] as const; + +export type DefaultableGeneralSetting = (typeof DEFAULTABLE_GENERAL_SETTINGS)[number]; + +export type OperatorSettingDefaults = Partial< + Pick +>; + +export interface ParsedSettingDefaults { + /** Validated operator defaults for known fields; null when the var is unset. */ + defaults: OperatorSettingDefaults | null; + /** Unrecognized field names, for the caller to warn about. */ + unknown: string[]; +} + +const defaultableFieldsSchema = instanceGeneralSettingsSchema + .pick( + Object.fromEntries(DEFAULTABLE_GENERAL_SETTINGS.map((key) => [key, true])) as { + [K in DefaultableGeneralSetting]: true; + }, + ) + .partial(); + +/** The all-schema-defaults view used to decide whether a value was chosen. */ +const schemaDefaults: InstanceGeneralSettings = instanceGeneralSettingsSchema.parse({}); + +/** + * Parse a `PAPERCLIP_SETTING_DEFAULTS`-style JSON object. + * + * @throws when the JSON is malformed, not an object, or a known field carries + * an invalid value — policy configuration fails closed. + */ +export function parseSettingDefaults(raw: string | undefined): ParsedSettingDefaults { + if (raw === undefined || raw.trim() === "") return { defaults: null, unknown: [] }; + let parsed: unknown; + try { + parsed = JSON.parse(raw); + } catch (error) { + throw new Error( + `${SETTING_DEFAULTS_ENV_KEY} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, + ); + } + if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) { + throw new Error(`${SETTING_DEFAULTS_ENV_KEY} must be a JSON object of setting defaults`); + } + const known: Record = {}; + const unknown: string[] = []; + const defaultable = new Set(DEFAULTABLE_GENERAL_SETTINGS); + for (const [key, value] of Object.entries(parsed)) { + if (defaultable.has(key)) { + known[key] = value; + } else { + unknown.push(key); + } + } + const result = defaultableFieldsSchema.safeParse(known); + if (!result.success) { + throw new Error( + `${SETTING_DEFAULTS_ENV_KEY} carries an invalid value: ${result.error.issues + .map((issue) => `${issue.path.join(".")}: ${issue.message}`) + .join("; ")}`, + ); + } + return { defaults: result.data as OperatorSettingDefaults, unknown }; +} + +/** + * Overlay operator defaults onto normalized general settings at read time. + * + * The operator value substitutes for the schema default: a field still at its + * schema default (absent from storage, or stored equal to it) resolves to the + * operator value; an explicit non-default choice is untouched. Callers must + * never persist the result. + */ +export function applyOperatorGeneralDefaults( + general: InstanceGeneralSettings, + defaults: OperatorSettingDefaults | null, +): InstanceGeneralSettings { + if (!defaults) return general; + let next: InstanceGeneralSettings | null = null; + for (const key of DEFAULTABLE_GENERAL_SETTINGS) { + const value = defaults[key]; + if (value === undefined) continue; + if (general[key] === schemaDefaults[key] && general[key] !== value) { + next ??= { ...general }; + next[key] = value; + } + } + return next ?? general; +} + +/** + * Strip overlay echoes from a general-settings write at persist time. + * + * A client that writes back the full object it read (a full-GET echo) sends + * the overlaid operator value for a field the user never chose. Persisting + * that echo would promote the operator value into an explicit stored choice — + * sticky across later changes to, or removal of, the environment variable. + * This maps such a write back to the schema default: a field whose stored + * value is still the schema default (unchosen) and whose incoming value + * equals the operator default stays unchosen, keeping the overlay + * strictly read-time. + * + * A user cannot be distinguished from an echo when they deliberately pick the + * value that already shows as the default, so that pick also stays unchosen — + * the mirror image of the documented "stored schema default is treated as + * unchosen" rule, with identical effective behavior. Any other write persists + * as given: an incoming value that differs from the operator default, or a + * write over an explicit stored choice. + */ +export function stripOperatorGeneralEchoes( + stored: InstanceGeneralSettings, + next: InstanceGeneralSettings, + defaults: OperatorSettingDefaults | null, +): InstanceGeneralSettings { + if (!defaults) return next; + let result: InstanceGeneralSettings | null = null; + for (const key of DEFAULTABLE_GENERAL_SETTINGS) { + const value = defaults[key]; + if (value === undefined) continue; + if ( + stored[key] === schemaDefaults[key] && + next[key] === value && + next[key] !== schemaDefaults[key] + ) { + result ??= { ...next }; + result[key] = schemaDefaults[key]; + } + } + return result ?? next; +} diff --git a/server/src/__tests__/instance-settings-operator-defaults.test.ts b/server/src/__tests__/instance-settings-operator-defaults.test.ts new file mode 100644 index 0000000000..368e0fecbd --- /dev/null +++ b/server/src/__tests__/instance-settings-operator-defaults.test.ts @@ -0,0 +1,132 @@ +import { describe, expect, it } from "vitest"; +import type { Db } from "@paperclipai/db"; +import { instanceSettingsService } from "../services/instance-settings.js"; +import { getOperatorSettingDefaults } from "../services/setting-defaults.js"; + +const DEFAULTS_RAW = JSON.stringify({ feedbackDataSharingPreference: "allowed" }); + +function defaultsEnv(raw: string | undefined = DEFAULTS_RAW) { + return { PAPERCLIP_SETTING_DEFAULTS: raw }; +} + +/** Mirrors the stub in instance-settings-managed-overlay.test.ts. */ +function stubDb(row: Record) { + const persistedSets: Array> = []; + const db = { + select: () => ({ from: () => ({ where: () => Promise.resolve([row]) }) }), + insert: () => { + throw new Error("unexpected insert in test"); + }, + update: () => ({ + set: (values: Record) => { + persistedSets.push(values); + return { where: () => ({ returning: () => Promise.resolve([{ ...row, ...values }]) }) }; + }, + }), + } as unknown as Db; + return { db, persistedSets }; +} + +function settingsRow(general: Record) { + return { + id: "row-1", + singletonKey: "default", + defaultEnvironmentId: null, + general, + experimental: {}, + createdAt: new Date("2026-06-20T00:00:00.000Z"), + updatedAt: new Date("2026-06-20T00:00:00.000Z"), + }; +} + +describe("getOperatorSettingDefaults", () => { + it("returns null with the variable unset", () => { + expect(getOperatorSettingDefaults({})).toBeNull(); + }); + + it("parses once and ignores unknown fields", () => { + const defaults = getOperatorSettingDefaults( + defaultsEnv('{"feedbackDataSharingPreference":"allowed","futureField":1}'), + ); + expect(defaults).toEqual({ feedbackDataSharingPreference: "allowed" }); + }); + + it("throws on malformed policy JSON (fail closed)", () => { + expect(() => getOperatorSettingDefaults(defaultsEnv("{broken"))).toThrow( + /PAPERCLIP_SETTING_DEFAULTS/, + ); + }); +}); + +describe("instanceSettingsService operator setting defaults", () => { + it("substitutes the operator value where the schema default holds", async () => { + const { db } = stubDb(settingsRow({})); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const general = await svc.getGeneral(); + expect(general.feedbackDataSharingPreference).toBe("allowed"); + }); + + it("treats a stored schema-default value as unchosen", async () => { + // updateGeneral materializes every field with its schema default, so a + // stored "prompt" does not mean the user chose "prompt" — the operator + // default still substitutes. + const { db } = stubDb(settingsRow({ feedbackDataSharingPreference: "prompt" })); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const general = await svc.getGeneral(); + expect(general.feedbackDataSharingPreference).toBe("allowed"); + }); + + it("keeps an explicit non-default user choice", async () => { + const { db } = stubDb(settingsRow({ feedbackDataSharingPreference: "not_allowed" })); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const general = await svc.getGeneral(); + expect(general.feedbackDataSharingPreference).toBe("not_allowed"); + }); + + it("changes nothing with the variable unset (self-hosted)", async () => { + const { db } = stubDb(settingsRow({})); + const svc = instanceSettingsService(db, { runtimeEnv: {} }); + const general = await svc.getGeneral(); + expect(general.feedbackDataSharingPreference).toBe("prompt"); + }); + + it("overlays reads but never persists the operator value", async () => { + const { db, persistedSets } = stubDb(settingsRow({})); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const result = await svc.updateGeneral({ censorUsernameInLogs: true }); + // The response reflects the overlay... + expect(result.general.feedbackDataSharingPreference).toBe("allowed"); + // ...but what hit the database is the schema default, not the operator's. + expect(persistedSets).toHaveLength(1); + const persistedGeneral = persistedSets[0]!.general as Record; + expect(persistedGeneral.censorUsernameInLogs).toBe(true); + expect(persistedGeneral.feedbackDataSharingPreference).toBe("prompt"); + }); + + it("does not let a full-GET echo promote the operator value into a choice", async () => { + // A client PUTs back the full object it read, including the overlaid + // "allowed". The stored value is still the schema default (unchosen), so + // the echo maps back to the schema default: changing or unsetting + // PAPERCLIP_SETTING_DEFAULTS later still takes effect. + const { db, persistedSets } = stubDb(settingsRow({})); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const echoed = await svc.getGeneral(); + expect(echoed.feedbackDataSharingPreference).toBe("allowed"); + const result = await svc.updateGeneral({ ...echoed, censorUsernameInLogs: true }); + expect(result.general.feedbackDataSharingPreference).toBe("allowed"); + expect(persistedSets).toHaveLength(1); + const persistedGeneral = persistedSets[0]!.general as Record; + expect(persistedGeneral.censorUsernameInLogs).toBe(true); + expect(persistedGeneral.feedbackDataSharingPreference).toBe("prompt"); + }); + + it("persists an explicit write of a value that differs from the operator default", async () => { + const { db, persistedSets } = stubDb(settingsRow({})); + const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() }); + const result = await svc.updateGeneral({ feedbackDataSharingPreference: "not_allowed" }); + expect(result.general.feedbackDataSharingPreference).toBe("not_allowed"); + expect(persistedSets).toHaveLength(1); + const persistedGeneral = persistedSets[0]!.general as Record; + expect(persistedGeneral.feedbackDataSharingPreference).toBe("not_allowed"); + }); +}); diff --git a/server/src/index.ts b/server/src/index.ts index 7fff89d1bb..e668adf7a8 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -39,6 +39,7 @@ import { getManagedInstanceConfig, type ManagedInstanceConfig, } from "./services/managed-config.js"; +import { getOperatorSettingDefaults } from "./services/setting-defaults.js"; import { setupEnvironmentCustomImageTerminalWebSocketServer } from "./realtime/environment-custom-image-terminal-ws.js"; import { setupLiveEventsWebSocketServer } from "./realtime/live-events-ws.js"; import { setupRunnerPrpWebSocketServer } from "./realtime/runner-prp-ws.js"; @@ -689,6 +690,22 @@ export async function startServer(): Promise { throw err; } + // Operator setting defaults (PAPERCLIP_SETTING_DEFAULTS). Same fail-closed + // posture as the managed-config parse above: malformed JSON or an invalid + // value for a known field refuses startup; unknown field names only warn. + try { + const operatorDefaults = getOperatorSettingDefaults(); + if (operatorDefaults && Object.keys(operatorDefaults).length > 0) { + logger.warn( + { defaultedSettings: Object.keys(operatorDefaults).sort() }, + "operator setting defaults active", + ); + } + } catch (err) { + logger.error({ err }, "invalid PAPERCLIP_SETTING_DEFAULTS; refusing to start (fail closed)"); + throw err; + } + const uiMode = config.uiDevMiddleware ? "vite-dev" : config.serveUi ? "static" : "none"; const storageService = createStorageServiceFromConfig(config); const feedback = feedbackService(db as any, { diff --git a/server/src/services/feedback.ts b/server/src/services/feedback.ts index 38a818c9e8..7698520eb0 100644 --- a/server/src/services/feedback.ts +++ b/server/src/services/feedback.ts @@ -25,6 +25,7 @@ import { parseOpenCodeJsonl } from "@paperclipai/adapter-opencode-local/server"; import { DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE, DEFAULT_FEEDBACK_DATA_SHARING_TERMS_VERSION, + applyOperatorGeneralDefaults, instanceGeneralSettingsSchema, type FeedbackTargetType, type FeedbackTraceBundle, @@ -46,6 +47,7 @@ import { sha256Digest, } from "./feedback-redaction.js"; import { getRunLogStore } from "./run-log-store.js"; +import { getOperatorSettingDefaults } from "./setting-defaults.js"; const FEEDBACK_SCHEMA_VERSION = "paperclip-feedback-envelope-v2"; const FEEDBACK_BUNDLE_VERSION = "paperclip-feedback-bundle-v2"; @@ -157,10 +159,7 @@ function contentTypeForPath(filePath: string) { function normalizeInstanceGeneralSettings(raw: unknown) { const parsed = instanceGeneralSettingsSchema.safeParse(raw ?? {}); if (parsed.success) return parsed.data; - return { - censorUsernameInLogs: false, - feedbackDataSharingPreference: DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE, - }; + return instanceGeneralSettingsSchema.parse({}); } function buildIssuePath(identifier: string | null) { @@ -1977,7 +1976,13 @@ export function feedbackService(db: Db, options: FeedbackServiceOptions = {}) { }) .then((rows) => rows[0] ?? null)); - const currentGeneral = normalizeInstanceGeneralSettings(currentInstanceSettings?.general); + // Operator setting defaults apply to the effective value: when the + // operator supplies a feedback-sharing default, the preference is no + // longer "prompt", so a stray answer must not persist over it. + const currentGeneral = applyOperatorGeneralDefaults( + normalizeInstanceGeneralSettings(currentInstanceSettings?.general), + getOperatorSettingDefaults(), + ); if (currentInstanceSettings && currentGeneral.feedbackDataSharingPreference === "prompt") { const nextSharingPreference = sharedWithLabs ? "allowed" : "not_allowed"; const currentGeneralRaw = asRecord(currentInstanceSettings.general) ?? {}; diff --git a/server/src/services/instance-settings.ts b/server/src/services/instance-settings.ts index d51b4684f3..1776fb2bdd 100644 --- a/server/src/services/instance-settings.ts +++ b/server/src/services/instance-settings.ts @@ -28,8 +28,10 @@ import { type PatchInstanceSettings, type PatchInstanceExperimentalSettings, } from "@paperclipai/shared"; +import { applyOperatorGeneralDefaults, stripOperatorGeneralEchoes } from "@paperclipai/shared"; import { eq } from "drizzle-orm"; import { getManagedInstanceConfig, type ManagedInstanceConfig } from "./managed-config.js"; +import { getOperatorSettingDefaults } from "./setting-defaults.js"; const DEFAULT_SINGLETON_KEY = "default"; const instanceGeneralSettingsStorageSchema = instanceGeneralSettingsSchema.strip(); @@ -328,6 +330,15 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService // Fail closed: a malformed PAPERCLIP_MANAGED_CONFIG throws here (and at // boot in index.ts) rather than silently running without the overlay. const managedConfig = getManagedInstanceConfig(options.runtimeEnv ?? process.env); + // Same posture for PAPERCLIP_SETTING_DEFAULTS: parsed once, applied per + // read, never persisted (see applyOperatorGeneralDefaults) — including on + // the write path, where a full-GET echo of the overlaid value is stripped + // back to the schema default (see stripOperatorGeneralEchoes). + const operatorDefaults = getOperatorSettingDefaults(options.runtimeEnv ?? process.env); + + function toGeneralView(raw: unknown): InstanceGeneralSettings { + return applyOperatorGeneralDefaults(normalizeGeneralSettings(raw), operatorDefaults); + } function toExperimentalView(raw: unknown): InstanceExperimentalSettingsWithManaged { const { experimental, managedKeys } = applyManagedExperimentalOverlay( @@ -342,7 +353,7 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService return { id: row.id, defaultEnvironmentId: row.defaultEnvironmentId ?? null, - general: normalizeGeneralSettings(row.general), + general: toGeneralView(row.general), experimental: toExperimentalView(row.experimental), createdAt: row.createdAt, updatedAt: row.updatedAt, @@ -415,7 +426,7 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService getGeneral: async (): Promise => { const row = await getOrCreateRow(); - return normalizeGeneralSettings(row.general); + return toGeneralView(row.general); }, getExperimental: async (): Promise => { @@ -425,10 +436,15 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService updateGeneral: async (patch: PatchInstanceGeneralSettings): Promise => { const current = await getOrCreateRow(); - const nextGeneral = normalizeGeneralSettings({ - ...normalizeGeneralSettings(current.general), - ...patch, - }); + const storedGeneral = normalizeGeneralSettings(current.general); + // A full-GET echo carries the overlaid operator value for a field the + // user never chose; stripping it keeps the overlay strictly read-time, + // so changing or unsetting the variable later still takes effect. + const nextGeneral = stripOperatorGeneralEchoes( + storedGeneral, + normalizeGeneralSettings({ ...storedGeneral, ...patch }), + operatorDefaults, + ); const now = new Date(); const [updated] = await db .update(instanceSettings) diff --git a/server/src/services/setting-defaults.ts b/server/src/services/setting-defaults.ts new file mode 100644 index 0000000000..a334067a0e --- /dev/null +++ b/server/src/services/setting-defaults.ts @@ -0,0 +1,40 @@ +import { + SETTING_DEFAULTS_ENV_KEY, + parseSettingDefaults, + type OperatorSettingDefaults, +} from "@paperclipai/shared"; +import { logger } from "../middleware/logger.js"; + +export { SETTING_DEFAULTS_ENV_KEY }; + +export type SettingDefaultsEnv = Record; + +let cache: { raw: string | undefined; defaults: OperatorSettingDefaults | null } | null = null; + +/** + * Operator setting defaults from the `PAPERCLIP_SETTING_DEFAULTS` env var + * (JSON object validated against the shared registry). Parse-once accessor + * keyed on the raw value, mirroring settings-visibility.ts: tests passing a + * custom env re-parse when the raw value differs; process.env callers share + * one parse for the process lifetime. + * + * Unknown field names are warned about once and ignored (mixed-version fleet + * safe). Malformed JSON or an invalid value for a known field throws — policy + * configuration fails closed, and index.ts calls this at boot so the failure + * is loud and immediate. + */ +export function getOperatorSettingDefaults( + env: SettingDefaultsEnv = process.env, +): OperatorSettingDefaults | null { + const raw = env[SETTING_DEFAULTS_ENV_KEY]; + if (cache && cache.raw === raw) return cache.defaults; + const { defaults, unknown } = parseSettingDefaults(raw); + if (unknown.length > 0) { + logger.warn( + { unknownKeys: unknown }, + `${SETTING_DEFAULTS_ENV_KEY} contains unknown fields; they are ignored`, + ); + } + cache = { raw, defaults }; + return cache.defaults; +}