Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { PRIVATE_CREDENTIALS, putCredential } from '../services/privateKeyStore.js';
import { Router } from 'express';
import { z } from 'zod';
import { getSettings, updateSettingsWith } from '../services/settings.js';
import { assertHostControl } from '../services/authGate.js';
import { getAiAssignments, updateAiAssignment } from '../services/aiAssignments.js';
import { saveSubscriptionCosts } from '../services/subscriptionCosts.js';
import { savePlanTiers } from '../services/subscriptions.js';
import { saveApiBilledInstanceIds } from '../services/usageFleetBilling.js';
import {
setCodexParallelLimit,
CODEX_PARALLEL_MIN,
CODEX_PARALLEL_MAX,
CODEX_PARALLEL_DEFAULT,
} from '../services/mediaJobQueue/index.js';
import { assertMediaRoutingConfig } from '../services/federatedMedia/routingPolicy.js';
import { assertConfiguredEidoverseInstalled, getInstanceFeatures, updateEidoverseWorldsRepo, updateEidoverseWorldsSource, updateInstanceFeature, updateInstanceFeatureGroup } from '../services/instanceFeatures.js';
import { getCredentialInventory } from '../services/credentialInventory.js';
import { installEidoverse } from '../services/eidoverse.js';
import { ensureEidoverseHost } from '../services/eidoverseHost.js';
import { isGitHubRepoUrl } from '../lib/repoUrl.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { isAllowedPython } from '../lib/pythonSetup.js';
import { isPlainObject } from '../lib/objects.js';
import { resolveBackupConfig } from '../lib/backupConfig.js';
import { storableAutoUpdateConfig } from '../lib/sharedSchemas.js';
import { DEFAULT_UNTRUSTED_CONTENT_POLICY, untrustedContentSettingsSchema } from '../lib/untrustedContent.js';
import { agentContextSettingsSchema } from '../lib/agentContextValidation.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { settingsSlicePatchSchema, privateCredentialParamsSchema, privateCredentialInputSchema, backupConfigSchema, autoUpdateSettingsSchema, sharingSettingsPatchSchema, featureProviderConfigSchema, autofixerSettingsSchema, codeReviewSettingsSchema, locationSettingsSchema, hideFirstRunCardSchema, networkSetupPreferenceSchema, settingsEmbeddingsSchema, localLlmSettingsSchema, imessageConfigSchema, signalConfigSchema, beeperSettingsSchema, beeperSavedScopesSchema, spotifyConfigSchema, youtubeConfigSchema, apiAccessSettingsSchema, instanceFeatureSettingsSchema, instanceFeatureIdSchema, instanceFeatureUpdateSchema, instanceFeatureGroupSettingsSchema, instanceFeatureGroupIdSchema, instanceFeatureGroupUpdateSchema, loraTrainingConfigSchema, pipelineEditorialChecksSettingsSchema, creativeDirectorSettingsSchema, musicSettingsSchema, federationSettingsSchema, privacySettingsSchema, seriesAutopilotSettingsSchema, layeredIntelligenceSettingsSchema, imageGenGrokSettingsSchema, imageGenAgySettingsSchema, imageGenFalSettingsSchema, imageGenRunwaySettingsSchema, renderDefaultsSettingsSchema, videoGenSettingsSchema, subscriptionCostsMapSchema, subscriptionPlanTiersMapSchema, usageApiBilledInstanceIdsSchema, namedOrchestrationProfileSchema, orchestrationProfilesSettingsSchema, harnessSettingsSchema, credentialBootstrapsSettingsSchema, validateRequest } from '../lib/validation.js';
import { filmLookSavedPresetsSchema } from '../lib/filmLookValidation.js';
import { dockerContainmentSettingsSchema } from '../lib/dockerContainmentValidation.js';
const router = Router();
const aiAssignmentUpdateSchema = z.object({
providerId: z.string().trim().max(128).nullable().optional(),
model: z.string().trim().max(300).nullable().optional(),
effort: z.enum(EFFORT_LEVELS).nullable().optional(),
}).strict();
const eidoverseRepoSchema = z.object({
worldsRepoUrl: z.string().trim().max(500).refine(isGitHubRepoUrl, 'Must be a GitHub repository URL'),
worldsBranch: z.string().trim().max(255).regex(/^[^\u0000-\u001f\u007f]*$/).optional(),
}).strict();
// Server-authoritative bounds the client UI can render directly so the form
// clamp never drifts away from what the queue actually enforces. Stitched
// under `imageGen.codex.parallelLimitBounds` since that's where the field
// the bounds describe lives.
const decorateBounds = (settings) => ({
...settings,
untrustedContent: { scopeAdherenceEnabled: settings.untrustedContent?.scopeAdherenceEnabled !== false, defaults: { ...DEFAULT_UNTRUSTED_CONTENT_POLICY, ...settings.untrustedContent?.defaults }, sources: settings.untrustedContent?.sources || {} },
imageGen: {
...(settings.imageGen || {}),
codex: {
...(settings.imageGen?.codex || {}),
parallelLimitBounds: {
min: CODEX_PARALLEL_MIN,
max: CODEX_PARALLEL_MAX,
default: CODEX_PARALLEL_DEFAULT,
},
},
},
});
// Third-party API tokens that live OUTSIDE the `secrets.*` hierarchy but must
// never be echoed to the client (#1821). The Settings UI reads only their
// *presence* from dedicated status routes (`GET /api/image-gen/setup/hf-token-
// status`, `GET /api/loras/auth/civitai` → `hasKey`), never the raw value here,
// so stripping them is non-breaking. Sibling fields under each parent are
// preserved; arrays are left untouched (a legacy/malformed `civitai: ['x']`
// must not be spread into `{ '0': 'x' }`).
const redactExternalTokens = (settings) => {
const next = { ...settings };
if (isPlainObject(next.imageGen)) {
const { hfToken, ...rest } = next.imageGen;
next.imageGen = rest;
}
if (isPlainObject(next.civitai)) {
const { apiKey, ...rest } = next.civitai;
next.civitai = rest;
}
// Beeper access token (#30/#31) — write-only, same posture as
// imageGen.hfToken / civitai.apiKey above. Since #31 the live credential is
// AES-256-GCM in `beeper_credentials`, not here; this strip covers the LEGACY
// plaintext field, which `beeperCredentials.resolveBeeperToken` still reads as
// a fallback for an install that hand-edited one. Nothing writes it, and it
// must never be echoed back to the client on a settings GET.
if (isPlainObject(next.beeper)) {
const { token, ...rest } = next.beeper;
next.beeper = rest;
}
// fal.ai / reactor.inc video keys (#8997) — same write-only posture, but
// nested one level deeper (`videoGen.fal.apiKey` / `videoGen.reactor.apiKey`),
// since `hydratePrivateKeys` re-injects them into `settings.videoGen` on
// every read (privateKeyStore.js). The Settings UI reads only presence, via
// GET /api/settings/credentials.
if (isPlainObject(next.videoGen)) {
const videoGen = { ...next.videoGen };
if (isPlainObject(videoGen.fal)) {
const { apiKey, ...rest } = videoGen.fal;
videoGen.fal = rest;
}
if (isPlainObject(videoGen.reactor)) {
const { apiKey, ...rest } = videoGen.reactor;
videoGen.reactor = rest;
}
if (isPlainObject(videoGen.runway)) {
const { apiKey, ...rest } = videoGen.runway;
videoGen.runway = rest;
}
next.videoGen = videoGen;
}
return next;
};
// Sub-keys this route must never clobber, because it isn't their write path.
// `updateSettings` shallow-merges TOP-LEVEL keys, so an incoming `imageGen` /
// `civitai` / `videoGen` object replaces the stored one wholesale — and a
// client that GETs settings, rebuilds the parent and PUTs it back (e.g.
// `patchSettingsSlice('imageGen.local', …)`) would drop any sub-key it never
// saw or never rendered. A parent absent from the patch needs nothing — the
// top-level merge keeps the stored object untouched.
//
// - imageGen.hfToken / civitai.apiKey: write-only tokens, redacted out of
// GET, owned by /setup/hf-token and /loras/auth/civitai. Re-injected only
// when the incoming parent omits them, so those routes can still write.
// - videoGen.acceptedModelTerms: the install's restricted-model license
// acknowledgements, owned exclusively by /api/video-gen/model-terms — which
// is where an id is checked against a model that actually declares it. The
// stored value ALWAYS wins here, so a settings save can neither drop an
// acknowledgement (silently 403ing every gated render) nor mint one that
// no model's terms gate would ever match.
const preserveExternallyOwnedKeys = (next, current) => {
const carryOver = (parentKey, childKey, { alwaysStored = false } = {}) => {
const incoming = next[parentKey];
const stored = current?.[parentKey]?.[childKey];
if (!isPlainObject(incoming)) return;
if (!alwaysStored && childKey in incoming) return;
if (stored === undefined) {
if (alwaysStored && childKey in incoming) {
const { [childKey]: _dropped, ...rest } = incoming;
next[parentKey] = rest;
}
return;
}
next[parentKey] = { ...incoming, [childKey]: stored };
};
// Same carryOver contract, one level deeper — for `videoGen.fal.apiKey` /
// `videoGen.reactor.apiKey` (#8997), which live under a grandchild key
// rather than a direct child of the top-level slice.
const carryOverNested = (parentKey, childKey, grandchildKey) => {
const incomingParent = next[parentKey];
if (!isPlainObject(incomingParent)) return;
const incoming = incomingParent[childKey];
const stored = current?.[parentKey]?.[childKey]?.[grandchildKey];
if (!isPlainObject(incoming) || grandchildKey in incoming) return;
if (stored === undefined) return;
next[parentKey] = { ...incomingParent, [childKey]: { ...incoming, [grandchildKey]: stored } };
};
carryOver('imageGen', 'hfToken');
carryOver('civitai', 'apiKey');
carryOver('videoGen', 'acceptedModelTerms', { alwaysStored: true });
carryOverNested('videoGen', 'fal', 'apiKey');
carryOverNested('videoGen', 'reactor', 'apiKey');
carryOverNested('videoGen', 'runway', 'apiKey');
// beeperSettingsSchema is `.strict()` with no `token`/`tokenExpiresAt`
// field, so a valid `beeper` PUT through this route can never carry either
// — without this, the generic top-level shallow merge (`{ ...current,
// ...settingsPatch }`) would REPLACE `current.beeper` wholesale and silently
// wipe out a legacy hand-edited token that `resolveBeeperToken` still falls
// back to (#31's own credential lives in Postgres, out of reach of this
// route entirely).
carryOver('beeper', 'token');
carryOver('beeper', 'tokenExpiresAt');
return next;
};
// `federation` is the one top-level slice with more than one owning surface:
// Settings → Sharing writes `mediaProvider` and `strictPullAuthorization`, while
// Instances → Unattended render routing writes `mediaRouting`. The generic
// top-level shallow merge replaces the slice wholesale, so whichever PUT lands
// second silently reverts the other surface's freshly saved sub-key (#4703).
// Merging per sub-key here removes that class instead of narrowing it — and
// because `updateSettingsWith` runs inside the settings write queue, `current`
// is always the freshest persisted snapshot, not the one the client read.
//
// A SHALLOW per-sub-key merge is deliberately enough: every sub-key today has
// exactly one owning surface, so an incoming sub-key is a complete value for it.
// "Absent vs present-but-empty" falls straight out of the spread — an omitted
// sub-key keeps the stored value, while one sent as `{}` or `null` applies the
// clear the user actually asked for. A FUTURE sub-key written by two surfaces
// would need its own deeper merge added here.
const mergeFederationSlice = (next, current) => {
if (!isPlainObject(next.federation) || !isPlainObject(current?.federation)) return next;
next.federation = { ...current.federation, ...next.federation };
return next;
};
// The backup slice is stored sparsely, so every response projects the EFFECTIVE
// schedule (`server/lib/backupConfig.js`) over the stored values. Without this the
// Settings screen had to guess what an omitted `enabled`/`cronExpression` meant,
// guessed the opposite of the scheduler, and then saved its guess back — silently
// cancelling a destination-only install's nightly backup (#6632). The stored keys
// stay sparse on disk; only the transport carries the resolved view.
const projectEffectiveBackup = (safe) => {
const effective = resolveBackupConfig(safe.backup);
return {
...safe,
backup: {
...safe.backup,
destPath: effective.destPath,
enabled: effective.enabled,
cronExpression: effective.cronExpression,
retentionCount: effective.retentionCount
}
};
};
// Same reasoning for the auto-update slice: an install that only ticked the
// checkbox stores `{ enabled: true }`, and the Update tab would otherwise have to
// re-derive what an omitted channel/interval means — the mistake #6632 made for
// the backup schedule. The resolver is the scheduler's own.
const projectEffectiveAutoUpdate = (safe) => ({
...safe,
autoUpdate: { ...safe.autoUpdate, ...storableAutoUpdateConfig(safe.autoUpdate) },
});
// Single sanitizer every settings response (GET load + PUT save) runs through,
// so a leak can't reappear on one path after being closed on the other: strip
// the top-level `secrets` hierarchy, redact external tokens (#1821), decorate
// server-authoritative bounds, then resolve the sparse backup schedule.
const sanitizeSettingsForResponse = (settings) => {
const { secrets, ...safe } = settings;
return projectEffectiveAutoUpdate(projectEffectiveBackup(decorateBounds(redactExternalTokens(safe))));
};
// GET /api/settings
router.get('/', asyncHandler(async (req, res) => {
const settings = await getSettings();
res.json(sanitizeSettingsForResponse(settings));
}));
// GET /api/settings/media-share-candidates
// The local image/video models this instance COULD share as a federated media
// provider, so the Sharing tab can offer them. The peer-facing status endpoint
// can't answer this: it only ever describes already-allowlisted models, which
// is the chicken-and-egg that left imageModels/videoModels unconfigurable.
// Deliberately local-only (this is unshared local model inventory, which no
// peer should read) — it lives here, behind the normal /api/* auth gate,
// rather than on /api/federation/media/v1.
router.get('/media-share-candidates', asyncHandler(async (_req, res) => {
const { listLocalMediaShareCandidates } = await import('../services/federatedMediaProvider.js');
res.json(await listLocalMediaShareCandidates());
}));
// GET /api/settings/ai-assignments
router.get('/ai-assignments', asyncHandler(async (_req, res) => {
res.json(await getAiAssignments());
}));
// GET /api/settings/features
router.get('/features', asyncHandler(async (_req, res) => {
res.json(await getInstanceFeatures());
}));
// GET /api/settings/credentials
// Presence + source only. Supported integrations have a separate write-only setter.
router.get('/credentials', asyncHandler(async (_req, res) => {
res.json(await getCredentialInventory());
}));
// Write-only, allowlisted integration credentials; no generic secrets access.
router.put('/credentials/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privateCredentialParamsSchema, req.params);
const { value } = validateRequest(privateCredentialInputSchema, req.body);
const entry = PRIVATE_CREDENTIALS.find(item => item.id === id);
await updateSettingsWith(current => {
putCredential(current, entry, value);
return current;
});
const inventory = await getCredentialInventory();
res.json(inventory.credentials.find(item => item.id === id));
}));
// POST /api/settings/features/eidoverse/install
// Explicit consent boundary: no Eidoverse checkout or dependency install occurs
// until the user presses Install in Settings > Features.
router.post('/features/eidoverse/install', asyncHandler(async (req, res) => {
const { worldsRepoUrl, worldsBranch } = validateRequest(eidoverseRepoSchema, req.body || {});
const normalizedRepoUrl = await updateEidoverseWorldsRepo(worldsRepoUrl, worldsBranch);
await installEidoverse({ worldsRepoUrl: normalizedRepoUrl, ...(worldsBranch !== undefined ? { worldsBranch } : {}) });
res.status(201).json(await updateInstanceFeature('eidoverse', true));
}));
// PUT /api/settings/features/eidoverse/source
// Update the origin and optional runtime branch in place. Branch switches
// require a clean checkout; future app updates honor the selected branch.
router.put('/features/eidoverse/source', asyncHandler(async (req, res) => {
const { worldsRepoUrl, worldsBranch } = validateRequest(eidoverseRepoSchema, req.body || {});
await updateEidoverseWorldsSource(worldsRepoUrl, worldsBranch);
res.json(await getInstanceFeatures());
}));
// POST /api/settings/features/eidoverse/host
// Lazily opens PortOS's TLS/WebSocket bridge. The external runtime stays a
// separately managed app; this listener only makes its existing web UI safe to
// embed when PortOS itself was opened over HTTPS.
router.post('/features/eidoverse/host', asyncHandler(async (_req, res) => {
await assertConfiguredEidoverseInstalled();
res.json(await ensureEidoverseHost());
}));
// The Beeper sweep scheduler and its realtime transport arm on the instance
// feature plus a stored token, and that gate used to be read at boot only — so
// turning the feature on left realtime down and no sweep registered until the
// next restart (fork issue #1, final live pass). Reconciling here closes that
// half; the credential paths close the other. Beeper sits in the `comms` group,
// so the group toggle moves the same gate — and so does the general settings
// PUT below, when it flips the user's own `settings.beeper.enabled` sync
// toggle: that save used to persist silently and never reach
// `startBeeperScheduler()` until a restart.
//
// Imported lazily inside the handler: a feature toggle is a rare path, and the
// arming module reaches the whole Beeper service graph (`ws` included), which
// has no business loading with every settings request.
const BEEPER_FEATURE_GROUP = 'comms';
async function reconcileBeeperArming(reason, options = {}) {
const { reconcileBeeperIngestion } = await import('../services/beeperArming.js');
// The flag is already persisted, so a reconcile failure must not turn a saved
// toggle into a 500.
await reconcileBeeperIngestion({ reason, ...options })
.catch((err) => console.error(`❌ Beeper ingestion reconcile (${reason}) failed: ${err.message}`));
}
// The iTerm2 bridge connects only while its feature is on (#8114): turning it
// off must drop the connection now, and turning it on must serve an already-
// open iTerm2 view without a restart. Same persisted-flag rule as above.
async function reconcileItermOnToggle() {
const { reconcileItermBridge } = await import('../services/itermBridge.js');
await reconcileItermBridge({ reason: 'feature-toggle' })
.catch((err) => console.error(`❌ iTerm2 bridge reconcile (feature-toggle) failed: ${err.message}`));
}
// Docker containment owns a shared egress network and per-run containers,
// networks and volumes (#12844): turning it on verifies the engine and sweeps
// orphans, turning it off cancels live runs and removes everything — now, not
// at the next restart. Same persisted-flag rule as above.
async function reconcileDockerContainmentOnToggle(result) {
const enabled = result.features.find((feature) => feature.id === 'docker-containment')?.enabled === true;
const { reconcileDockerContainment } = await import('../services/dockerContainment.js');
await reconcileDockerContainment({ enabled, reason: 'feature-toggle' })
.catch((err) => console.error(`❌ Docker containment reconcile (feature-toggle) failed: ${err.message}`));
}
// An interval-only Beeper save (no `enabled` flip) used to take effect only
// at the next process restart: the registered event's `intervalMs` is read
// once, at `schedule()` time (`createSettingsGatedSyncScheduler.js`), and
// `startBeeperScheduler()` deliberately no-ops once `beeper-sync` is already
// registered (fork issue #79). `restartBeeperScheduler()` is the fix — cancel
// and register fresh, which reads `getBeeperSyncConfig()` again and picks up
// whatever interval was just persisted. Lazily imported for the same reason
// `reconcileBeeperArming` above is: this is a rare save, and the scheduler
// module reaches the whole Beeper service graph.
async function restartBeeperSchedulerForIntervalChange(reason) {
const { restartBeeperScheduler } = await import('../services/beeperScheduler.js');
await restartBeeperScheduler()
.catch((err) => console.error(`❌ Beeper scheduler restart (${reason}) failed: ${err.message}`));
}
// PUT /api/settings/features/:featureId
// `enabled` is nullable: null clears a grouped feature's override back to
// "inherit" (see instanceFeatureUpdateSchema and updateInstanceFeature).
router.put('/features/:featureId', asyncHandler(async (req, res) => {
const featureId = validateRequest(instanceFeatureIdSchema, req.params.featureId);
const { enabled } = validateRequest(instanceFeatureUpdateSchema, req.body || {});
const result = await updateInstanceFeature(featureId, enabled);
if (featureId === 'beeper') await reconcileBeeperArming('feature-toggle');
if (featureId === 'iterm') await reconcileItermOnToggle();
if (featureId === 'docker-containment') await reconcileDockerContainmentOnToggle(result);
res.json(result);
}));
// PUT /api/settings/features/groups/:groupId (#40)
router.put('/features/groups/:groupId', asyncHandler(async (req, res) => {
const groupId = validateRequest(instanceFeatureGroupIdSchema, req.params.groupId);
const { enabled } = validateRequest(instanceFeatureGroupUpdateSchema, req.body || {});
const result = await updateInstanceFeatureGroup(groupId, enabled);
if (groupId === BEEPER_FEATURE_GROUP) await reconcileBeeperArming('feature-group-toggle');
res.json(result);
}));
// PUT /api/settings/ai-assignments/:id
router.put('/ai-assignments/:id', asyncHandler(async (req, res) => {
// These facades replace execution policy, steer scheduled social posts, or
// retarget the scheduled Brain digest (the PUT /api/brain/settings check).
// Check the decoded identifier so encoded route params cannot bypass the gate.
if (req.params.id === 'settings.autofixer' || req.params.id === 'brain.default'
|| req.params.id.startsWith('socialAgent.')) assertHostControl(req);
const payload = validateRequest(aiAssignmentUpdateSchema, req.body || {});
res.json(await updateAiAssignment(req.params.id, payload));
}));
// GET /api/settings/orchestration-profiles
router.get('/orchestration-profiles', asyncHandler(async (_req, res) => {
const { getOrchestrationProfiles } = await import('../services/orchestrationProfiles.js');
res.json(await getOrchestrationProfiles());
}));
// POST /api/settings/orchestration-profiles
router.post('/orchestration-profiles', asyncHandler(async (req, res) => {
const { saveOrchestrationProfile } = await import('../services/orchestrationProfiles.js');
const payload = validateRequest(namedOrchestrationProfileSchema, req.body || {});
const saved = await saveOrchestrationProfile(payload);
res.status(201).json(saved);
}));
// PUT /api/settings/orchestration-profiles/:id
router.put('/orchestration-profiles/:id', asyncHandler(async (req, res) => {
const { updateOrchestrationProfile } = await import('../services/orchestrationProfiles.js');
const payload = validateRequest(namedOrchestrationProfileSchema.partial(), req.body || {});
const updated = await updateOrchestrationProfile(req.params.id, payload);
res.json(updated);
}));
// DELETE /api/settings/orchestration-profiles/:id
router.delete('/orchestration-profiles/:id', asyncHandler(async (req, res) => {
const { deleteOrchestrationProfile } = await import('../services/orchestrationProfiles.js');
const result = await deleteOrchestrationProfile(req.params.id);
res.json(result);
}));
// Shared validation keeps PATCH and legacy PUT on the same configuration contracts.
const validateSettingsPatch = async (body) => {
if (body?.orchestrationProfiles !== undefined) {
validateRequest(orchestrationProfilesSettingsSchema, body.orchestrationProfiles);
}
// Settings is a polymorphic store but the backup sub-object has a known
// schema. Validate that slice when it's present so a malformed Backup-tab
// save doesn't reach disk (the runtime guards downstream are belt-and-
// suspenders, but per project convention all inputs are validated).
if (body?.filmLookPresets !== undefined) {
validateRequest(filmLookSavedPresetsSchema, body.filmLookPresets);
}
if (body?.untrustedContent !== undefined) {
validateRequest(untrustedContentSettingsSchema, body.untrustedContent);
}
// Per-harness enablement and the credential-bootstrap app table (#7564):
// both are read at composite-provider resolve time, so a malformed entry
// would surface as a run that cannot spawn rather than a 400 here.
if (body?.harnesses !== undefined) {
validateRequest(harnessSettingsSchema, body.harnesses);
}
if (body?.credentialBootstraps !== undefined) {
validateRequest(credentialBootstrapsSettingsSchema, body.credentialBootstraps);
}
if (body?.backup !== undefined) {
validateRequest(backupConfigSchema.partial(), body.backup);
}
if (body?.autoUpdate !== undefined) {
validateRequest(autoUpdateSettingsSchema, body.autoUpdate);
}
if (body?.sharingDisplayName !== undefined || body?.sharingBio !== undefined) {
validateRequest(sharingSettingsPatchSchema.partial(), {
sharingDisplayName: body.sharingDisplayName,
sharingBio: body.sharingBio,
});
}
// Per-feature AI provider assignments — validate each slice when present so
// a malformed picker save can't write a non-string providerId/model to disk.
if (body?.autofixer !== undefined) {
validateRequest(autofixerSettingsSchema.partial(), body.autofixer);
}
if (body?.calendarSync !== undefined) {
validateRequest(featureProviderConfigSchema.partial(), body.calendarSync);
}
if (body?.codeReview !== undefined) {
validateRequest(codeReviewSettingsSchema.partial(), body.codeReview);
}
// Creative Director's treatment, plan, and scene-evaluation provider/model
// pins — validate the slice when present so a malformed picker save can't
// write a bad provider config.
if (body?.creativeDirector !== undefined) {
validateRequest(creativeDirectorSettingsSchema.partial(), body.creativeDirector);
}
// Music studio slice (#2911) — the chiptune provider pin + publish prefs.
if (body?.music !== undefined) {
validateRequest(musicSettingsSchema.partial(), body.music);
}
if (body?.federation !== undefined) {
validateRequest(federationSettingsSchema, body.federation);
// The schema only proves a route is well-SHAPED. A route naming a peer that
// is unknown, switched off, not a media provider, not allowlisted for that
// model, or outside the tailnet is well-shaped and permanently unusable —
// and unattended work has no human at the moment it fails, so it would just
// break every future Creative Director / Commission render in silence.
// Refuse it here, where there IS a human. See routingPolicy.js.
await assertMediaRoutingConfig(body.federation.mediaRouting);
}
// Home location ({ lat, lon }) read by the weather_now voice tool. The schema
// already makes both fields optional + nullable (clearing falls back to the
// tool default), and the refine enforces both-or-neither — so validate the
// whole slice rather than .partial()ing away that pairing rule.
if (body?.location !== undefined) {
validateRequest(locationSettingsSchema, body.location);
}
if (body?.networkSetupPreference !== undefined) {
validateRequest(networkSetupPreferenceSchema, body.networkSetupPreference);
}
if (body?.hideFirstRunCard !== undefined) {
validateRequest(hideFirstRunCardSchema, body.hideFirstRunCard);
}
if (body?.embeddings !== undefined) {
validateRequest(settingsEmbeddingsSchema.partial(), body.embeddings);
}
if (body?.localLlm !== undefined) {
validateRequest(localLlmSettingsSchema, body.localLlm);
}
// iMessage ingestion config (#2151) — validate the slice when present so a
// malformed enabled/interval can't reach disk and break the sync scheduler.
if (body?.imessage !== undefined) {
validateRequest(imessageConfigSchema.partial(), body.imessage);
}
// Signal ingestion config (#2154) — validate the slice when present so a
// malformed enabled/interval can't reach disk and break the sync scheduler.
if (body?.signal !== undefined) {
validateRequest(signalConfigSchema.partial(), body.signal);
}
// Beeper Desktop bridge ingestion + connection config (#30) — validate the
// slice when present so a malformed enabled/interval/baseUrl/budget can't
// reach disk. `beeperSettingsSchema` is `.strict()` and deliberately has no
// `token`/`tokenExpiresAt` field, so a client attempting to smuggle a token
// through this generic route 400s instead of it silently reaching disk —
// the credential's own write path is POST/DELETE /api/beeper/token (#31),
// which stores it AES-256-GCM encrypted in Postgres. Used directly, NOT
// `.partial()`: every field is already individually `.optional()` (so
// `.partial()` was a no-op), and the schema's `superRefine` (SEC-2's
// loopback-only `baseUrl` gate) returns a `ZodEffects`, which has no
// `.partial()` method at all.
if (body?.beeperSavedScopes !== undefined) {
validateRequest(beeperSavedScopesSchema, body.beeperSavedScopes);
}
if (body?.beeper !== undefined) {
validateRequest(beeperSettingsSchema, body.beeper);
}
// Spotify ingestion config (#2152) — validate the slice when present so a
// malformed enabled/interval can't reach disk and break the sync scheduler.
if (body?.spotify !== undefined) {
validateRequest(spotifyConfigSchema.partial(), body.spotify);
}
// YouTube watch-history scrape config (#2153) — validate the slice when present
// so a malformed enabled/interval can't reach disk and break the sync scheduler.
if (body?.youtube !== undefined) {
validateRequest(youtubeConfigSchema.partial(), body.youtube);
}
// LoRA training config (caption provider + training defaults) — validate
// the slice when present so a malformed save can't write bad bounds the
// trainer would then pass to the python child.
if (body?.loraTraining !== undefined) {
validateRequest(loraTrainingConfigSchema.partial(), body.loraTraining);
}
// Per-API external-access flags (voice/sdapi). Validate the slice when present
// so a malformed toggle save can't write a non-boolean exposed/requireAuth to
// disk (the registry would then silently treat it as its default).
if (body?.apiAccess !== undefined) {
validateRequest(apiAccessSettingsSchema.partial(), body.apiAccess);
}
if (body?.dockerContainment !== undefined) {
validateRequest(dockerContainmentSettingsSchema, body.dockerContainment);
}
if (body?.instanceFeatures !== undefined) {
validateRequest(instanceFeatureSettingsSchema, body.instanceFeatures);
}
// Instance feature GROUP participation (#40) — same shape guard as the
// per-feature slice above, keyed on the separate group id list.
if (body?.instanceFeatureGroups !== undefined) {
validateRequest(instanceFeatureGroupSettingsSchema, body.instanceFeatureGroups);
}
// Local MCP agent-context opt-in. Validate the whole strict slice so an
// unknown scope/profile cannot silently broaden what the server exposes.
if (body?.agentContext !== undefined) {
validateRequest(agentContextSettingsSchema, body.agentContext);
}
// Editorial-check enable/config slice (#1284) — validate when present so a
// malformed save can't write a non-boolean enabled / non-object config the
// registry would then choke on.
if (body?.pipelineEditorialChecks !== undefined) {
validateRequest(pipelineEditorialChecksSettingsSchema.partial(), body.pipelineEditorialChecks);
}
// Privacy Center opt-out recheck config (#2145) — validate the slice when
// present so a malformed cron / non-boolean autonomy toggle can't reach disk
// and break the recheck scheduler. Both autonomy toggles default OFF.
if (body?.privacy !== undefined) {
validateRequest(privacySettingsSchema.partial(), body.privacy);
}
// Scheduled Series Autopilot config (#2174) — validate the slice when present
// so an invalid cron (rejected by the schema's isValidCronExpression refine) or
// bad seriesId can't reach disk and leave an "enabled" schedule that never fires.
// `.partial()` so a PUT that only carries { schedules } still validates.
if (body?.seriesAutopilot !== undefined) {
validateRequest(seriesAutopilotSettingsSchema.partial(), body.seriesAutopilot);
}
// Grok Imagegen settings slice (#2859) — validate when present so a malformed
// save can't write a bad aspect ratio (which lands verbatim in the grok
// prompt) or a non-boolean enabled gate to disk. The imageGen parent stays
// polymorphic; only the grok sub-slice has a schema here.
if (body?.imageGen?.grok !== undefined) {
validateRequest(imageGenGrokSettingsSchema.partial(), body.imageGen.grok);
}
if (body?.imageGen?.agy !== undefined) {
validateRequest(imageGenAgySettingsSchema.partial(), body.imageGen.agy);
}
if (body?.imageGen?.runway !== undefined) {
validateRequest(imageGenRunwaySettingsSchema.partial(), body.imageGen.runway);
}
if (body?.imageGen?.fal !== undefined) {
validateRequest(imageGenFalSettingsSchema.partial(), body.imageGen.fal);
}
// Every local media lane spawns this interpreter (and image gen spawns the
// `mflux-generate` beside it), so hold it to the guard the setup routes use:
// a python basename, never an arbitrary binary (#8751). A cleared value
// (`''`/`null`) falls back to interpreter discovery, so it stays allowed.
const localPython = body?.imageGen?.local?.pythonPath;
if (localPython != null && localPython !== '' && !isAllowedPython(localPython)) {
throw new ServerError('imageGen.local.pythonPath must be a python interpreter (basename python/python3/python3.NN)', {
status: 400, code: 'INVALID_PYTHON_PATH',
});
}
// Per-surface render defaults (#3231) — validate when present so a typo'd
// target key or a non-enum backend can't persist a slice the render-target
// resolver would then silently ignore (or worse, hand an invalid model id
// to a cloud CLI's argv).
if (body?.renderDefaults !== undefined) {
validateRequest(renderDefaultsSettingsSchema, body.renderDefaults);
}
// Install-wide video render pin (#3231 Phase 4) — validate when present so a
// non-enum backend can't persist a mode resolveVideoMode would choke on.
if (body?.videoGen !== undefined) {
validateRequest(videoGenSettingsSchema, body.videoGen);
}
// Install-level Layered Intelligence settings (#2515) — validate the slice when
// present so a malformed `trustShellSources` can't persist and silently unlock
// full-shell custom `cmd` sources install-wide.
if (body.layeredIntelligence) {
validateRequest(layeredIntelligenceSettingsSchema.partial(), body.layeredIntelligence);
}
// Subscription plan prices — the same schema PUT /api/usage/subscriptions
// enforces, so a legacy client or restore bundle can't write a junk family
// key or an over-cap price through the generic settings endpoint. Without it
// the value persists, reads back as "not priced", and is silently deleted by
// the next save from the usage page.
if (body?.subscriptionCosts !== undefined) {
validateRequest(subscriptionCostsMapSchema, body.subscriptionCosts);
}
// Plan tiers ride the same rails as the prices beside them, for the same
// reason: an unvalidated key here would persist, read back as "no tier", and
// be dropped by the next save from the Subscriptions page.
if (body?.subscriptionPlanTiers !== undefined) {
validateRequest(subscriptionPlanTiersMapSchema, body.subscriptionPlanTiers);
}
// Same schema PUT /api/usage/fleet-billing's store uses, so a restore dump
// can't write an unbounded or non-string list through the generic endpoint.
if (body?.usageApiBilledInstanceIds !== undefined) {
validateRequest(usageApiBilledInstanceIdsSchema, body.usageApiBilledInstanceIds);
}
};
const saveSettingsPatch = async (body, slicePatch) => {
// User-defined catalog types moved out of settings.json into PostgreSQL
// (`catalog_user_types`, #1001). The `/api/catalog/types` routes are the only
// write path; a `catalogUserTypes` key in a PUT /api/settings body (legacy
// client, restore bundle) is stripped below alongside `secrets` so it can't
// write a dead, unread slice back into settings.json (which the boot import
// would then re-import and rename aside on the next restart, churning state).
// Strip `secrets` from the incoming PUT body so an authenticated session
// (or stolen cookie) can't disable the auth gate or clobber other secrets
// by sending `{ "secrets": { ... } }` directly to /api/settings — that
// would bypass the current-password proof the /api/auth/password routes
// require. Secrets are write-only through their dedicated routes
// (/api/auth/password, /api/github/secrets, etc.).
// subscriptionCosts, subscriptionPlanTiers and usageApiBilledInstanceIds are
// excluded from the generic shallow spread below and routed through their
// dedicated savers — the same merge PUT /api/usage/subscriptions and PUT
// /api/usage/fleet-billing use — so a restore dump cannot persist an
// unvalidated slice, and a shallow `{ ...current, ...settingsPatch }` cannot
// replace a map by dropping keys the incoming patch did not mention.
const {
secrets: _ignoredSecrets,
passwordRiskRevision: _ignoredPasswordRiskRevision,
catalogUserTypes: _ignoredTypes,
subscriptionCosts: subscriptionCostsPatch,
subscriptionPlanTiers: subscriptionPlanTiersPatch,
usageApiBilledInstanceIds: apiBilledPatch,
...initialSettingsPatch
} = body || {};
// updateSettingsWith (not updateSettings) so the multi-owner `federation`
// slice merges per sub-key and persisted write-only tokens the incoming patch
// omits get re-injected — both against the freshest snapshot inside the write
// queue (see mergeFederationSlice / preserveExternallyOwnedKeys).
// `actor: 'user'` is what separates a save made HERE — a human on the Settings
// page — from every other `save()` caller (schedulers, sync hooks, feature
// writes), which keep the `'system'` default in the operator-action ledger (#5594).
let settingsPatch = initialSettingsPatch;
let previousBeeperEnabled;
let previousBeeperIntervalMinutes;
let previousBeeperConnection;
let previousBeeperGates;
let merged = await updateSettingsWith(async (current) => {
// Read inside the queue, against the freshest persisted snapshot (same
// reasoning as `mergeFederationSlice` above) — a stale pre-image here could
// read a no-op as a flip, or a real flip as a no-op.
if (slicePatch) {
const { slicePath, partial } = slicePatch;
const [root, child] = slicePath.split('.');
const parent = isPlainObject(current[root]) ? current[root] : {};
const existing = child ? parent[child] : current[root];
// Shallow merge at exactly the selected slice: objects/arrays/null supplied
// as values replace that key, including explicit clearing.
const updated = { ...(isPlainObject(existing) ? existing : {}), ...partial };
settingsPatch = { [root]: child ? { ...parent, [child]: updated } : updated };
await validateSettingsPatch(settingsPatch);
}
previousBeeperEnabled = current?.beeper?.enabled === true;
previousBeeperIntervalMinutes = current?.beeper?.intervalMinutes;
previousBeeperConnection = JSON.stringify([current?.beeper?.baseUrl, current?.beeper?.allowNonLoopbackBaseUrl]);
previousBeeperGates = JSON.stringify([current?.instanceFeatures?.beeper, current?.instanceFeatureGroups?.comms]);
// Provider picker and promotion controls save independent keys in this
// slice. Merge while holding the settings write queue to retain both.
const next = { ...current, ...settingsPatch };
if (settingsPatch.autofixer !== undefined) {
next.autofixer = { ...current.autofixer, ...settingsPatch.autofixer };
}
return preserveExternallyOwnedKeys(
mergeFederationSlice(next, current),
current,
);
}, { actor: 'user' });
if (settingsPatch.instanceFeatures?.eidoverse !== undefined) {
const { reconcileEidoverseRuntime } = await import('../services/eidoverseRuntime.js');
await reconcileEidoverseRuntime()
.catch((err) => console.error(`⚠️ Eidoverse startup deferred: ${err.message}`));
}
// A beeper save that flips `enabled` never armed the scheduler until a
// restart. `startBeeperScheduler()` is the only thing that registers the
// sweep, and it's reached exclusively through `reconcileBeeperArming` —
// which the feature and comms-group toggles call, but this generic PUT path
// never did. `undefined` counts as `false` on both sides, matching how
// `getBeeperSyncConfig()` reads the stored flag, so an install that has
// never touched the Beeper card doesn't read as a flip. Fires AFTER the
// write above so the reconcile (and the scheduler's own re-read) see the
// value that was actually persisted, not the request body.
const nextBeeperEnabled = merged?.beeper?.enabled === true;
const beeperIntervalChanged = merged?.beeper?.intervalMinutes !== previousBeeperIntervalMinutes;
if (nextBeeperEnabled !== previousBeeperEnabled) {
// Fork issue #94: the flip branch does NOT always get a fresh
// registration. `reconcileBeeperArming` only registers the scheduler when
// it is not already registered (fork issue #79's re-registration guard in
// beeperArming.js), and a true→false save deliberately leaves the
// scheduler registered — it just gates per tick (see the true→false test
// beside this route's other Beeper tests) — so a false→true flip right
// after finds it already registered and the reconcile below is a no-op
// for the scheduler. Capture that "already registered" state BEFORE
// reconciling: if this save also changed the interval, the still-
// registered event is holding the stale `intervalMs`
// `createSettingsGatedSyncScheduler.js` locked in at `schedule()` time, so
// restart explicitly to pick up what was just persisted.
const { isBeeperSchedulerRegistered } = await import('../services/beeperScheduler.js');
const wasSchedulerRegisteredBeforeReconcile = isBeeperSchedulerRegistered();
await reconcileBeeperArming('sync-toggle');
if (nextBeeperEnabled && beeperIntervalChanged && wasSchedulerRegisteredBeforeReconcile) {
await restartBeeperSchedulerForIntervalChange('sync-toggle-interval-change');
}
} else if (beeperIntervalChanged) {
// Fork issue #79: an interval-only change (no `enabled` flip) still has to
// take effect without a restart.
await restartBeeperSchedulerForIntervalChange('interval-change');
}
const beeperConnectionChanged = JSON.stringify([merged?.beeper?.baseUrl, merged?.beeper?.allowNonLoopbackBaseUrl]) !== previousBeeperConnection;
const beeperGatesChanged = JSON.stringify([merged?.instanceFeatures?.beeper, merged?.instanceFeatureGroups?.comms]) !== previousBeeperGates;
if (beeperConnectionChanged || beeperGatesChanged) {
await reconcileBeeperArming('connection-settings', { restartSocket: beeperConnectionChanged });
}
if (subscriptionCostsPatch !== undefined) {
const costs = await saveSubscriptionCosts(subscriptionCostsPatch, { actor: 'user' });
merged = { ...merged, subscriptionCosts: costs };
}
if (subscriptionPlanTiersPatch !== undefined) {
const tiers = await savePlanTiers(subscriptionPlanTiersPatch, { actor: 'user' });
merged = { ...merged, subscriptionPlanTiers: tiers };
}
if (apiBilledPatch !== undefined) {
const ids = await saveApiBilledInstanceIds(apiBilledPatch, { actor: 'user' });
merged = { ...merged, usageApiBilledInstanceIds: ids };
}
// The queue caches codex.parallelLimit in-process; sync it from the
// merged value so a save takes effect without a restart and without
// re-reading the file.
setCodexParallelLimit(merged.imageGen?.codex?.parallelLimit ?? CODEX_PARALLEL_DEFAULT);
// Series Autopilot crons re-register themselves off settings.js's
// `settings:updated` event (see seriesAutopilotScheduler.js) — the save above
// already emitted it — so an added/removed/edited schedule takes effect
// immediately without a restart, and this route stays decoupled from the
// autopilot pipeline graph.
if (settingsPatch.untrustedContent !== undefined) {
const { clearPendingMergeAssessmentHolds } = await import('../services/prWatcher.js');
await clearPendingMergeAssessmentHolds()
.catch((err) => console.error(`❌ Could not re-arm pending-merge assessments after a policy save: ${err.message}`));
}
return sanitizeSettingsForResponse(merged);
};
// PUT remains a top-level replacement contract for whole-form and older callers.
router.put('/', asyncHandler(async (req, res) => {
await validateSettingsPatch(req.body);
res.json(await saveSettingsPatch(req.body));
}));
router.patch('/slice', asyncHandler(async (req, res) => {
const patch = validateRequest(settingsSlicePatchSchema, req.body);
res.json(await saveSettingsPatch({}, patch));
}));
export default router;