feat(admin): add authenticated settings API endpoints

.changeset/admin-settings-api.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+feat: add authenticated admin settings API endpoints

src/controllers/admin/get-settings-controller.ts

@@ -0,0 +1,17 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { Settings } from '../../@types/settings'
+import { loadDefaults, loadMergedSettings, filterSettingsAgainstDefaults } from '../../utils/settings-config'
+import { redactSettingsSecrets } from '../../utils/settings-redaction'
+
+export class GetAdminSettingsController implements IController {
+  public async handleRequest(_request: Request, response: Response): Promise<void> {
+    const merged = loadMergedSettings()
+    const defaults = loadDefaults()
+    const filtered = filterSettingsAgainstDefaults(merged, defaults) as Settings
+    const settings = redactSettingsSecrets(filtered)
+
+    response.status(200).setHeader('content-type', 'application/json').send({ settings })
+  }
+}

src/controllers/admin/get-settings-schema-controller.ts

@@ -0,0 +1,10 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { guidedSettingCategories } from '../../utils/settings-guided-schema'
+
+export class GetAdminSettingsSchemaController implements IController {
+  public async handleRequest(_request: Request, response: Response): Promise<void> {
+    response.status(200).setHeader('content-type', 'application/json').send({ categories: guidedSettingCategories })
+  }
+}

src/controllers/admin/patch-settings-controller.ts

@@ -0,0 +1,76 @@
+import { Request, Response } from 'express'
+
+import { Settings } from '../../@types/settings'
+import { IController } from '../../@types/controllers'
+import { adminSettingsPatchBodySchema } from '../../schemas/admin-settings-schema'
+import {
+  getByPath,
+  loadMergedSettings,
+  loadUserSettings,
+  saveSettings,
+  setByPath,
+  validatePathAgainstDefaults,
+  validateSettings,
+} from '../../utils/settings-config'
+import {
+  isWriteProtectedSettingsPath,
+  redactSettingsValue,
+} from '../../utils/settings-redaction'
+import { validateSchema } from '../../utils/validation'
+
+export class PatchAdminSettingsController implements IController {
+  public async handleRequest(request: Request, response: Response): Promise<void> {
+    const validation = validateSchema(adminSettingsPatchBodySchema)(request.body)
+    if (validation.error) {
+      response.status(400).setHeader('content-type', 'application/json').send({ error: 'Invalid request' })
+      return
+    }
+
+    const { path, value } = validation.value
+
+    if (isWriteProtectedSettingsPath(path)) {
+      response
+        .status(400)
+        .setHeader('content-type', 'application/json')
+        .send({
+          error: 'Validation failed',
+          issues: [{ path, message: 'Path is write-protected' }],
+        })
+      return
+    }
+
+    const pathIssues = validatePathAgainstDefaults(path)
+    if (pathIssues.length > 0) {
+      response
+        .status(400)
+        .setHeader('content-type', 'application/json')
+        .send({ error: 'Validation failed', issues: pathIssues })
+      return
+    }
+
+    const userSettings = loadUserSettings() as unknown as Record<string, unknown>
+    const nextUserSettings = setByPath(userSettings, path, value)
+
+    const merged = loadMergedSettings() as unknown as Record<string, unknown>
+    const mergedNext = setByPath(merged, path, getByPath(nextUserSettings, path))
+    const validationIssues = validateSettings(mergedNext as unknown as Settings)
+
+    if (validationIssues.length > 0) {
+      response
+        .status(400)
+        .setHeader('content-type', 'application/json')
+        .send({ error: 'Validation failed', issues: validationIssues })
+      return
+    }
+
+    saveSettings(nextUserSettings as unknown as Settings)
+
+    const updatedValue = redactSettingsValue(path, getByPath(nextUserSettings, path))
+
+    response.status(200).setHeader('content-type', 'application/json').send({
+      ok: true,
+      path,
+      value: updatedValue,
+    })
+  }
+}

src/controllers/admin/post-settings-validate-controller.ts

@@ -0,0 +1,17 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { loadMergedSettings, validateSettings } from '../../utils/settings-config'
+
+export class PostAdminSettingsValidateController implements IController {
+  public async handleRequest(_request: Request, response: Response): Promise<void> {
+    const issues = validateSettings(loadMergedSettings())
+
+    if (issues.length === 0) {
+      response.status(200).setHeader('content-type', 'application/json').send({ valid: true, issues: [] })
+      return
+    }
+
+    response.status(200).setHeader('content-type', 'application/json').send({ valid: false, issues })
+  }
+}

src/factories/controllers/get-admin-settings-controller-factory.ts

@@ -0,0 +1,6 @@
+import { GetAdminSettingsController } from '../../controllers/admin/get-settings-controller'
+import { IController } from '../../@types/controllers'
+
+export const createGetAdminSettingsController = (): IController => {
+  return new GetAdminSettingsController()
+}

src/factories/controllers/get-admin-settings-schema-controller-factory.ts

@@ -0,0 +1,6 @@
+import { GetAdminSettingsSchemaController } from '../../controllers/admin/get-settings-schema-controller'
+import { IController } from '../../@types/controllers'
+
+export const createGetAdminSettingsSchemaController = (): IController => {
+  return new GetAdminSettingsSchemaController()
+}

src/factories/controllers/patch-admin-settings-controller-factory.ts

@@ -0,0 +1,6 @@
+import { PatchAdminSettingsController } from '../../controllers/admin/patch-settings-controller'
+import { IController } from '../../@types/controllers'
+
+export const createPatchAdminSettingsController = (): IController => {
+  return new PatchAdminSettingsController()
+}

src/factories/controllers/post-admin-settings-validate-controller-factory.ts

@@ -0,0 +1,6 @@
+import { PostAdminSettingsValidateController } from '../../controllers/admin/post-settings-validate-controller'
+import { IController } from '../../@types/controllers'
+
+export const createPostAdminSettingsValidateController = (): IController => {
+  return new PostAdminSettingsValidateController()
+}

src/routes/admin/index.ts

@@ -3,8 +3,12 @@
 import { createGetAdminHealthController } from '../../factories/controllers/get-admin-health-controller-factory'
 import { createGetAdminMetricsController } from '../../factories/controllers/get-admin-metrics-controller-factory'
 import { createGetAdminSessionController } from '../../factories/controllers/get-admin-session-controller-factory'
+import { createGetAdminSettingsController } from '../../factories/controllers/get-admin-settings-controller-factory'
+import { createGetAdminSettingsSchemaController } from '../../factories/controllers/get-admin-settings-schema-controller-factory'
+import { createPatchAdminSettingsController } from '../../factories/controllers/patch-admin-settings-controller-factory'
 import { createPostAdminLoginController } from '../../factories/controllers/post-admin-login-controller-factory'
 import { createPostAdminLogoutController } from '../../factories/controllers/post-admin-logout-controller-factory'
+import { createPostAdminSettingsValidateController } from '../../factories/controllers/post-admin-settings-validate-controller-factory'
 import { adminAuthMiddleware } from '../../handlers/request-handlers/admin-auth-middleware'
 import { adminEnabledMiddleware } from '../../handlers/request-handlers/admin-enabled-middleware'
 import {
@@ -23,11 +27,25 @@
 router.use(adminEnabledMiddleware)
 router.use('/assets', express.static('./resources/admin/assets'))
 router.get('/', getAdminDashboardRequestHandler)
 router.get('/dashboard', getAdminDashboardRequestHandler)
 router.post('/login', adminLoginRateLimitMiddleware, json(), withAdminController(createPostAdminLoginController))
 router.post('/logout', adminRateLimitMiddleware, withAdminController(createPostAdminLogoutController))
 router.get('/session', adminRateLimitMiddleware, adminAuthMiddleware, withAdminController(createGetAdminSessionController))
 router.get('/health', adminRateLimitMiddleware, adminAuthMiddleware, withAdminController(createGetAdminHealthController))
 router.get('/metrics', adminRateLimitMiddleware, adminAuthMiddleware, withAdminController(createGetAdminMetricsController))
+router.get('/settings', adminRateLimitMiddleware, adminAuthMiddleware, withAdminController(createGetAdminSettingsController))
+router.get(
+  '/settings/schema',
+  adminRateLimitMiddleware,
+  adminAuthMiddleware,
+  withAdminController(createGetAdminSettingsSchemaController),
+)
+router.patch('/settings', adminRateLimitMiddleware, adminAuthMiddleware, json(), withAdminController(createPatchAdminSettingsController))
+router.post(
+  '/settings/validate',
+  adminRateLimitMiddleware,
+  adminAuthMiddleware,
+  withAdminController(createPostAdminSettingsValidateController),
+)
 
 export default router

src/schemas/admin-settings-schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const adminSettingsPatchBodySchema = z
+  .object({
+    path: z.string().min(1),
+    value: z.custom<unknown>((input) => input !== undefined, { message: 'value is required' }),
+  })
+  .strict()

src/utils/settings-config.ts

@@ -262,6 +262,10 @@ const pathExistsInSchema = (schema: unknown, tokens: PathToken[]): boolean => {
       return false
     }
 
+    if (current.length === 0) {
+      return true
+    }
+
     current = current[0]
   }
 
@@ -297,10 +301,58 @@ export const loadMergedSettings = (): Settings => {
   return mergeDeepRight(loadDefaults(), loadUserSettings()) as Settings
 }
 
+export const filterSettingsAgainstDefaults = (settings: unknown, defaults: unknown): unknown => {
+  if (Array.isArray(settings)) {
+    if (!Array.isArray(defaults)) {
+      return []
+    }
+    if (defaults.length === 0) {
+      return [...settings]
+    }
+
+    const itemSchema = defaults[0]
+    return settings.map((item) => filterSettingsAgainstDefaults(item, itemSchema))
+  }
+
+  if (isPlainObject(settings)) {
+    if (!isPlainObject(defaults)) {
+      return {}
+    }
+
+    const filtered: Record<string, unknown> = {}
+    for (const key of Object.keys(settings)) {
+      if (hasOwn(defaults, key) || key === 'passwordHash') {
+        // If it's a known non-schema key like passwordHash, we don't have a default schema for its children.
+        // We can pass {} to allow it to be preserved.
+        const defaultSubSchema = hasOwn(defaults, key)
+          ? (defaults as Record<string, unknown>)[key]
+          : {}
+
+        filtered[key] = filterSettingsAgainstDefaults(
+          (settings as Record<string, unknown>)[key],
+          defaultSubSchema
+        )
+      }
+    }
+    return filtered
+  }
+
+  return settings
+}
+
 export const saveSettings = (settings: Settings): void => {
   ensureSettingsExists()
   const serialized = yaml.dump(toSerializable(settings), { lineWidth: 120 })
-  fs.writeFileSync(getSettingsFilePath(), serialized, 'utf-8')
+  const settingsPath = getSettingsFilePath()
+  const backupPath = `${settingsPath}.${Date.now()}.bak`
+
+  if (fs.existsSync(settingsPath)) {
+    fs.copyFileSync(settingsPath, backupPath)
+  }
+
+  const tempPath = `${settingsPath}.${Date.now()}.tmp`
+  fs.writeFileSync(tempPath, serialized, 'utf-8')
+  fs.renameSync(tempPath, settingsPath)
 }
 
 export const getTopLevelSettingCategories = (): string[] => {

src/utils/settings-redaction.ts

@@ -0,0 +1,52 @@
+const SENSITIVE_SETTING_KEYS = new Set(['passwordHash', 'secret'])
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export const isSensitiveSettingsPath = (path: string): boolean => {
+  const segments = path.split('.')
+  const lastSegment = segments[segments.length - 1] ?? ''
+  const key = lastSegment.replace(/\[\d+\]$/, '')
+
+  return SENSITIVE_SETTING_KEYS.has(key)
+}
+
+export const isWriteProtectedSettingsPath = (path: string): boolean => {
+  return path === 'admin.passwordHash' || path.endsWith('.passwordHash')
+}
+
+export const redactSettingsValue = (path: string, value: unknown): unknown => {
+  if (isSensitiveSettingsPath(path) && typeof value === 'string' && value.length > 0) {
+    return '***'
+  }
+
+  return value
+}
+
+export const redactSettingsSecrets = <T>(settings: T): T => {
+  const redactWalk = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      return value.map(redactWalk)
+    }
+
+    if (!isPlainObject(value)) {
+      return value
+    }
+
+    const result: Record<string, unknown> = {}
+
+    for (const [key, entry] of Object.entries(value)) {
+      if (SENSITIVE_SETTING_KEYS.has(key) && typeof entry === 'string' && entry.length > 0) {
+        result[key] = '***'
+        continue
+      }
+
+      result[key] = redactWalk(entry)
+    }
+
+    return result
+  }
+
+  return redactWalk(settings) as T
+}

test/unit/app/maintenance-worker.spec.ts

@@ -10,6 +10,7 @@ import { Nip05Verification } from '../../../src/@types/nip05'
 import { IMaintenanceService, IPaymentsService } from '../../../src/@types/services'
 import { Settings } from '../../../src/@types/settings'
 import { applyReverificationOutcome, MaintenanceWorker } from '../../../src/app/maintenance-worker'
+import * as metricsTelemetry from '../../../src/telemetry/metrics'
 import * as misc from '../../../src/utils/misc'
 import * as nip05Utils from '../../../src/utils/nip05'
 
@@ -499,6 +500,8 @@ describe('MaintenanceWorker', () => {
 
   describe('onExit', () => {
     it('calls close and then exits the process with code 0', async () => {
+      sandbox.stub(metricsTelemetry, 'shutdownMetricsTelemetry').resolves()
+
       fakeProcess.emit('SIGTERM')
       await new Promise((resolve) => setImmediate(resolve))