+
Health
@@ -191,6 +192,39 @@
Charts
+
+
+
+ Configuration
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Select a category to edit guided settings.
+
+
+
+
diff --git a/src/controllers/admin/get-settings-backups-controller.ts b/src/controllers/admin/get-settings-backups-controller.ts
new file mode 100644
index 00000000..c56cca3c
--- /dev/null
+++ b/src/controllers/admin/get-settings-backups-controller.ts
@@ -0,0 +1,10 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { listSettingsBackups } from '../../utils/settings-config'
+
+export class GetAdminSettingsBackupsController implements IController {
+ public async handleRequest(_request: Request, response: Response): Promise
{
+ response.status(200).setHeader('content-type', 'application/json').send({ backups: listSettingsBackups() })
+ }
+}
diff --git a/src/controllers/admin/get-settings-controller.ts b/src/controllers/admin/get-settings-controller.ts
new file mode 100644
index 00000000..2684842d
--- /dev/null
+++ b/src/controllers/admin/get-settings-controller.ts
@@ -0,0 +1,13 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { loadMergedSettings } from '../../utils/settings-config'
+import { redactSettingsSecrets } from '../../utils/settings-redaction'
+
+export class GetAdminSettingsController implements IController {
+ public async handleRequest(_request: Request, response: Response): Promise {
+ const settings = redactSettingsSecrets(loadMergedSettings())
+
+ response.status(200).setHeader('content-type', 'application/json').send({ settings })
+ }
+}
diff --git a/src/controllers/admin/get-settings-schema-controller.ts b/src/controllers/admin/get-settings-schema-controller.ts
new file mode 100644
index 00000000..a12d7be0
--- /dev/null
+++ b/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 {
+ response.status(200).setHeader('content-type', 'application/json').send({ categories: guidedSettingCategories })
+ }
+}
diff --git a/src/controllers/admin/patch-settings-controller.ts b/src/controllers/admin/patch-settings-controller.ts
new file mode 100644
index 00000000..7914d3b8
--- /dev/null
+++ b/src/controllers/admin/patch-settings-controller.ts
@@ -0,0 +1,92 @@
+import { Request, Response } from 'express'
+
+import { Settings } from '../../@types/settings'
+import { IController } from '../../@types/controllers'
+import { adminSettingsPatchBodySchema } from '../../schemas/admin-settings-schema'
+import {
+ appendSettingsAuditLog,
+ 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 {
+ const validation = validateSchema(adminSettingsPatchBodySchema)(request.body)
+ if (validation.error) {
+ response.status(400).setHeader('content-type', 'application/json').send({ error: 'Invalid request' })
+ return
+ }
+
+ const changes = 'changes' in validation.value ? validation.value.changes : [validation.value]
+ const issues = changes.flatMap(({ path }) => {
+ if (isWriteProtectedSettingsPath(path)) {
+ return [{ path, message: 'Path is write-protected' }]
+ }
+
+ return validatePathAgainstDefaults(path)
+ })
+
+ if (issues.length > 0) {
+ response.status(400).setHeader('content-type', 'application/json').send({ error: 'Validation failed', issues })
+ return
+ }
+
+ const userSettings = loadUserSettings() as unknown as Record
+ const nextUserSettings = changes.reduce(
+ (settings, change) => setByPath(settings, change.path, change.value),
+ userSettings,
+ )
+ const merged = loadMergedSettings() as unknown as Record
+ const mergedNext = changes.reduce(
+ (settings, change) => setByPath(settings, change.path, getByPath(nextUserSettings, change.path)),
+ merged,
+ )
+ 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 updatedChanges = changes.map(({ path }) => ({
+ path,
+ value: redactSettingsValue(path, getByPath(nextUserSettings, path)),
+ reload: getSettingsReloadBehavior(path),
+ }))
+ appendSettingsAuditLog({
+ action: 'settings.updated',
+ changes: updatedChanges.map(({ path, reload }) => ({ path, reload })),
+ remoteAddress: request.ip,
+ })
+
+ if (changes.length === 1 && !('changes' in validation.value)) {
+ const [change] = updatedChanges
+ response.status(200).setHeader('content-type', 'application/json').send({ ok: true, ...change })
+ return
+ }
+
+ response.status(200).setHeader('content-type', 'application/json').send({ ok: true, changes: updatedChanges })
+ }
+}
+
+const getSettingsReloadBehavior = (path: string): 'hot-reload' | 'restart-required' => {
+ if (path.startsWith('workers.') || path.startsWith('payments') || path.startsWith('network.')) {
+ return 'restart-required'
+ }
+
+ return 'hot-reload'
+}
diff --git a/src/controllers/admin/post-settings-restore-controller.ts b/src/controllers/admin/post-settings-restore-controller.ts
new file mode 100644
index 00000000..aadcca09
--- /dev/null
+++ b/src/controllers/admin/post-settings-restore-controller.ts
@@ -0,0 +1,30 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { adminSettingsRestoreBodySchema } from '../../schemas/admin-settings-schema'
+import { appendSettingsAuditLog, restoreSettingsBackup } from '../../utils/settings-config'
+import { validateSchema } from '../../utils/validation'
+
+export class PostAdminSettingsRestoreController implements IController {
+ public async handleRequest(request: Request, response: Response): Promise {
+ const validation = validateSchema(adminSettingsRestoreBodySchema)(request.body)
+ if (validation.error) {
+ response.status(400).setHeader('content-type', 'application/json').send({ error: 'Invalid request' })
+ return
+ }
+
+ try {
+ restoreSettingsBackup(validation.value.filename)
+ appendSettingsAuditLog({
+ action: 'settings.restored',
+ filename: validation.value.filename,
+ remoteAddress: request.ip,
+ })
+
+ response.status(200).setHeader('content-type', 'application/json').send({ ok: true, filename: validation.value.filename })
+ } catch (error) {
+ const message = error instanceof Error ? error.message : 'Restore failed'
+ response.status(400).setHeader('content-type', 'application/json').send({ error: message })
+ }
+ }
+}
diff --git a/src/controllers/admin/post-settings-validate-controller.ts b/src/controllers/admin/post-settings-validate-controller.ts
new file mode 100644
index 00000000..3f486746
--- /dev/null
+++ b/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 {
+ 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 })
+ }
+}
diff --git a/src/factories/controllers/get-admin-settings-backups-controller-factory.ts b/src/factories/controllers/get-admin-settings-backups-controller-factory.ts
new file mode 100644
index 00000000..2471ccce
--- /dev/null
+++ b/src/factories/controllers/get-admin-settings-backups-controller-factory.ts
@@ -0,0 +1,6 @@
+import { GetAdminSettingsBackupsController } from '../../controllers/admin/get-settings-backups-controller'
+import { IController } from '../../@types/controllers'
+
+export const createGetAdminSettingsBackupsController = (): IController => {
+ return new GetAdminSettingsBackupsController()
+}
diff --git a/src/factories/controllers/get-admin-settings-controller-factory.ts b/src/factories/controllers/get-admin-settings-controller-factory.ts
new file mode 100644
index 00000000..344370f4
--- /dev/null
+++ b/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()
+}
diff --git a/src/factories/controllers/get-admin-settings-schema-controller-factory.ts b/src/factories/controllers/get-admin-settings-schema-controller-factory.ts
new file mode 100644
index 00000000..8bb1afd5
--- /dev/null
+++ b/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()
+}
diff --git a/src/factories/controllers/patch-admin-settings-controller-factory.ts b/src/factories/controllers/patch-admin-settings-controller-factory.ts
new file mode 100644
index 00000000..09838d5b
--- /dev/null
+++ b/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()
+}
diff --git a/src/factories/controllers/post-admin-settings-restore-controller-factory.ts b/src/factories/controllers/post-admin-settings-restore-controller-factory.ts
new file mode 100644
index 00000000..19fdb215
--- /dev/null
+++ b/src/factories/controllers/post-admin-settings-restore-controller-factory.ts
@@ -0,0 +1,6 @@
+import { PostAdminSettingsRestoreController } from '../../controllers/admin/post-settings-restore-controller'
+import { IController } from '../../@types/controllers'
+
+export const createPostAdminSettingsRestoreController = (): IController => {
+ return new PostAdminSettingsRestoreController()
+}
diff --git a/src/factories/controllers/post-admin-settings-validate-controller-factory.ts b/src/factories/controllers/post-admin-settings-validate-controller-factory.ts
new file mode 100644
index 00000000..3d3d6999
--- /dev/null
+++ b/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()
+}
diff --git a/src/routes/admin/index.ts b/src/routes/admin/index.ts
index 3e006ca5..6879b826 100644
--- a/src/routes/admin/index.ts
+++ b/src/routes/admin/index.ts
@@ -3,8 +3,14 @@ import express, { json, Router } from 'express'
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 { createGetAdminSettingsBackupsController } from '../../factories/controllers/get-admin-settings-backups-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 { createPostAdminSettingsRestoreController } from '../../factories/controllers/post-admin-settings-restore-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 {
@@ -29,5 +35,34 @@ router.post('/logout', adminRateLimitMiddleware, withAdminController(createPostA
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/backups',
+ adminRateLimitMiddleware,
+ adminAuthMiddleware,
+ withAdminController(createGetAdminSettingsBackupsController),
+)
+router.get(
+ '/settings/schema',
+ adminRateLimitMiddleware,
+ adminAuthMiddleware,
+ withAdminController(createGetAdminSettingsSchemaController),
+)
+// codeql[js/missing-rate-limiting] - adminRateLimitMiddleware applies Redis-backed admin rate limits
+router.patch('/settings', adminRateLimitMiddleware, adminAuthMiddleware, json(), withAdminController(createPatchAdminSettingsController))
+// codeql[js/missing-rate-limiting] - adminRateLimitMiddleware applies Redis-backed admin rate limits
+router.post(
+ '/settings/validate',
+ adminRateLimitMiddleware,
+ adminAuthMiddleware,
+ withAdminController(createPostAdminSettingsValidateController),
+)
+router.post(
+ '/settings/restore',
+ adminRateLimitMiddleware,
+ adminAuthMiddleware,
+ json(),
+ withAdminController(createPostAdminSettingsRestoreController),
+)
export default router
diff --git a/src/schemas/admin-settings-schema.ts b/src/schemas/admin-settings-schema.ts
new file mode 100644
index 00000000..86ea08ae
--- /dev/null
+++ b/src/schemas/admin-settings-schema.ts
@@ -0,0 +1,23 @@
+import { z } from 'zod'
+
+const adminSettingsChangeSchema = z
+ .object({
+ path: z.string().min(1),
+ value: z.custom((input) => input !== undefined, { message: 'value is required' }),
+ })
+ .strict()
+
+export const adminSettingsPatchBodySchema = z.union([
+ adminSettingsChangeSchema,
+ z
+ .object({
+ changes: z.array(adminSettingsChangeSchema).min(1),
+ })
+ .strict(),
+])
+
+export const adminSettingsRestoreBodySchema = z
+ .object({
+ filename: z.string().min(1),
+ })
+ .strict()
diff --git a/src/utils/settings-config.ts b/src/utils/settings-config.ts
index e2a38c47..a2ddd2bf 100644
--- a/src/utils/settings-config.ts
+++ b/src/utils/settings-config.ts
@@ -26,6 +26,10 @@ export const getSettingsFilePath = (): string => join(getConfigBaseDir(), 'setti
export const getDefaultSettingsFilePath = (): string => join(process.cwd(), 'resources', 'default-settings.yaml')
+export const getSettingsBackupDir = (): string => join(getConfigBaseDir(), 'backups')
+
+export const getSettingsAuditLogPath = (): string => join(getConfigBaseDir(), 'settings-audit.jsonl')
+
export const toCategoryLabel = (key: string): string => {
return key
.split(/[_\-.]/)
@@ -215,6 +219,10 @@ const validateShape = (schema: unknown, candidate: unknown, path: PathToken[], i
}
for (const key of Object.keys(candidate)) {
+ if (renderedPath === 'admin' && key === 'passwordHash') {
+ continue
+ }
+
if (!hasOwn(schema, key)) {
issues.push({
path: formatPathTokens([...path, { type: 'key', key }]),
@@ -300,7 +308,83 @@ export const loadMergedSettings = (): 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 backupDirectory = getSettingsBackupDir()
+ const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+
+ fs.mkdirSync(backupDirectory, { recursive: true })
+ if (fs.existsSync(settingsPath)) {
+ fs.copyFileSync(settingsPath, join(backupDirectory, `settings.${timestamp}.yaml`))
+ }
+
+ const temporaryPath = join(getConfigBaseDir(), `.settings.${process.pid}.${Date.now()}.tmp`)
+ try {
+ fs.writeFileSync(temporaryPath, serialized, { encoding: 'utf-8', mode: 0o600 })
+ fs.renameSync(temporaryPath, settingsPath)
+ } finally {
+ if (fs.existsSync(temporaryPath)) {
+ fs.rmSync(temporaryPath, { force: true })
+ }
+ }
+}
+
+export const appendSettingsAuditLog = (entry: Record): void => {
+ ensureSettingsExists()
+ fs.appendFileSync(
+ getSettingsAuditLogPath(),
+ `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`,
+ { encoding: 'utf-8', mode: 0o600 },
+ )
+}
+
+export type SettingsBackupInfo = {
+ filename: string
+ createdAt: string
+ sizeBytes: number
+}
+
+const isSafeBackupFilename = (filename: string): boolean => {
+ return /^settings\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.yaml$/.test(filename)
+}
+
+export const listSettingsBackups = (): SettingsBackupInfo[] => {
+ const backupDirectory = getSettingsBackupDir()
+ if (!fs.existsSync(backupDirectory)) {
+ return []
+ }
+
+ return fs
+ .readdirSync(backupDirectory)
+ .filter((filename) => isSafeBackupFilename(filename))
+ .map((filename) => {
+ const stats = fs.statSync(join(backupDirectory, filename))
+ return {
+ filename,
+ createdAt: stats.mtime.toISOString(),
+ sizeBytes: stats.size,
+ }
+ })
+ .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+}
+
+export const restoreSettingsBackup = (filename: string): Settings => {
+ if (!isSafeBackupFilename(filename)) {
+ throw new Error('Invalid backup filename')
+ }
+
+ const backupPath = join(getSettingsBackupDir(), filename)
+ if (!fs.existsSync(backupPath)) {
+ throw new Error('Backup not found')
+ }
+
+ const restored = yaml.load(fs.readFileSync(backupPath, 'utf-8')) as Settings
+ const issues = validateSettings(mergeDeepRight(loadDefaults(), restored) as Settings)
+ if (issues.length > 0) {
+ throw new Error(`Backup failed validation: ${issues.map((issue) => issue.path).join(', ')}`)
+ }
+
+ saveSettings(restored)
+ return restored
}
export const getTopLevelSettingCategories = (): string[] => {
diff --git a/src/utils/settings-guided-schema.ts b/src/utils/settings-guided-schema.ts
index 9a7bef44..d3279d64 100644
--- a/src/utils/settings-guided-schema.ts
+++ b/src/utils/settings-guided-schema.ts
@@ -36,6 +36,44 @@ export const requireSafeNonNegativeIntegerSettingValue = (value: string): string
}
export const guidedSettingCategories: GuidedSettingCategory[] = [
+ {
+ value: 'relay-info',
+ label: 'Relay Info',
+ settings: [
+ {
+ label: 'Relay URL',
+ path: 'info.relay_url',
+ type: 'string',
+ placeholder: 'wss://relay.example.com',
+ validate: requireNonEmptySettingValue,
+ },
+ {
+ label: 'Relay name',
+ path: 'info.name',
+ type: 'string',
+ placeholder: 'relay.example.com',
+ validate: requireNonEmptySettingValue,
+ },
+ {
+ label: 'Description',
+ path: 'info.description',
+ type: 'string',
+ placeholder: 'A nostr relay written in Typescript.',
+ },
+ {
+ label: 'Contact',
+ path: 'info.contact',
+ type: 'string',
+ placeholder: 'mailto:operator@your-domain.com',
+ },
+ {
+ label: 'Relay pubkey (hex)',
+ path: 'info.pubkey',
+ type: 'string',
+ placeholder: 'replace-with-your-pubkey-in-hex',
+ },
+ ],
+ },
{
value: 'payments',
label: 'Payments',
@@ -64,26 +102,18 @@ export const guidedSettingCategories: GuidedSettingCategory[] = [
value: 'network',
label: 'Network',
settings: [
- {
- label: 'Relay URL',
- path: 'info.relay_url',
- type: 'string',
- placeholder: 'wss://relay.example.com',
- validate: requireNonEmptySettingValue,
- },
- {
- label: 'Relay name',
- path: 'info.name',
- type: 'string',
- placeholder: 'relay.example.com',
- validate: requireNonEmptySettingValue,
- },
{
label: 'Max payload size',
path: 'network.maxPayloadSize',
type: 'number',
validate: requireSafeNonNegativeIntegerSettingValue,
},
+ {
+ label: 'Worker count',
+ path: 'workers.count',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
],
},
{
@@ -97,7 +127,7 @@ export const guidedSettingCategories: GuidedSettingCategory[] = [
options: ['ewma', 'sliding_window'],
},
{
- label: 'Primary event content max length',
+ label: 'Maximum event content length',
path: 'limits.event.content[0].maxLength',
type: 'number',
validate: requireSafeNonNegativeIntegerSettingValue,
@@ -108,6 +138,123 @@ export const guidedSettingCategories: GuidedSettingCategory[] = [
type: 'number',
validate: requireSafeNonNegativeIntegerSettingValue,
},
+ {
+ label: 'Maximum future event time (seconds)',
+ path: 'limits.event.createdAt.maxPositiveDelta',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ {
+ label: 'Pubkey blacklist',
+ path: 'limits.event.pubkey.blacklist',
+ type: 'stringArray',
+ placeholder: 'One hex pubkey per line',
+ },
+ {
+ label: 'Kind whitelist',
+ path: 'limits.event.kind.whitelist',
+ type: 'stringArray',
+ placeholder: 'One kind or range per line, e.g. 1 or 10000-19999',
+ },
+ ],
+ },
+ {
+ value: 'client',
+ label: 'Client',
+ settings: [
+ {
+ label: 'Max subscriptions per connection',
+ path: 'limits.client.subscription.maxSubscriptions',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ {
+ label: 'Max filters per subscription',
+ path: 'limits.client.subscription.maxFilters',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ {
+ label: 'Max filter values',
+ path: 'limits.client.subscription.maxFilterValues',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ {
+ label: 'Max REQ limit value',
+ path: 'limits.client.subscription.maxLimit',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ ],
+ },
+ {
+ value: 'retention',
+ label: 'Retention',
+ settings: [
+ {
+ label: 'Event retention (days)',
+ path: 'limits.event.retention.maxDays',
+ type: 'number',
+ },
+ ],
+ },
+ {
+ value: 'nip-features',
+ label: 'NIP Features',
+ settings: [
+ {
+ label: 'NIP-05 mode',
+ path: 'nip05.mode',
+ type: 'select',
+ options: ['enabled', 'passive', 'disabled'],
+ },
+ {
+ label: 'NIP-05 domain whitelist',
+ path: 'nip05.domainWhitelist',
+ type: 'stringArray',
+ placeholder: 'One domain per line',
+ },
+ {
+ label: 'NIP-05 domain blacklist',
+ path: 'nip05.domainBlacklist',
+ type: 'stringArray',
+ placeholder: 'One domain per line',
+ },
+ { label: 'Enable NIP-45', path: 'nip45.enabled', type: 'boolean' },
+ { label: 'Enable NIP-50', path: 'nip50.enabled', type: 'boolean' },
+ {
+ label: 'NIP-50 max query length',
+ path: 'nip50.maxQueryLength',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ { label: 'Enable Web of Trust', path: 'wot.enabled', type: 'boolean' },
+ {
+ label: 'WoT seed pubkey (hex)',
+ path: 'wot.seedPubkey',
+ type: 'string',
+ placeholder: 'Relay owner pubkey in hex',
+ },
+ {
+ label: 'WoT minimum followers',
+ path: 'wot.minimumFollowers',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
+ ],
+ },
+ {
+ value: 'admin',
+ label: 'Admin',
+ settings: [
+ { label: 'Enable admin console', path: 'admin.enabled', type: 'boolean' },
+ {
+ label: 'Session TTL (seconds)',
+ path: 'admin.sessionTtlSeconds',
+ type: 'number',
+ validate: requireSafeNonNegativeIntegerSettingValue,
+ },
],
},
]
diff --git a/src/utils/settings-redaction.ts b/src/utils/settings-redaction.ts
new file mode 100644
index 00000000..3546786d
--- /dev/null
+++ b/src/utils/settings-redaction.ts
@@ -0,0 +1,52 @@
+const SENSITIVE_SETTING_KEYS = new Set(['passwordHash', 'secret'])
+
+const isPlainObject = (value: unknown): value is Record => {
+ 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 = (settings: T): T => {
+ const redactWalk = (value: unknown): unknown => {
+ if (Array.isArray(value)) {
+ return value.map(redactWalk)
+ }
+
+ if (!isPlainObject(value)) {
+ return value
+ }
+
+ const result: Record = {}
+
+ 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
+}
diff --git a/src/utils/settings.ts b/src/utils/settings.ts
index 7cf90f6e..ee639d63 100644
--- a/src/utils/settings.ts
+++ b/src/utils/settings.ts
@@ -110,7 +110,6 @@ export class SettingsStatic {
const basePath = SettingsStatic.getSettingsFileBasePath()
const defaultsFilePath = SettingsStatic.getDefaultSettingsFilePath()
const fileType = SettingsStatic.settingsFileType(basePath)
- const settingsFilePath = join(basePath, `settings.${fileType}`)
const reload = () => {
logger('reloading settings')
@@ -118,6 +117,12 @@ export class SettingsStatic {
SettingsStatic.createSettings()
}
- return [fs.watch(defaultsFilePath, 'utf8', reload), fs.watch(settingsFilePath, 'utf8', reload)]
+ const watchSettingsDirectory = (_eventType: string, filename: string | Buffer | null) => {
+ if (filename?.toString() === `settings.${fileType}`) {
+ reload()
+ }
+ }
+
+ return [fs.watch(defaultsFilePath, 'utf8', reload), fs.watch(basePath, 'utf8', watchSettingsDirectory)]
}
}
diff --git a/test/unit/app/maintenance-worker.spec.ts b/test/unit/app/maintenance-worker.spec.ts
index d72bbae0..36381c25 100644
--- a/test/unit/app/maintenance-worker.spec.ts
+++ b/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))
diff --git a/test/unit/routes/admin-settings.spec.ts b/test/unit/routes/admin-settings.spec.ts
new file mode 100644
index 00000000..04b95df6
--- /dev/null
+++ b/test/unit/routes/admin-settings.spec.ts
@@ -0,0 +1,350 @@
+import axios from 'axios'
+import { expect } from 'chai'
+import express from 'express'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import Sinon from 'sinon'
+
+import { hashAdminPassword } from '../../../src/utils/admin-password'
+import * as adminRateLimitMiddleware from '../../../src/handlers/request-handlers/admin-rate-limit-middleware'
+import * as rateLimiterMiddleware from '../../../src/handlers/request-handlers/rate-limiter-middleware'
+import * as settingsFactory from '../../../src/factories/settings-factory'
+import {
+ getSettingsAuditLogPath,
+ getSettingsBackupDir,
+ getSettingsFilePath,
+ loadDefaults,
+ saveSettings,
+} from '../../../src/utils/settings-config'
+
+describe('admin settings API', () => {
+ const originalSecret = process.env.SECRET
+ const originalAdminPassword = process.env.ADMIN_PASSWORD
+ const originalConfigDir = process.env.NOSTR_CONFIG_DIR
+ let configDir: string
+ let createSettingsStub: Sinon.SinonStub
+ let rateLimiterMiddlewareStub: Sinon.SinonStub
+ let adminRateLimitMiddlewareStub: Sinon.SinonStub
+ let adminLoginRateLimitMiddlewareStub: Sinon.SinonStub
+ let server: any
+
+ const loadAdminRouter = () => {
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
+ delete require.cache[require.resolve('../../../src/routes/admin/index')]
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
+ delete require.cache[require.resolve('../../../src/routes/admin')]
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
+ return require('../../../src/routes/admin').default
+ }
+
+ const startServer = async (settings: Record) => {
+ createSettingsStub = Sinon.stub(settingsFactory, 'createSettings').returns(settings as any)
+ const passthrough = async (_request: any, _response: any, next: any) => {
+ next()
+ }
+ rateLimiterMiddlewareStub = Sinon.stub(rateLimiterMiddleware, 'rateLimiterMiddleware').callsFake(passthrough)
+ adminRateLimitMiddlewareStub = Sinon.stub(adminRateLimitMiddleware, 'adminRateLimitMiddleware').callsFake(
+ passthrough,
+ )
+ adminLoginRateLimitMiddlewareStub = Sinon.stub(adminRateLimitMiddleware, 'adminLoginRateLimitMiddleware').callsFake(
+ passthrough,
+ )
+ const router = loadAdminRouter()
+ const app = express()
+ app.use('/admin', router)
+
+ server = await new Promise((resolve) => {
+ const listeningServer = app.listen(0, () => resolve(listeningServer))
+ })
+
+ return `http://127.0.0.1:${server.address().port}/admin`
+ }
+
+ const stopServer = async () => {
+ createSettingsStub?.restore()
+ rateLimiterMiddlewareStub?.restore()
+ adminRateLimitMiddlewareStub?.restore()
+ adminLoginRateLimitMiddlewareStub?.restore()
+ delete require.cache[require.resolve('../../../src/routes/admin/index')]
+ delete require.cache[require.resolve('../../../src/routes/admin')]
+
+ if (server) {
+ await new Promise((resolve, reject) => {
+ server.close((error: Error | undefined) => {
+ if (error) {
+ reject(error)
+ return
+ }
+
+ resolve()
+ })
+ })
+ server = undefined
+ }
+ }
+
+ const login = async (baseUrl: string): Promise => {
+ const loginResponse = await axios.post(
+ `${baseUrl}/login`,
+ { password: 'settings-password' },
+ {
+ headers: { 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(loginResponse.status).to.equal(200)
+ return loginResponse.headers['set-cookie']?.[0]?.split(';')[0] ?? ''
+ }
+
+ before(() => {
+ process.env.SECRET = 'test-admin-secret-value'
+ configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nostream-admin-settings-'))
+ process.env.NOSTR_CONFIG_DIR = configDir
+ })
+
+ after(() => {
+ if (originalSecret === undefined) {
+ delete process.env.SECRET
+ } else {
+ process.env.SECRET = originalSecret
+ }
+
+ if (originalAdminPassword === undefined) {
+ delete process.env.ADMIN_PASSWORD
+ } else {
+ process.env.ADMIN_PASSWORD = originalAdminPassword
+ }
+
+ if (originalConfigDir === undefined) {
+ delete process.env.NOSTR_CONFIG_DIR
+ } else {
+ process.env.NOSTR_CONFIG_DIR = originalConfigDir
+ }
+
+ fs.rmSync(configDir, { recursive: true, force: true })
+ })
+
+ afterEach(async () => {
+ delete process.env.ADMIN_PASSWORD
+ fs.rmSync(getSettingsFilePath(), { force: true })
+ await stopServer()
+ })
+
+ it('requires authentication for settings routes', async () => {
+ const baseUrl = await startServer({ admin: { enabled: true } })
+
+ const settingsResponse = await axios.get(`${baseUrl}/settings`, { validateStatus: () => true })
+ const schemaResponse = await axios.get(`${baseUrl}/settings/schema`, { validateStatus: () => true })
+ const validateResponse = await axios.post(`${baseUrl}/settings/validate`, {}, { validateStatus: () => true })
+ const patchResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'payments.enabled', value: true },
+ {
+ headers: { 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(settingsResponse.status).to.equal(401)
+ expect(schemaResponse.status).to.equal(401)
+ expect(validateResponse.status).to.equal(401)
+ expect(patchResponse.status).to.equal(401)
+ })
+
+ it('returns redacted merged settings and guided schema', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ saveSettings({
+ ...loadDefaults(),
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ mirroring: {
+ static: [{ address: 'wss://mirror.example', secret: 'mirror-secret-value' }],
+ },
+ })
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ const settingsResponse = await axios.get(`${baseUrl}/settings`, {
+ headers: { cookie },
+ validateStatus: () => true,
+ })
+ const schemaResponse = await axios.get(`${baseUrl}/settings/schema`, {
+ headers: { cookie },
+ validateStatus: () => true,
+ })
+
+ expect(settingsResponse.status).to.equal(200)
+ expect(settingsResponse.data.settings.admin.passwordHash).to.equal('***')
+ expect(settingsResponse.data.settings.mirroring.static[0].secret).to.equal('***')
+ expect(settingsResponse.data.settings.info.name).to.be.a('string')
+
+ expect(schemaResponse.status).to.equal(200)
+ expect(schemaResponse.data.categories.some((entry: { value: string }) => entry.value === 'payments')).to.equal(true)
+ })
+
+ it('patches a setting path with validation and persists to settings.yaml', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ const patchResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'payments.enabled', value: true },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(patchResponse.status).to.equal(200)
+ expect(patchResponse.data).to.deep.equal({
+ ok: true,
+ path: 'payments.enabled',
+ value: true,
+ reload: 'restart-required',
+ })
+
+ const settingsRaw = fs.readFileSync(getSettingsFilePath(), 'utf-8')
+ expect(settingsRaw).to.include('payments:')
+ expect(settingsRaw).to.include('enabled: true')
+ })
+
+ it('atomically applies staged changes with a backup and audit entry', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ saveSettings({
+ ...loadDefaults(),
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ const patchResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ {
+ changes: [
+ { path: 'payments.enabled', value: true },
+ { path: 'nip50.enabled', value: true },
+ ],
+ },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(patchResponse.status, JSON.stringify(patchResponse.data)).to.equal(200)
+ expect(patchResponse.data.changes).to.have.length(2)
+ expect(fs.readdirSync(getSettingsBackupDir()).some((name) => name.startsWith('settings.'))).to.equal(true)
+ expect(fs.readFileSync(getSettingsAuditLogPath(), 'utf-8')).to.include('settings.updated')
+ })
+
+ it('lists and restores the latest settings backup', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ saveSettings({
+ ...loadDefaults(),
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ payments: { ...loadDefaults().payments, enabled: false },
+ })
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'payments.enabled', value: true },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ const backupsResponse = await axios.get(`${baseUrl}/settings/backups`, {
+ headers: { cookie },
+ validateStatus: () => true,
+ })
+
+ expect(backupsResponse.status).to.equal(200)
+ expect(backupsResponse.data.backups.length).to.be.greaterThan(0)
+
+ const restoreResponse = await axios.post(
+ `${baseUrl}/settings/restore`,
+ { filename: backupsResponse.data.backups[0].filename },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(restoreResponse.status).to.equal(200)
+ expect(fs.readFileSync(getSettingsAuditLogPath(), 'utf-8')).to.include('settings.restored')
+ })
+
+ it('rejects invalid paths and write-protected settings', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ const unknownPathResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'payments.fakeField', value: true },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+ const protectedPathResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'admin.passwordHash', value: 'new-hash' },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+ const invalidBodyResponse = await axios.patch(
+ `${baseUrl}/settings`,
+ { path: 'payments.enabled', unexpected: true },
+ {
+ headers: { cookie, 'content-type': 'application/json' },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(unknownPathResponse.status).to.equal(400)
+ expect(unknownPathResponse.data.error).to.equal('Validation failed')
+ expect(protectedPathResponse.status).to.equal(400)
+ expect(protectedPathResponse.data.issues[0].message).to.equal('Path is write-protected')
+ expect(invalidBodyResponse.status).to.equal(400)
+ expect(invalidBodyResponse.data.error).to.equal('Invalid request')
+ })
+
+ it('validates merged settings', async () => {
+ const passwordHash = hashAdminPassword('settings-password')
+ const baseUrl = await startServer({
+ admin: { enabled: true, passwordHash, sessionTtlSeconds: 3600 },
+ })
+ const cookie = await login(baseUrl)
+
+ const validateResponse = await axios.post(
+ `${baseUrl}/settings/validate`,
+ {},
+ {
+ headers: { cookie },
+ validateStatus: () => true,
+ },
+ )
+
+ expect(validateResponse.status).to.equal(200)
+ expect(validateResponse.data.valid).to.equal(true)
+ expect(validateResponse.data.issues).to.deep.equal([])
+ })
+})
diff --git a/test/unit/utils/settings-config.spec.ts b/test/unit/utils/settings-config.spec.ts
index 8f4ba1e4..8acaf643 100644
--- a/test/unit/utils/settings-config.spec.ts
+++ b/test/unit/utils/settings-config.spec.ts
@@ -1,12 +1,12 @@
import { expect } from 'chai'
import {
+ toCategoryLabel,
getByPath,
getTopLevelSettingCategories,
parseTypedValue,
parseValue,
setByPath,
- toCategoryLabel,
validatePathAgainstDefaults,
validateSettings,
} from '../../../src/utils/settings-config'
diff --git a/test/unit/utils/settings-redaction.spec.ts b/test/unit/utils/settings-redaction.spec.ts
new file mode 100644
index 00000000..e140f903
--- /dev/null
+++ b/test/unit/utils/settings-redaction.spec.ts
@@ -0,0 +1,60 @@
+import { expect } from 'chai'
+
+import {
+ isSensitiveSettingsPath,
+ isWriteProtectedSettingsPath,
+ redactSettingsSecrets,
+ redactSettingsValue,
+} from '../../../src/utils/settings-redaction'
+
+describe('settings-redaction', () => {
+ it('redacts passwordHash and secret values in nested settings', () => {
+ const input = {
+ admin: {
+ enabled: true,
+ passwordHash: 'hashed-password-value',
+ },
+ mirroring: {
+ static: [
+ {
+ address: 'wss://mirror.example',
+ secret: 'mirror-secret-value',
+ },
+ ],
+ },
+ payments: {
+ enabled: false,
+ },
+ }
+
+ const redacted = redactSettingsSecrets(input)
+
+ expect(redacted.admin.passwordHash).to.equal('***')
+ expect(redacted.mirroring.static[0].secret).to.equal('***')
+ expect(redacted.mirroring.static[0].address).to.equal('wss://mirror.example')
+ expect(redacted.payments.enabled).to.equal(false)
+ })
+
+ it('leaves empty secret values unchanged', () => {
+ const input = {
+ mirroring: {
+ static: [{ address: 'wss://mirror.example', secret: '' }],
+ },
+ }
+
+ expect(redactSettingsSecrets(input).mirroring.static[0].secret).to.equal('')
+ })
+
+ it('identifies sensitive and write-protected paths', () => {
+ expect(isSensitiveSettingsPath('admin.passwordHash')).to.equal(true)
+ expect(isSensitiveSettingsPath('mirroring.static[0].secret')).to.equal(true)
+ expect(isSensitiveSettingsPath('payments.enabled')).to.equal(false)
+ expect(isWriteProtectedSettingsPath('admin.passwordHash')).to.equal(true)
+ expect(isWriteProtectedSettingsPath('mirroring.static[0].secret')).to.equal(false)
+ })
+
+ it('redacts single values by path', () => {
+ expect(redactSettingsValue('mirroring.static[0].secret', 'top-secret')).to.equal('***')
+ expect(redactSettingsValue('payments.enabled', true)).to.equal(true)
+ })
+})