Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

fix(wizard): block setup endpoints after initialization

Timothy Yinc524890efab5
diff --git a/package.json b/package.json
index 5eead955..95a607d7 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,7 @@
"es-toolkit": "^1.52.0",
"exiftool-vendored": "^35.21.0",
"file-type": "^22.1.1",
+ "h3": "^1.15.11",
"heic-convert": "^2.1.0",
"maplibre-gl": "^5.24.0",
"motion-v": "^2.6.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d09cf733..9feadab3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -80,6 +80,9 @@ importers:
file-type:
specifier: ^22.1.1
version: 22.1.1
+ h3:
+ specifier: ^1.15.11
+ version: 1.15.11
heic-convert:
specifier: ^2.1.0
version: 2.1.0
diff --git a/server/api/wizard/admin.post.ts b/server/api/wizard/admin.post.ts
index 9c700797..51fbe010 100644
--- a/server/api/wizard/admin.post.ts
+++ b/server/api/wizard/admin.post.ts
@@ -1,6 +1,7 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const db = useDB()
const { email, password, username } = await readValidatedBody(
event,
diff --git a/server/api/wizard/complete.post.ts b/server/api/wizard/complete.post.ts
index 903a096a..bd977528 100644
--- a/server/api/wizard/complete.post.ts
+++ b/server/api/wizard/complete.post.ts
@@ -1,6 +1,7 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { settingsManager } from '~~/server/services/settings/settingsManager'
-export default eventHandler(async (_event) => {
+export default defineWizardHandler(async (_event) => {
// Set firstLaunch to false
// Pass true as the last argument (sudo) to bypass readonly check
await settingsManager.set('system', 'firstLaunch', false, undefined, true)
diff --git a/server/api/wizard/map.post.ts b/server/api/wizard/map.post.ts
index 4a39f222..d90fee06 100644
--- a/server/api/wizard/map.post.ts
+++ b/server/api/wizard/map.post.ts
@@ -1,7 +1,8 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const body = await readValidatedBody(
event,
z.object({
diff --git a/server/api/wizard/schema.get.ts b/server/api/wizard/schema.get.ts
index 11e54f38..0c369cd1 100644
--- a/server/api/wizard/schema.get.ts
+++ b/server/api/wizard/schema.get.ts
@@ -1,10 +1,11 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import { getHiddenSettingKeys } from '~~/server/services/settings/contants'
import { getSettingUIConfig } from '~~/server/services/settings/ui-config'
import type { FieldDescriptor } from '~~/shared/types/settings'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const query = await getValidatedQuery(
event,
z.object({
diff --git a/server/api/wizard/site.post.ts b/server/api/wizard/site.post.ts
index d167ecc0..c218f1f0 100644
--- a/server/api/wizard/site.post.ts
+++ b/server/api/wizard/site.post.ts
@@ -1,7 +1,8 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const body = await readValidatedBody(
event,
z.object({
diff --git a/server/api/wizard/storage.post.ts b/server/api/wizard/storage.post.ts
index d80e9fc2..b5f24887 100644
--- a/server/api/wizard/storage.post.ts
+++ b/server/api/wizard/storage.post.ts
@@ -1,8 +1,9 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import { storageConfigSchema } from '~~/shared/types/storage'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const body = await readValidatedBody(
event,
z.object({
diff --git a/server/api/wizard/submit.post.ts b/server/api/wizard/submit.post.ts
index aa268051..d81bc569 100644
--- a/server/api/wizard/submit.post.ts
+++ b/server/api/wizard/submit.post.ts
@@ -1,9 +1,10 @@
+import { defineWizardHandler } from '../../utils/wizard-handler'
import { z } from 'zod'
import { settingsManager } from '~~/server/services/settings/settingsManager'
import { storageConfigSchema } from '~~/shared/types/storage'
import { useDB, tables, eq } from '~~/server/utils/db'
-export default eventHandler(async (event) => {
+export default defineWizardHandler(async (event) => {
const body = await readValidatedBody(
event,
z.object({
diff --git a/server/services/wizard-guard.ts b/server/services/wizard-guard.ts
new file mode 100644
index 00000000..5e60a81d
--- /dev/null
+++ b/server/services/wizard-guard.ts
@@ -0,0 +1,36 @@
+import { createError } from 'h3'
+
+// One shared gate for every wizard endpoint in this server process.
+export function createWizardGuard(isFirstLaunch: () => Promise<unknown>) {
+ let pending: Promise<unknown> = Promise.resolve()
+ let windowStart = 0
+ let attempts = 0
+
+ return async function guard<T>(run: () => Promise<T> | T): Promise<T> {
+ // A global limit also bounds the queue and cannot be bypassed by spoofing
+ // forwarded IP headers. Setup normally needs only a handful of requests.
+ const now = Date.now()
+ if (now - windowStart >= 60_000) {
+ windowStart = now
+ attempts = 0
+ }
+ if (++attempts > 60) {
+ throw createError({ statusCode: 429, message: 'Too many setup requests' })
+ }
+
+ const request = pending.then(async () => {
+ // Check inside the queue so requests waiting behind submit/complete
+ // cannot modify settings or credentials after setup has finished.
+ // Only an explicit true enables setup; missing state fails closed.
+ if ((await isFirstLaunch()) !== true) {
+ throw createError({
+ statusCode: 403,
+ message: 'Setup already completed',
+ })
+ }
+ return run()
+ })
+ pending = request.catch(() => {})
+ return request
+ }
+}
diff --git a/server/utils/wizard-handler.ts b/server/utils/wizard-handler.ts
new file mode 100644
index 00000000..f2bdfe2c
--- /dev/null
+++ b/server/utils/wizard-handler.ts
@@ -0,0 +1,11 @@
+import { eventHandler, type EventHandler } from 'h3'
+import { settingsManager } from '../services/settings/settingsManager'
+import { createWizardGuard } from '../services/wizard-guard'
+
+const guard = createWizardGuard(() =>
+ settingsManager.get('system', 'firstLaunch'),
+)
+
+export function defineWizardHandler(handler: EventHandler) {
+ return eventHandler((event) => guard(() => handler(event)))
+}
diff --git a/tests/wizard-guard.test.ts b/tests/wizard-guard.test.ts
new file mode 100644
index 00000000..b5939c6b
--- /dev/null
+++ b/tests/wizard-guard.test.ts
@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createWizardGuard } from '../server/services/wizard-guard.ts'
+
+test('wizard only runs with explicit first-launch state', async () => {
+ for (const state of [false, undefined, null, 'true', 1]) {
+ const guard = createWizardGuard(async () => state)
+ await assert.rejects(
+ guard(() => assert.fail('must not execute')),
+ { statusCode: 403 },
+ )
+ }
+ const guard = createWizardGuard(async () => true)
+ assert.equal(await guard(() => 'ok'), 'ok')
+})
+
+test('queued requests cannot overwrite credentials after completion', async () => {
+ let firstLaunch = true
+ const guard = createWizardGuard(async () => firstLaunch)
+ const complete = guard(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 10))
+ firstLaunch = false
+ })
+ const overwrite = guard(() => assert.fail('must not execute'))
+ await Promise.all([complete, assert.rejects(overwrite, { statusCode: 403 })])
+})
+
+test('failed requests release the gate', async () => {
+ const guard = createWizardGuard(async () => true)
+ await assert.rejects(
+ guard(() => {
+ throw new Error('invalid input')
+ }),
+ )
+ assert.equal(await guard(() => 'ok'), 'ok')
+})
+
+test('limits requests across endpoints, including failed requests', async () => {
+ const guard = createWizardGuard(async () => false)
+ for (let i = 0; i < 60; i++) {
+ await assert.rejects(
+ guard(() => assert.fail()),
+ { statusCode: 403 },
+ )
+ }
+ await assert.rejects(
+ guard(() => assert.fail()),
+ { statusCode: 429 },
+ )
+})
+
+test('rate limit recovers after its one-minute window', async (t) => {
+ t.mock.timers.enable({ apis: ['Date'], now: 120_000 })
+ const guard = createWizardGuard(async () => true)
+ for (let i = 0; i < 60; i++) await guard(() => 'ok')
+ await assert.rejects(
+ guard(() => 'blocked'),
+ { statusCode: 429 },
+ )
+ t.mock.timers.tick(60_000)
+ assert.equal(await guard(() => 'ok'), 'ok')
+})