@camstack/server 0.1.3

package/src/api/bridge-addons.router.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod'
+import { TRPCError } from '@trpc/server'
+import { protectedProcedure, adminProcedure, trpcRouter } from './trpc/trpc.middleware'
+import type { AddonBridgeService } from '../core/addon-bridge/addon-bridge.service'
+import type { AddonSearchService } from '../core/addon/addon-search.service'
+import type { AddonRegistryService } from '../core/addon/addon-registry.service'
+import type { ToastService } from '@camstack/core'
+
+export function createBridgeAddonsRouter(
+  bridge: AddonBridgeService,
+  addonSearch: AddonSearchService,
+  addonRegistry?: AddonRegistryService,
+  toastService?: ToastService,
+) {
+  return trpcRouter({
+    /** List all addon packages installed in the addons directory */
+    listPackages: protectedProcedure.query(() => {
+      const installer = bridge.getInstaller()
+      if (!installer) return []
+      return installer.listInstalled()
+    }),
+
+    /** List all available addons across all loaded packages */
+    listAddons: protectedProcedure.query(() => {
+      return bridge.listAvailableAddons().map((id) => {
+        const addon = bridge.getLoader().getAddon(id)
+        return {
+          id,
+          packageName: addon?.packageName ?? 'unknown',
+          slot: addon?.declaration.slot ?? null,
+        }
+      })
+    }),
+
+    /** Install a community addon package from npm */
+    installPackage: adminProcedure
+      .input(z.object({ packageName: z.string(), version: z.string().optional() }))
+      .mutation(async ({ input }) => {
+        const installer = bridge.getInstaller()
+        if (!installer) {
+          throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: 'Addon installer not available — bridge may have failed to initialize',
+          })
+        }
+        await installer.install(input.packageName, input.version)
+        await bridge.reloadPackages()
+        const result = addonRegistry ? await addonRegistry.loadNewAddons() : { loaded: [], failed: [] }
+        toastService?.broadcast({
+          title: 'Addon Installed',
+          message: `${input.packageName} installed successfully${result.loaded.length ? ` (${result.loaded.join(', ')})` : ''}`,
+          severity: result.failed.length ? 'warning' : 'info',
+        })
+        return { success: true, loaded: result.loaded, failed: result.failed }
+      }),
+
+    /** Uninstall a community addon package */
+    uninstallPackage: adminProcedure
+      .input(z.object({ packageName: z.string() }))
+      .mutation(async ({ input }) => {
+        // Server-side guard: prevent uninstalling required packages.
+        // After Phase D bundle merge, the pipeline-related packages
+        // (stream-broker, detection-pipeline, motion-wasm, decoders,
+        // audio) all live in @camstack/addon-pipeline.
+        const REQUIRED = new Set([
+          '@camstack/core',
+          '@camstack/addon-pipeline',
+          '@camstack/addon-pipeline-orchestrator',
+          '@camstack/addon-post-analysis',
+          '@camstack/addon-admin-ui',
+        ])
+        if (REQUIRED.has(input.packageName)) {
+          throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: `Package ${input.packageName} is required and cannot be uninstalled`,
+          })
+        }
+
+        const installer = bridge.getInstaller()
+        if (!installer) {
+          throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: 'Addon installer not available — bridge may have failed to initialize',
+          })
+        }
+        await installer.uninstall(input.packageName)
+        await bridge.reloadPackages()
+        if (addonRegistry) await addonRegistry.loadNewAddons()
+        toastService?.broadcast({
+          title: 'Addon Uninstalled',
+          message: `${input.packageName} has been removed`,
+          severity: 'info',
+        })
+        return { success: true }
+      }),
+
+    /** Force reload all addon packages (re-scan directories, re-import modules) */
+    reloadPackages: adminProcedure.mutation(async () => {
+      await bridge.reloadPackages()
+      return { success: true, message: 'Addon packages reloaded' }
+    }),
+
+    /** Search npm for available CamStack addons */
+    searchAvailable: protectedProcedure
+      .input(z.object({ query: z.string().optional() }).optional())
+      .query(async ({ input }) => {
+        const results = await addonSearch.searchAddons(input?.query)
+
+        // Enrich with install status from locally installed packages
+        const installed = bridge.getInstaller()?.listInstalled() ?? []
+        const installedMap = new Map(installed.map((p) => [p.name, p.version]))
+
+        return results.map((r) => ({
+          ...r,
+          installed: installedMap.has(r.name),
+          installedVersion: installedMap.get(r.name),
+        }))
+      }),
+  })
+}

package/src/api/capabilities.router.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod'
+import { TRPCError } from '@trpc/server'
+import { adminProcedure, trpcRouter } from './trpc/trpc.middleware'
+import type { AddonRegistryService } from '../core/addon/addon-registry.service'
+import type { ConfigService } from '../core/config/config.service'
+import type { LoggingService } from '../core/logging/logging.service'
+import { isInfraCapability } from '@camstack/kernel'
+import { collectionPreferenceKey, persistCollectionDisabled } from './core/collection-preference'
+
+// ─── Zod Schemas ───────────────────────────────────────────────────────────
+
+const setPreferenceInput = z.discriminatedUnion('mode', [
+  z.object({
+    mode: z.literal('singleton'),
+    capability: z.string(),
+    addonId: z.string(),
+  }),
+  z.object({
+    mode: z.literal('collection'),
+    capability: z.string(),
+    addonId: z.string(),
+    enabled: z.boolean(),
+  }),
+])
+
+// ─── Router ────────────────────────────────────────────────────────────────
+
+export function createCapabilitiesRouter(
+  addonRegistry: AddonRegistryService,
+  configService: ConfigService,
+  loggingService: LoggingService,
+) {
+  const logger = loggingService.createLogger('CapabilitiesRouter')
+
+  /** Build enriched provider details from addon metadata */
+  function getProviderDetails(addonIds: readonly string[]) {
+    const allAddons = addonRegistry.listAllAddons()
+    return addonIds.map((addonId) => {
+      const addon = allAddons.find((a) => a.manifest.id === addonId)
+      return {
+        addonId,
+        displayName: addon?.manifest.name ?? addonId,
+        packageName: addon?.manifest.packageName ?? addonId,
+      }
+    })
+  }
+
+  return trpcRouter({
+    // ─── List all capabilities with enriched metadata ──────────────────
+
+    list: adminProcedure.query(() => {
+      const registry = addonRegistry.getCapabilityRegistry()
+      const caps = registry.listCapabilities()
+      return caps.map((cap) => ({
+        ...cap,
+        providerDetails: getProviderDetails(cap.providers),
+        isInfra: isInfraCapability(cap.name),
+      }))
+    }),
+
+    // ─── Get current preference for a capability ──────────────────────
+
+    getPreference: adminProcedure
+      .input(z.object({ capability: z.string() }))
+      .query(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        const mode = registry.getMode(input.capability)
+        if (!mode) return null
+
+        if (mode === 'singleton') {
+          const addonId = configService.get<string>(`capabilities.singleton.${input.capability}`)
+          return {
+            capability: input.capability,
+            mode: mode as 'singleton',
+            preference: addonId ? { addonId } : null,
+          }
+        }
+
+        // collection
+        const raw = configService.get<string>(collectionPreferenceKey(input.capability))
+        let disabled: string[] = []
+        if (raw) {
+          try {
+            const parsed = JSON.parse(raw) as { disabled?: string[] }
+            disabled = Array.isArray(parsed.disabled) ? parsed.disabled : []
+          } catch { /* ignore malformed */ }
+        }
+        return {
+          capability: input.capability,
+          mode: mode as 'collection',
+          preference: { disabled },
+        }
+      }),
+
+    // ─── Set preference (singleton switch or collection toggle) ───────
+
+    setPreference: adminProcedure
+      .input(setPreferenceInput)
+      .mutation(async ({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+
+        if (input.mode === 'singleton') {
+          const { capability, addonId } = input
+          const caps = registry.listCapabilities()
+          const cap = caps.find((c) => c.name === capability)
+          if (!cap) throw new TRPCError({ code: 'NOT_FOUND', message: `Unknown capability: ${capability}` })
+          if (cap.mode !== 'singleton') throw new TRPCError({ code: 'BAD_REQUEST', message: `"${capability}" is not a singleton` })
+          if (!cap.providers.includes(addonId)) {
+            throw new TRPCError({ code: 'BAD_REQUEST', message: `Provider "${addonId}" is not registered for "${capability}"` })
+          }
+
+          const requiresRestart = isInfraCapability(capability)
+
+          if (!requiresRestart) {
+            // Hot-swap at runtime
+            await registry.setActiveSingleton(capability, addonId, true)
+          }
+
+          // Persist preference
+          configService.set(`capabilities.singleton.${capability}`, addonId)
+          logger.info('Singleton preference set', { tags: { addonId }, meta: { capability, requiresRestart } })
+
+          return { success: true, requiresRestart }
+        }
+
+        // collection toggle
+        const { capability, addonId, enabled } = input
+        const caps = registry.listCapabilities()
+        const cap = caps.find((c) => c.name === capability)
+        if (!cap) throw new TRPCError({ code: 'NOT_FOUND', message: `Unknown capability: ${capability}` })
+        if (cap.mode !== 'collection') throw new TRPCError({ code: 'BAD_REQUEST', message: `"${capability}" is not a collection` })
+        if (!cap.providers.includes(addonId)) {
+          throw new TRPCError({ code: 'BAD_REQUEST', message: `Provider "${addonId}" is not registered for "${capability}"` })
+        }
+
+        if (enabled) {
+          registry.enableCollectionProvider(capability, addonId)
+        } else {
+          registry.disableCollectionProvider(capability, addonId)
+        }
+
+        // Persist disabled list via the shared canonical writer.
+        const updatedCap = registry.listCapabilities().find((c) => c.name === capability)
+        persistCollectionDisabled(configService, capability, updatedCap?.disabledProviders ?? [])
+        logger.info('Collection provider toggled', { tags: { addonId }, meta: { capability, enabled } })
+
+        return { success: true, requiresRestart: false }
+      }),
+
+    // ─── Reset preference to default ──────────────────────────────────
+
+    resetPreference: adminProcedure
+      .input(z.object({ capability: z.string() }))
+      .mutation(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        const mode = registry.getMode(input.capability)
+        if (!mode) throw new TRPCError({ code: 'NOT_FOUND', message: `Unknown capability: ${input.capability}` })
+
+        if (mode === 'singleton') {
+          configService.set(`capabilities.singleton.${input.capability}`, null)
+          logger.info('Singleton preference reset (takes effect on restart)', { meta: { capability: input.capability } })
+          return { success: true, requiresRestart: true }
+        }
+
+        // collection: re-enable all disabled providers
+        const caps = registry.listCapabilities()
+        const cap = caps.find((c) => c.name === input.capability)
+        if (cap) {
+          for (const addonId of cap.disabledProviders) {
+            registry.enableCollectionProvider(input.capability, addonId)
+          }
+        }
+        configService.set(`capabilities.collection.${input.capability}`, null)
+        logger.info('Collection preference reset (all providers re-enabled)', { meta: { capability: input.capability } })
+        return { success: true, requiresRestart: false }
+      }),
+
+    // ─── Per-device overrides (existing, unchanged) ───────────────────
+
+    listCapabilities: adminProcedure.query(() => {
+      const registry = addonRegistry.getCapabilityRegistry()
+      return registry.listCapabilities()
+    }),
+
+    setDeviceCapability: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string(), addonId: z.string() }))
+      .mutation(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        registry.setDeviceOverride(input.deviceId, input.capability, input.addonId)
+        logger.info('Device capability override set', { tags: { deviceId: Number(input.deviceId), addonId: input.addonId }, meta: { capability: input.capability } })
+      }),
+
+    clearDeviceCapability: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string() }))
+      .mutation(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        registry.clearDeviceOverride(input.deviceId, input.capability)
+        logger.info('Device capability override cleared', { tags: { deviceId: Number(input.deviceId) }, meta: { capability: input.capability } })
+      }),
+
+    getDeviceCapabilities: adminProcedure
+      .input(z.object({ deviceId: z.string() }))
+      .output(z.record(z.string(), z.string()))
+      .query(({ input }): Record<string, string> => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        const overrides = registry.getDeviceOverrides(input.deviceId)
+        return Object.fromEntries(overrides) as Record<string, string>
+      }),
+
+    setDeviceCollectionFilter: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string(), addonIds: z.array(z.string()) }))
+      .mutation(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        registry.setDeviceCollectionFilter(input.deviceId, input.capability, input.addonIds)
+        logger.info('Device collection filter set', { tags: { deviceId: Number(input.deviceId) }, meta: { capability: input.capability, addonIds: input.addonIds } })
+      }),
+
+    clearDeviceCollectionFilter: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string() }))
+      .mutation(({ input }) => {
+        const registry = addonRegistry.getCapabilityRegistry()
+        registry.clearDeviceCollectionFilter(input.deviceId, input.capability)
+        logger.info('Device collection filter cleared', { tags: { deviceId: Number(input.deviceId) }, meta: { capability: input.capability } })
+      }),
+  })
+}

package/src/api/core/__tests__/auth-router-totp.spec.ts

@@ -0,0 +1,256 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return -- mock factories cross typed boundaries */
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createAuthRouter } from '../auth.router.js'
+import { AuthService } from '../../../core/auth/auth.service.js'
+
+/**
+ * Two-phase TOTP login flow tests for `auth.router`. Focus on the
+ * cap-router contracts the SDK + admin-ui depend on:
+ *
+ *   • `login` returns `requiresTotp: true` + a short-lived challenge
+ *     token when the user has TOTP enrolled.
+ *   • `login` returns a regular session token when the user has NO
+ *     TOTP (backwards compat).
+ *   • `loginVerifyTotp` validates the challenge token + code and
+ *     mints the real session JWT.
+ *   • Failure paths: wrong code, expired/forged challenge, missing
+ *     user, missing user-management cap.
+ */
+
+interface MockUser {
+  id: string
+  username: string
+  isAdmin: boolean
+  passwordHash: string
+  allowedProviders: string | string[]
+  allowedDevices: Record<string, unknown>
+  scopes: unknown[]
+}
+
+interface MockUserManagement {
+  validateCredentials: ReturnType<typeof vi.fn>
+  getTotpStatus: ReturnType<typeof vi.fn>
+  verifyTotp: ReturnType<typeof vi.fn>
+  listUsers: ReturnType<typeof vi.fn>
+}
+
+function makeUser(overrides: Partial<MockUser> = {}): MockUser {
+  return {
+    id: 'u-1',
+    username: 'alice',
+    isAdmin: false,
+    passwordHash: 'hashed',
+    allowedProviders: '*',
+    allowedDevices: {},
+    scopes: [],
+    ...overrides,
+  }
+}
+
+function makeUserMgmt(overrides: Partial<MockUserManagement> = {}): MockUserManagement {
+  return {
+    validateCredentials: vi.fn(),
+    getTotpStatus: vi.fn(async () => ({ enabled: false, confirmedAt: null })),
+    verifyTotp: vi.fn(async () => ({ valid: true })),
+    listUsers: vi.fn(async () => [makeUser()]),
+    ...overrides,
+  }
+}
+
+function makeConfig(overrides: Record<string, unknown> = {}): { get<T>(p: string): T; update(s: string, d: Record<string, unknown>): void } {
+  const store: Record<string, unknown> = { 'auth.jwtSecret': 'unit-test-secret', ...overrides }
+  return {
+    get<T>(path: string): T { return store[path] as T },
+    update(_section: string, _data: Record<string, unknown>): void { /* no-op */ },
+  }
+}
+
+function makeRegistry(userMgmt: MockUserManagement): { getSingleton: (name: string) => unknown | null } {
+  return {
+    getSingleton: (name: string) => (name === 'user-management' ? userMgmt : null),
+  }
+}
+
+/** Invoke a tRPC procedure directly via the router's internal API. */
+async function callProc(router: ReturnType<typeof createAuthRouter>, name: 'login' | 'loginVerifyTotp', input: unknown): Promise<unknown> {
+  const caller = router.createCaller({} as never)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const fn = (caller as any)[name]
+  return fn(input)
+}
+
+describe('auth.router — TOTP gate', () => {
+  let auth: AuthService
+  let userMgmt: MockUserManagement
+  let registry: ReturnType<typeof makeRegistry>
+
+  beforeEach(() => {
+    auth = new AuthService(makeConfig() as never)
+    userMgmt = makeUserMgmt()
+    registry = makeRegistry(userMgmt)
+  })
+
+  describe('login (phase 1)', () => {
+    it('returns a regular session token + requiresTotp:false when user has NO TOTP', async () => {
+      const u = makeUser()
+      userMgmt.validateCredentials.mockResolvedValueOnce(u)
+      userMgmt.getTotpStatus.mockResolvedValueOnce({ enabled: false, confirmedAt: null })
+
+      const router = createAuthRouter(auth, registry as never)
+      const result = await callProc(router, 'login', { username: 'alice', password: 'pw' }) as {
+        token: string
+        user: { id: string; username: string; isAdmin: boolean }
+        requiresTotp?: boolean
+      }
+
+      expect(result.requiresTotp).toBe(false)
+      expect(result.user).toEqual({ id: 'u-1', username: 'alice', isAdmin: false })
+      // The token verifies as a regular session token (NOT a challenge).
+      const verified = auth.verifyToken(result.token)
+      expect(verified.userId).toBe('u-1')
+      // verifyTotpChallengeToken should NOT recognize a regular session token.
+      expect(auth.verifySsoBridgeToken(result.token)).toBeNull()
+    })
+
+    it('returns a challenge token + requiresTotp:true when user HAS TOTP', async () => {
+      const u = makeUser()
+      userMgmt.validateCredentials.mockResolvedValueOnce(u)
+      userMgmt.getTotpStatus.mockResolvedValueOnce({ enabled: true, confirmedAt: Date.now() })
+
+      const router = createAuthRouter(auth, registry as never)
+      const result = await callProc(router, 'login', { username: 'alice', password: 'pw' }) as {
+        token: string
+        user: { id: string; username: string; isAdmin: boolean }
+        requiresTotp?: boolean
+      }
+
+      expect(result.requiresTotp).toBe(true)
+      // The challenge token MUST NOT verify as a session JWT — it has
+      // `kind: 'totp-challenge'` and the standard verifyToken expects
+      // the session shape (it'd throw or return garbage).
+      const challengeClaims = auth.verifyTotpChallengeToken(result.token)
+      expect(challengeClaims).not.toBeNull()
+      expect(challengeClaims!.userId).toBe('u-1')
+      expect(challengeClaims!.isAdmin).toBe(false)
+    })
+
+    it('rejects invalid credentials', async () => {
+      userMgmt.validateCredentials.mockResolvedValueOnce(null)
+      const router = createAuthRouter(auth, registry as never)
+      await expect(callProc(router, 'login', { username: 'alice', password: 'wrong' })).rejects.toThrow('Invalid credentials')
+    })
+
+    it('throws when user-management cap is unregistered (boot failure)', async () => {
+      const emptyRegistry = { getSingleton: () => null } as never
+      const router = createAuthRouter(auth, emptyRegistry)
+      await expect(callProc(router, 'login', { username: 'alice', password: 'pw' })).rejects.toThrow(/user-management.*capability not registered/)
+    })
+
+    it('falls through to session-token branch when getTotpStatus method is absent (older user-mgmt builds)', async () => {
+      const u = makeUser()
+      const legacyMgmt = {
+        validateCredentials: vi.fn().mockResolvedValueOnce(u),
+        // getTotpStatus deliberately undefined
+        verifyTotp: vi.fn(),
+        listUsers: vi.fn(),
+      }
+      const router = createAuthRouter(auth, makeRegistry(legacyMgmt as never) as never)
+      const result = await callProc(router, 'login', { username: 'alice', password: 'pw' }) as { requiresTotp?: boolean }
+      expect(result.requiresTotp).toBe(false)
+    })
+  })
+
+  describe('loginVerifyTotp (phase 2)', () => {
+    it('mints the real session JWT when challenge + code are both valid', async () => {
+      const u = makeUser({ scopes: [{ type: 'category', target: 'storage', access: ['view'] }] })
+      userMgmt.verifyTotp.mockResolvedValueOnce({ valid: true })
+      userMgmt.listUsers.mockResolvedValueOnce([u])
+
+      const challengeToken = auth.signTotpChallengeToken({
+        userId: u.id,
+        username: u.username,
+        isAdmin: u.isAdmin,
+      })
+
+      const router = createAuthRouter(auth, registry as never)
+      const result = await callProc(router, 'loginVerifyTotp', { challengeToken, code: '123456' }) as {
+        token: string
+        user: { id: string; username: string; isAdmin: boolean }
+        requiresTotp?: boolean
+      }
+
+      expect(result.requiresTotp).toBe(false)
+      expect(result.user.id).toBe('u-1')
+      // Session JWT verifies + carries the user's scopes snapshot.
+      const decoded = auth.verifyToken(result.token)
+      expect(decoded.userId).toBe('u-1')
+    })
+
+    it('rejects an invalid/expired challenge token', async () => {
+      const router = createAuthRouter(auth, registry as never)
+      await expect(
+        callProc(router, 'loginVerifyTotp', { challengeToken: 'not.a.real.jwt', code: '123456' }),
+      ).rejects.toThrow(/Invalid or expired TOTP challenge/)
+    })
+
+    it('rejects a forged challenge token (signed with wrong secret)', async () => {
+      const other = new AuthService(makeConfig({ 'auth.jwtSecret': 'attacker-secret' }) as never)
+      const forged = other.signTotpChallengeToken({ userId: 'u-1', username: 'alice', isAdmin: true })
+      const router = createAuthRouter(auth, registry as never)
+      await expect(
+        callProc(router, 'loginVerifyTotp', { challengeToken: forged, code: '000000' }),
+      ).rejects.toThrow(/Invalid or expired TOTP challenge/)
+    })
+
+    it('rejects a session token reused as a challenge token (wrong kind)', async () => {
+      const sessionTok = auth.signToken({
+        userId: 'u-1',
+        username: 'alice',
+        isAdmin: true,
+        allowedProviders: '*',
+        allowedDevices: {},
+      })
+      const router = createAuthRouter(auth, registry as never)
+      await expect(
+        callProc(router, 'loginVerifyTotp', { challengeToken: sessionTok, code: '000000' }),
+      ).rejects.toThrow(/Invalid or expired TOTP challenge/)
+    })
+
+    it('rejects a wrong 6-digit code', async () => {
+      userMgmt.verifyTotp.mockResolvedValueOnce({ valid: false })
+      const challengeToken = auth.signTotpChallengeToken({ userId: 'u-1', username: 'alice', isAdmin: false })
+      const router = createAuthRouter(auth, registry as never)
+      await expect(
+        callProc(router, 'loginVerifyTotp', { challengeToken, code: '000000' }),
+      ).rejects.toThrow(/Invalid TOTP code/)
+    })
+
+    it('rejects when the user vanishes between legs (deleted concurrently)', async () => {
+      userMgmt.verifyTotp.mockResolvedValueOnce({ valid: true })
+      // The fresh listUsers() call returns nothing — user was deleted.
+      userMgmt.listUsers.mockResolvedValueOnce([])
+      const challengeToken = auth.signTotpChallengeToken({ userId: 'ghost', username: 'alice', isAdmin: false })
+      const router = createAuthRouter(auth, registry as never)
+      await expect(
+        callProc(router, 'loginVerifyTotp', { challengeToken, code: '123456' }),
+      ).rejects.toThrow(/User no longer exists/)
+    })
+
+    it('uses the FRESHLY fetched user record (scope changes pick up immediately)', async () => {
+      // Issue challenge for u-1 with empty scopes (the in-token snapshot).
+      const challengeToken = auth.signTotpChallengeToken({ userId: 'u-1', username: 'alice', isAdmin: false })
+      // Between the two legs, an admin granted u-1 a new scope.
+      userMgmt.verifyTotp.mockResolvedValueOnce({ valid: true })
+      userMgmt.listUsers.mockResolvedValueOnce([
+        makeUser({ scopes: [{ type: 'category', target: 'addon', access: ['view'] }] }),
+      ])
+      const router = createAuthRouter(auth, registry as never)
+      const result = await callProc(router, 'loginVerifyTotp', { challengeToken, code: '123456' }) as { token: string }
+      const decoded = auth.verifyToken(result.token)
+      // The fresh scope is in the minted session JWT, not the snapshot
+      // from the (potentially stale) password leg.
+      const scopes = (decoded as { scopes?: unknown[] }).scopes
+      expect(scopes).toHaveLength(1)
+    })
+  })
+})