@shawnstack/quickforge 1.7.6 → 1.7.8

package/server/lan-access-store.mjs

@@ -2,6 +2,8 @@ import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { ensureStorage, storageDir } from './storage.mjs'
 import { createRandomToken, hashPassword, safeHashEqual, sha256Base64Url, verifyPassword } from './utils/password-auth.mjs'
+import { getLanAccessRepository, isLanAccessStorageAuthoritative, requestLanAccessJsonMirrorDrain } from './lan-access-service.mjs'
+import { isLanAccessMaintenanceActive } from './lan-access-cutover.mjs'
 
 const LAN_ACCESS_DIR = path.join(storageDir, 'security')
 const LAN_ACCESS_FILE = path.join(LAN_ACCESS_DIR, 'lan-access.json')
@@ -20,6 +22,40 @@ function enqueueWrite(queueName, operation) {
   return next
 }
 
+// F11 Phase 2: once the LAN access storage is SQLite-readable
+// (sqlite_authoritative_json_pending/authoritative) every read/write routes
+// through the repository and the JSON file degrades to a best-effort mirror.
+// json_authoritative/cutover_running keep the legacy JSON path below.
+function repositoryActive() {
+  return isLanAccessStorageAuthoritative()
+}
+
+// Maintenance writes are only blocked while the SQLite store is authoritative;
+// the legacy JSON path keeps working during cutover/maintenance.
+function assertLanAccessWritesAllowed() {
+  if (!repositoryActive()) return
+  if (isLanAccessMaintenanceActive()) {
+    const error = new Error('LAN access storage is under maintenance')
+    error.statusCode = 423
+    error.errorCode = 'LAN_ACCESS_MAINTENANCE_ACTIVE'
+    throw error
+  }
+}
+
+// Fail closed on a missing config record: pending/authoritative states are only
+// entered after cutover integrity verification, so a missing row means the
+// store is damaged and must not be silently treated as default-disabled.
+function requireLanAccessRepositoryConfig() {
+  const config = getLanAccessRepository().getConfig()
+  if (!config) {
+    const error = new Error('LAN access state is unavailable')
+    error.statusCode = 503
+    error.errorCode = 'LAN_ACCESS_STATE_UNAVAILABLE'
+    throw error
+  }
+  return config
+}
+
 function defaultLanAccessConfig() {
   return {
     enabled: false,
@@ -144,15 +180,30 @@ function assertPasswordAllowed(password) {
 }
 
 export async function readLanAccessStatus() {
+  if (repositoryActive()) return publicStatus(requireLanAccessRepositoryConfig())
   return publicStatus(await readLanAccessFile())
 }
 
 export async function readLanAccessConfig() {
+  if (repositoryActive()) return requireLanAccessRepositoryConfig()
   return readLanAccessFile()
 }
 
 export async function updateLanAccessSettings({ enabled, password, sessionTtlHours }) {
   return enqueueWrite(writeQueueName, async () => {
+    assertLanAccessWritesAllowed()
+    if (repositoryActive()) {
+      const passwordProvided = typeof password === 'string' && password.length > 0
+      if (passwordProvided) assertPasswordAllowed(password)
+      const passwordInfo = passwordProvided ? await hashPassword(password.trim()) : {}
+      const updated = getLanAccessRepository().updateSettings({
+        enabled,
+        sessionTtlHours,
+        ...passwordInfo,
+      })
+      requestLanAccessJsonMirrorDrain()
+      return publicStatus(updated.config)
+    }
     const current = await readLanAccessFile()
     const passwordProvided = typeof password === 'string' && password.length > 0
     const nextEnabled = Boolean(enabled)
@@ -184,6 +235,12 @@ export async function updateLanAccessSettings({ enabled, password, sessionTtlHou
 
 export async function revokeLanAccessTokens() {
   return enqueueWrite(writeQueueName, async () => {
+    assertLanAccessWritesAllowed()
+    if (repositoryActive()) {
+      const updated = getLanAccessRepository().revokeAll()
+      requestLanAccessJsonMirrorDrain()
+      return publicStatus(updated.config)
+    }
     const current = await readLanAccessFile()
     const next = normalizeConfig({
       ...current,
@@ -204,6 +261,12 @@ export async function revokeLanAccessTokenById(id) {
     throw error
   }
   return enqueueWrite(writeQueueName, async () => {
+    assertLanAccessWritesAllowed()
+    if (repositoryActive()) {
+      const updated = getLanAccessRepository().revokeTokenById(normalizedId)
+      requestLanAccessJsonMirrorDrain()
+      return publicStatus(updated.config)
+    }
     const current = await readLanAccessFile()
     const tokens = pruneTokens(current.tokens)
     const nextTokens = tokens.filter((tokenRecord) => tokenRecordId(tokenRecord) !== normalizedId)
@@ -228,6 +291,12 @@ export async function revokeLanAccessToken(token) {
   if (!secret) return false
   const actualHash = sha256Base64Url(secret)
   return enqueueWrite(writeQueueName, async () => {
+    assertLanAccessWritesAllowed()
+    if (repositoryActive()) {
+      const revoked = getLanAccessRepository().revokeToken(token)
+      requestLanAccessJsonMirrorDrain()
+      return revoked
+    }
     const current = await readLanAccessFile()
     if (Number(versionText) !== (current.authVersion || 1)) return false
     const tokens = pruneTokens(current.tokens)
@@ -249,6 +318,31 @@ export function lanAccessCookieName() {
 
 export async function issueLanAccessToken(password, metadata = {}) {
   return enqueueWrite(writeQueueName, async () => {
+    assertLanAccessWritesAllowed()
+    if (repositoryActive()) {
+      const repository = getLanAccessRepository()
+      const current = repository.getConfig()
+      if (!current?.enabled || !current.passwordHash) {
+        const error = new Error('LAN access is not enabled.')
+        error.statusCode = 403
+        throw error
+      }
+      if (!(await verifyPassword(current, typeof password === 'string' ? password.trim() : ''))) {
+        const error = new Error('Invalid LAN access password')
+        error.statusCode = 401
+        throw error
+      }
+      const result = repository.issueToken({
+        remoteAddress: metadata.remoteAddress,
+        userAgent: metadata.userAgent,
+      })
+      requestLanAccessJsonMirrorDrain()
+      return {
+        token: result.token,
+        expiresAt: result.expiresAt,
+        maxAge: result.maxAge,
+      }
+    }
     const current = await readLanAccessFile()
     if (!current.enabled || !current.passwordHash) {
       const error = new Error('LAN access is not enabled.')
@@ -293,13 +387,20 @@ export async function issueLanAccessToken(password, metadata = {}) {
 }
 
 export async function verifyLanAccessToken(token) {
-  const current = await readLanAccessFile()
-  if (!current.enabled || !current.passwordHash || !token || typeof token !== 'string') return false
-  const [versionText, secret] = token.split('.')
-  if (Number(versionText) !== (current.authVersion || 1) || !secret) return false
-  const actualHash = sha256Base64Url(secret)
-  return pruneTokens(current.tokens).some((tokenRecord) => {
-    if ((tokenRecord.authVersion || 1) !== (current.authVersion || 1)) return false
-    return safeHashEqual(tokenRecord.tokenHash, actualHash)
-  })
+  try {
+    if (repositoryActive()) return getLanAccessRepository().verifyToken(token)
+    const current = await readLanAccessFile()
+    if (!current.enabled || !current.passwordHash || !token || typeof token !== 'string') return false
+    const [versionText, secret] = token.split('.')
+    if (Number(versionText) !== (current.authVersion || 1) || !secret) return false
+    const actualHash = sha256Base64Url(secret)
+    return pruneTokens(current.tokens).some((tokenRecord) => {
+      if ((tokenRecord.authVersion || 1) !== (current.authVersion || 1)) return false
+      return safeHashEqual(tokenRecord.tokenHash, actualHash)
+    })
+  } catch {
+    // Fail closed on any storage error or malformed input: LAN access is
+    // denied rather than accidentally allowed.
+    return false
+  }
 }

package/server/maintenance/downgrade-lan-access-v1.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { closeSqliteStorage, initializeSqliteStorage } from '../sqlite/database.mjs'
+import { createLanAccessRepository } from '../sqlite/lan-access-repository.mjs'
+import { buildLanAccessJsonSnapshot } from '../lan-access-cutover.mjs'
+import {
+  LAN_ACCESS_STORAGE_PHASES,
+  configureLanAccessService,
+  createDefaultLanAccessMirror,
+  drainLanAccessJsonMirror,
+  readLanAccessStorageState,
+  setLanAccessStoragePhase,
+} from '../lan-access-service.mjs'
+import { readLanAccessJsonFile } from '../lan-access-json-file.mjs'
+import { dataDir } from '../storage.mjs'
+
+// F11 Phase 3 offline LAN access downgrade (shutdown-time only). Mirrors
+// downgrade-share-v1.mjs in the independent lan-access storage domain:
+// --dry-run reports without writing anything or changing the phase; the default
+// run drains the lan-access JSON mirror (materializing the whole config into
+// security/lan-access.json) and verifies the on-disk JSON against the
+// authoritative SQLite snapshot with an exact count/digest comparison; --commit
+// then flips authority back to json_authoritative. Any failure leaves no
+// partial output or phase change.
+const AUTHORITATIVE_PHASES = new Set(['sqlite_authoritative_json_pending', 'authoritative'])
+
+const args = new Set(process.argv.slice(2).filter((arg) => arg.startsWith('--')))
+const dryRun = args.has('--dry-run')
+const commit = args.has('--commit')
+
+function exitError(message) {
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
+
+try {
+  const storage = await initializeSqliteStorage({ dataDir })
+  storage.health({ quickCheck: true })
+  const repository = createLanAccessRepository(storage)
+  configureLanAccessService({ repository, mirror: createDefaultLanAccessMirror() })
+  const state = readLanAccessStorageState()
+  if (state.phase === 'cutover_running') {
+    throw new Error('LAN access cutover is still running; stop all QuickForge processes and retry')
+  }
+  if (state.phase === LAN_ACCESS_STORAGE_PHASES.JSON_AUTHORITATIVE) {
+    throw new Error('LAN access storage is already JSON authoritative; nothing to downgrade')
+  }
+  if (!AUTHORITATIVE_PHASES.has(state.phase)) {
+    throw new Error(`LAN access storage is ${state.phase}; downgrade requires pending or authoritative phase`)
+  }
+  const integrity = repository.verifyIntegrity({ quickCheck: true })
+  if (!integrity.ok) throw new Error('LAN access storage integrity verification failed')
+  const snapshot = repository.exportSnapshot()
+  if (snapshot.tokenCount !== integrity.count || snapshot.digest !== integrity.digest) {
+    throw new Error('LAN access storage snapshot count/digest verification failed')
+  }
+  const report = {
+    ok: true,
+    phase: state.phase,
+    count: snapshot.tokenCount,
+    digest: snapshot.digest,
+    dryRun,
+    commit,
+    lanAccessFile: path.join(dataDir, 'storage', 'security', 'lan-access.json'),
+  }
+
+  if (dryRun) {
+    // Read-only: report what a real run would do without writing anything or
+    // changing the phase.
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    const drained = await drainLanAccessJsonMirror()
+    if (drained.pending !== 0) {
+      throw new Error(`LAN access JSON mirror drain failed: ${drained.pending} pending`)
+    }
+    // Verify the on-disk JSON store exactly matches the authoritative SQLite
+    // snapshot before allowing any phase change.
+    const mirror = buildLanAccessJsonSnapshot(await readLanAccessJsonFile())
+    if (mirror.tokenCount !== snapshot.tokenCount || mirror.digest !== snapshot.digest) {
+      throw new Error(`LAN access JSON mirror verification failed: SQLite ${snapshot.tokenCount}/${snapshot.digest} vs JSON ${mirror.tokenCount}/${mirror.digest}`)
+    }
+    report.materialized = drained.drained
+    if (commit) {
+      setLanAccessStoragePhase(LAN_ACCESS_STORAGE_PHASES.JSON_AUTHORITATIVE, {
+        lanTokenCount: snapshot.tokenCount,
+        digest: snapshot.digest,
+        diagnostic: { operation: 'downgrade', materialized: drained.drained },
+      })
+      report.phase = LAN_ACCESS_STORAGE_PHASES.JSON_AUTHORITATIVE
+      report.phaseChanged = true
+    } else {
+      report.phaseChanged = false
+      report.message = 'LAN access JSON mirror materialized; run with --commit after stopping all QuickForge processes to switch authority back to JSON'
+    }
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  }
+} catch (error) {
+  exitError(error?.message || String(error))
+} finally {
+  await closeSqliteStorage().catch(() => {})
+}

package/server/maintenance/downgrade-session-state-v1.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { closeSqliteStorage, initializeSqliteStorage } from '../sqlite/database.mjs'
+import { createSessionStateRepository, snapshotDigestLine } from '../sqlite/session-state-repository.mjs'
+import { buildSessionJsonSnapshot } from '../session-state-cutover.mjs'
+import {
+  SESSION_STORAGE_PHASES,
+  configureSessionStateService,
+  drainSessionJsonMirror,
+  readSessionStorageState,
+  setSessionStoragePhase,
+} from '../session-state-service.mjs'
+import {
+  dataDir,
+  materializeSessionJsonMirrorEntry,
+  readPhysicalSessionStateBuckets,
+} from '../storage.mjs'
+
+const AUTHORITATIVE_PHASES = new Set(['sqlite_authoritative_json_pending', 'authoritative'])
+
+const args = new Set(process.argv.slice(2).filter((arg) => arg.startsWith('--')))
+const dryRun = args.has('--dry-run')
+const commit = args.has('--commit')
+
+function mirrorAdapter() {
+  async function materialize(entry) {
+    await materializeSessionJsonMirrorEntry(entry)
+  }
+  return { upsert: materialize, delete: materialize }
+}
+
+function exitError(message) {
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().filter((key) => value[key] !== undefined).map((key) => [key, canonicalize(value[key])]))
+}
+
+function digestJson(value) {
+  return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex')
+}
+
+// F9 split sessions: the downgrade materializes the JSON mirror as full bodies
+// (split marker + messages inline) via drainSessionJsonMirror, so the SQLite
+// side must be digested over the ASSEMBLED representation — not the stored
+// stripped body + messages digest — to compare against buildSessionJsonSnapshot.
+function assembledSnapshotDigest(snapshot) {
+  const rows = snapshot.records.map((record) => {
+    const state = record.state?.messageStorage === 'split'
+      ? { ...record.state, messages: record.messages ?? [] }
+      : record.state
+    return snapshotDigestLine(record.scope, record.projectId || '', record.sessionId, digestJson(state), digestJson(record.metadata), '')
+  })
+  return createHash('sha256').update(rows.sort().join('\n')).digest('hex')
+}
+
+try {
+  const storage = await initializeSqliteStorage({ dataDir })
+  storage.health({ quickCheck: true })
+  const repository = createSessionStateRepository(storage)
+  configureSessionStateService({ repository, mirror: mirrorAdapter() })
+  const state = readSessionStorageState()
+  if (state.phase === 'cutover_running') {
+    throw new Error('Session state cutover is still running; stop all QuickForge processes and retry')
+  }
+  if (state.phase === SESSION_STORAGE_PHASES.JSON_AUTHORITATIVE) {
+    throw new Error('Session state is already JSON authoritative; nothing to downgrade')
+  }
+  if (!AUTHORITATIVE_PHASES.has(state.phase)) {
+    throw new Error(`Session state is ${state.phase}; downgrade requires pending or authoritative phase`)
+  }
+  const integrity = repository.verifyIntegrity({ quickCheck: true })
+  if (!integrity.ok) throw new Error('Session state integrity verification failed')
+  const snapshot = repository.exportSnapshot()
+  if (snapshot.count !== integrity.count || snapshot.digest !== integrity.digest) {
+    throw new Error('Session state snapshot count/digest verification failed')
+  }
+  const report = {
+    ok: true,
+    phase: state.phase,
+    count: snapshot.count,
+    digest: snapshot.digest,
+    dryRun,
+    commit,
+    sessionsDirectory: path.join(dataDir, 'storage', 'conversations'),
+  }
+
+  if (dryRun) {
+    // Read-only: report what a real run would materialize without writing
+    // anything or changing the phase.
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    await drainSessionJsonMirror()
+    // Verify the on-disk JSON mirror exactly matches the authoritative SQLite
+    // snapshot before allowing any phase change. Split sessions are compared
+    // over their assembled representation (full body with messages), which is
+    // what the JSON mirror materializes.
+    const mirror = buildSessionJsonSnapshot(await readPhysicalSessionStateBuckets())
+    const targetDigest = assembledSnapshotDigest(snapshot)
+    if (mirror.count !== snapshot.count || mirror.digest !== targetDigest) {
+      throw new Error(`JSON mirror verification failed: SQLite ${snapshot.count}/${targetDigest} vs JSON ${mirror.count}/${mirror.digest}`)
+    }
+    if (commit) {
+      setSessionStoragePhase(SESSION_STORAGE_PHASES.JSON_AUTHORITATIVE, {
+        stateCount: snapshot.count,
+        digest: snapshot.digest,
+        diagnostic: { operation: 'downgrade', materialized: mirror.count },
+      })
+      report.phase = SESSION_STORAGE_PHASES.JSON_AUTHORITATIVE
+      report.phaseChanged = true
+    } else {
+      report.phaseChanged = false
+      report.message = 'JSON mirror materialized; run with --commit after stopping all QuickForge processes to switch authority back to JSON'
+    }
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  }
+} catch (error) {
+  exitError(error?.message || String(error))
+} finally {
+  await closeSqliteStorage().catch(() => {})
+}

package/server/maintenance/downgrade-share-v1.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { closeSqliteStorage, initializeSqliteStorage } from '../sqlite/database.mjs'
+import { createShareRepository } from '../sqlite/share-repository.mjs'
+import { buildShareJsonSnapshot } from '../share-cutover.mjs'
+import {
+  SHARE_STORAGE_PHASES,
+  configureShareService,
+  createDefaultShareMirror,
+  drainShareJsonMirror,
+  readShareStorageState,
+  setShareStoragePhase,
+} from '../share-service.mjs'
+import { readSharesJsonFile } from '../share-json-file.mjs'
+import { dataDir } from '../storage.mjs'
+
+// F10 Phase 3 offline share downgrade (shutdown-time only). Mirrors
+// downgrade-session-state-v1.mjs in the independent share storage domain:
+// --dry-run reports without writing anything or changing the phase; the default
+// run drains the share JSON mirror (materializing the whole conversation-shares
+// store) and verifies the on-disk JSON against the authoritative SQLite
+// snapshot with an exact count/digest comparison; --commit then flips authority
+// back to json_authoritative. Any failure leaves no partial output or phase
+// change.
+const AUTHORITATIVE_PHASES = new Set(['sqlite_authoritative_json_pending', 'authoritative'])
+
+const args = new Set(process.argv.slice(2).filter((arg) => arg.startsWith('--')))
+const dryRun = args.has('--dry-run')
+const commit = args.has('--commit')
+
+function exitError(message) {
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
+
+try {
+  const storage = await initializeSqliteStorage({ dataDir })
+  storage.health({ quickCheck: true })
+  const repository = createShareRepository(storage)
+  configureShareService({ repository, mirror: createDefaultShareMirror() })
+  const state = readShareStorageState()
+  if (state.phase === 'cutover_running') {
+    throw new Error('Share cutover is still running; stop all QuickForge processes and retry')
+  }
+  if (state.phase === SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE) {
+    throw new Error('Share storage is already JSON authoritative; nothing to downgrade')
+  }
+  if (!AUTHORITATIVE_PHASES.has(state.phase)) {
+    throw new Error(`Share storage is ${state.phase}; downgrade requires pending or authoritative phase`)
+  }
+  const integrity = repository.verifyIntegrity({ quickCheck: true })
+  if (!integrity.ok) throw new Error('Share storage integrity verification failed')
+  const snapshot = repository.exportSnapshot()
+  if (snapshot.count !== integrity.count || snapshot.digest !== integrity.digest) {
+    throw new Error('Share storage snapshot count/digest verification failed')
+  }
+  const report = {
+    ok: true,
+    phase: state.phase,
+    count: snapshot.count,
+    digest: snapshot.digest,
+    dryRun,
+    commit,
+    sharesFile: path.join(dataDir, 'storage', 'shares', 'conversation-shares.json'),
+  }
+
+  if (dryRun) {
+    // Read-only: report what a real run would do without writing anything or
+    // changing the phase.
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    const drained = await drainShareJsonMirror()
+    if (drained.pending !== 0) {
+      throw new Error(`Share JSON mirror drain failed: ${drained.pending} pending`)
+    }
+    // Verify the on-disk JSON store exactly matches the authoritative SQLite
+    // snapshot before allowing any phase change.
+    const mirror = buildShareJsonSnapshot(await readSharesJsonFile())
+    if (mirror.count !== snapshot.count || mirror.digest !== snapshot.digest) {
+      throw new Error(`Share JSON mirror verification failed: SQLite ${snapshot.count}/${snapshot.digest} vs JSON ${mirror.count}/${mirror.digest}`)
+    }
+    report.materialized = drained.drained
+    if (commit) {
+      setShareStoragePhase(SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE, {
+        shareCount: snapshot.count,
+        digest: snapshot.digest,
+        diagnostic: { operation: 'downgrade', materialized: drained.drained },
+      })
+      report.phase = SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE
+      report.phaseChanged = true
+    } else {
+      report.phaseChanged = false
+      report.message = 'Share JSON mirror materialized; run with --commit after stopping all QuickForge processes to switch authority back to JSON'
+    }
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  }
+} catch (error) {
+  exitError(error?.message || String(error))
+} finally {
+  await closeSqliteStorage().catch(() => {})
+}

package/server/maintenance/export-lan-access-v1.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { closeSqliteStorage, initializeSqliteStorage } from '../sqlite/database.mjs'
+import { createLanAccessRepository } from '../sqlite/lan-access-repository.mjs'
+import { buildLanAccessJsonSnapshot } from '../lan-access-cutover.mjs'
+import { readLanAccessStorageState } from '../lan-access-service.mjs'
+import { dataDir } from '../storage.mjs'
+
+// F11 Phase 3 offline authoritative LAN access export (shutdown-time only).
+// Mirrors export-share-v1.mjs in the independent lan-access storage domain:
+// refuses cutover_running and json_authoritative, runs quick_check +
+// verifyIntegrity + exportSnapshot with fail-closed count/digest checks, and
+// only renames the temporary file into place after re-reading and re-verifying
+// what was written. The exported config carries token hashes only (never the
+// raw secrets) and strips the repository-internal revision.
+const AUTHORITATIVE_PHASES = new Set(['sqlite_authoritative_json_pending', 'authoritative'])
+
+function outputPath() {
+  const argument = process.argv[2]
+  if (argument) return path.resolve(argument)
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  return path.join(process.cwd(), `quickforge-lan-access-${stamp}.json`)
+}
+
+const finalPath = outputPath()
+const temporaryPath = `${finalPath}.${process.pid}.${randomUUID()}.tmp`
+
+function publicConfig(config) {
+  const rest = { ...config }
+  delete rest.revision
+  return rest
+}
+
+try {
+  const storage = await initializeSqliteStorage({ dataDir })
+  storage.health({ quickCheck: true })
+  const repository = createLanAccessRepository(storage)
+  const state = readLanAccessStorageState()
+  if (state.phase === 'cutover_running') {
+    throw new Error('LAN access cutover is still running; stop all QuickForge processes and retry')
+  }
+  if (!AUTHORITATIVE_PHASES.has(state.phase)) {
+    throw new Error(`LAN access storage is ${state.phase}; authoritative export requires the SQLite cutover to be complete`)
+  }
+  const integrity = repository.verifyIntegrity({ quickCheck: true })
+  if (!integrity.ok) throw new Error('LAN access storage integrity verification failed')
+  const snapshot = repository.exportSnapshot()
+  if (snapshot.tokenCount !== integrity.count || snapshot.digest !== integrity.digest) {
+    throw new Error('LAN access backup count/digest verification failed')
+  }
+  const backup = {
+    app: 'quickforge',
+    version: 1,
+    exportedAt: new Date().toISOString(),
+    scope: 'lan-access',
+    includeSecrets: false,
+    lanAccessState: { phase: state.phase, count: snapshot.tokenCount, digest: snapshot.digest },
+    data: {
+      lanAccess: publicConfig(snapshot.config),
+    },
+  }
+  await fs.mkdir(path.dirname(finalPath), { recursive: true })
+  await fs.writeFile(temporaryPath, `${JSON.stringify(backup, null, 2)}\n`, 'utf8')
+  const verified = JSON.parse(await fs.readFile(temporaryPath, 'utf8'))
+  const recheck = buildLanAccessJsonSnapshot(verified.data?.lanAccess)
+  if (verified.lanAccessState?.count !== snapshot.tokenCount || verified.lanAccessState?.digest !== snapshot.digest
+    || recheck.tokenCount !== snapshot.tokenCount || recheck.digest !== snapshot.digest) {
+    throw new Error('LAN access export verification failed')
+  }
+  await fs.rename(temporaryPath, finalPath)
+  process.stdout.write(`${finalPath}\n`)
+} catch (error) {
+  await fs.rm(temporaryPath, { force: true }).catch(() => {})
+  process.stderr.write(`${error?.message || error}\n`)
+  process.exitCode = 1
+} finally {
+  await closeSqliteStorage().catch(() => {})
+}

package/server/maintenance/export-scheduled-runs-v1.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { closeSqliteStorage, initializeSqliteStorage } from '../sqlite/database.mjs'
+import { readScheduledTasksForBackup } from '../scheduled-runs-backup.mjs'
+import { readScheduledRunsState } from '../scheduled-runs-cutover.mjs'
+import { dataDir } from '../storage.mjs'
+
+function outputPath() {
+  const argument = process.argv[2]
+  if (argument) return path.resolve(argument)
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  return path.join(process.cwd(), `quickforge-scheduled-runs-${stamp}.json`)
+}
+
+const finalPath = outputPath()
+const temporaryPath = `${finalPath}.${process.pid}.${randomUUID()}.tmp`
+
+try {
+  const storage = await initializeSqliteStorage({ dataDir })
+  storage.health({ quickCheck: true })
+  const state = readScheduledRunsState(storage)
+  if (state.phase === 'cutover_running') throw new Error('Scheduled runs cutover is still running; stop all QuickForge processes and retry')
+  const scheduledTasks = await readScheduledTasksForBackup()
+  const backup = {
+    app: 'quickforge',
+    version: 1,
+    exportedAt: new Date().toISOString(),
+    scope: 'config',
+    includeSecrets: false,
+    data: { scheduledTasks },
+  }
+  await fs.mkdir(path.dirname(finalPath), { recursive: true })
+  await fs.writeFile(temporaryPath, `${JSON.stringify(backup, null, 2)}\n`, 'utf8')
+  JSON.parse(await fs.readFile(temporaryPath, 'utf8'))
+  await fs.rename(temporaryPath, finalPath)
+  process.stdout.write(`${finalPath}\n`)
+} catch (error) {
+  await fs.rm(temporaryPath, { force: true }).catch(() => {})
+  process.stderr.write(`${error?.message || error}\n`)
+  process.exitCode = 1
+} finally {
+  await closeSqliteStorage().catch(() => {})
+}