From 8f195c2f4999515118d033f49aeb4f3970149e47 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Thu, 27 Aug 2026 11:29:05 -0700 Subject: [PATCH] Let operators supply defaults for selected instance settings (#12285) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Hosting operators (a managed cloud, an internal shared server) tune the settings surface with `PAPERCLIP_HIDDEN_SETTINGS`, but hiding a control never changes its value > - An instance whose stored feedback-sharing preference is still the schema default ("prompt") keeps prompting users even when the operator hid the control, leaving them no way to answer > - More generally, operators have no supported way to change what a setting defaults to without patching code > - This pull request adds `PAPERCLIP_SETTING_DEFAULTS`, a generic operator-supplied read-time default overlay for registry-listed general settings > - The benefit is that any hosting operator can pair "hide the control" with "default the value", while explicit user choices and self-hosted stock behavior stay untouched ## Linked Issues or Issue Description No public issue exists; following the enhancement template: **What existing behavior does this improve?** Hosting operators need to supply the default value of selected instance settings (first: `feedbackDataSharingPreference`) via configuration, without patching code and without a hard-coded, opinionated constant in the product. **Subsystem affected** Server (instance-settings service, feedback service, boot) and `packages/shared` (settings schemas). **Current behavior** Setting defaults are fixed in the shared zod schemas. `PAPERCLIP_HIDDEN_SETTINGS` can hide the feedback-sharing control and floor writes, but the stored value stays "prompt", so issue-chat surfaces keep prompting with no way to answer. **Proposed behavior** `PAPERCLIP_SETTING_DEFAULTS` takes a JSON object validated against a shared registry of defaultable fields. The operator value substitutes for the schema default at read time: a field whose effective value is still the schema default resolves to the operator value; an explicit non-default user choice always wins. Never persisted; unsetting the variable restores stock behavior. Malformed JSON or an invalid value for a known field refuses startup (fail closed); unknown field names warn and are ignored (mixed-version fleet safe). **Reason and benefit** Any hosting operator can pair "hide the control" with "default the value" without forking the product. Explicit user choices and self-hosted stock behavior stay untouched. **Breaking changes** None. With the variable unset, every read path is byte-identical to before. ## What Changed - New `packages/shared/src/setting-defaults.ts`: `SETTING_DEFAULTS_ENV_KEY`, `DEFAULTABLE_GENERAL_SETTINGS` registry (currently `feedbackDataSharingPreference`), `parseSettingDefaults` (fail-closed for policy content, warn-ignore unknown fields), `applyOperatorGeneralDefaults` (pure read-time overlay), `stripOperatorGeneralEchoes` (persist-time echo strip, see below), re-exported from the package index. - New `server/src/services/setting-defaults.ts`: parse-once accessor mirroring `settings-visibility.ts`. - `server/src/services/instance-settings.ts`: `toGeneralView` applies the overlay in `get`/`getGeneral`/update responses; persisted writes never carry operator values. Because general-settings writes materialize every field, a stored schema-default value is treated as unchosen — deliberate, documented, and covered by tests. - `server/src/services/feedback.ts`: the preference-persistence branch now checks the effective (overlaid) preference, so a stray prompt answer cannot overwrite an operator default; its local normalize fallback now returns full schema defaults. - `server/src/index.ts`: boot-time fail-fast parse with a log line naming the defaulted settings, mirroring the managed-config posture. - The hidden-settings write floor (`assertNoHiddenSettingChanges`) keeps comparing against effective values, so clients echoing a full GET response keep working. To keep the overlay strictly read-time, `updateGeneral` strips such echoes at persist time: a write of the operator value over a field whose stored value is still the schema default (unchosen) maps back to the schema default, so an echo cannot promote the operator value into an explicit stored choice and later changes to (or removal of) `PAPERCLIP_SETTING_DEFAULTS` still take effect. A write of any other value, or over an explicit stored choice, persists as given. - Docs: `PAPERCLIP_SETTING_DEFAULTS` row + "Operator setting defaults" section in `docs/deploy/environment-variables.md`. - Tests: `packages/shared/src/setting-defaults.test.ts` (parse matrix, overlay precedence, echo-strip matrix, immutability) and `server/src/__tests__/instance-settings-operator-defaults.test.ts` (accessor, substitution, explicit-choice wins, unset identity, never-persisted, full-GET echo stays unchosen, explicit non-default write persists). ## Verification - `npx vitest run packages/shared/src/setting-defaults.test.ts server/src/__tests__/instance-settings-operator-defaults.test.ts server/src/__tests__/instance-settings-managed-overlay.test.ts` — 33 tests passing. - `npx vitest run server/src/__tests__/instance-settings-routes.test.ts server/src/__tests__/instance-settings-service.test.ts` — 57 passing; `npx vitest run server/src/__tests__/feedback-service.test.ts server/src/__tests__/issue-feedback-routes.test.ts` — 18 passing. - `pnpm --filter @paperclipai/shared typecheck` and `pnpm --filter @paperclipai/server typecheck` — clean. ## Risks - Low. With the variable unset every read path is byte-identical to before (identity overlay, covered by tests). The overlay is read-time only and never persisted, so no migration and no data risk. Fail-closed parsing means a bad policy value is a loud boot failure rather than silent drift — consistent with the existing managed-config contract. ## Model Used Claude (Anthropic), model id `claude-fable-5`, extended thinking, agentic tool use via Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --- docs/deploy/environment-variables.md | 26 ++- packages/shared/src/index.ts | 10 ++ packages/shared/src/setting-defaults.test.ts | 136 +++++++++++++++ packages/shared/src/setting-defaults.ts | 163 ++++++++++++++++++ ...nstance-settings-operator-defaults.test.ts | 132 ++++++++++++++ server/src/index.ts | 17 ++ server/src/services/feedback.ts | 15 +- server/src/services/instance-settings.ts | 28 ++- server/src/services/setting-defaults.ts | 40 +++++ 9 files changed, 555 insertions(+), 12 deletions(-) create mode 100644 packages/shared/src/setting-defaults.test.ts create mode 100644 packages/shared/src/setting-defaults.ts create mode 100644 server/src/__tests__/instance-settings-operator-defaults.test.ts create mode 100644 server/src/services/setting-defaults.ts 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; +}