@camstack/server 0.1.3

package/src/api/core/addon-settings.router.ts

@@ -0,0 +1,124 @@
+/**
+ * Addon settings router — raw DB proxy for the common settings API.
+ *
+ * Exposes four protected procedures consumed by:
+ *   1. Forked addons (via the tRPC WSS client in `WorkerBootstrapService`)
+ *      to read/write their 3-level settings chain from the worker process.
+ *   2. Future UI flows that want to inspect/mutate addon settings through
+ *      a single well-typed endpoint.
+ *
+ * The router is deliberately thin — it does NOT perform schema-based
+ * resolver merging (defaults → global → per-device). That happens on the
+ * consumer side where the addon's `ConfigUISchema` is available:
+ *   - In-process addons: handled by `SettingsResolverService.createView()`
+ *     wired into `AddonContext.settings` during `createAddonContext()`.
+ *   - Forked addons: handled by the `AddonSettingsView` constructed inside
+ *     `WorkerBootstrapService`, which has access to the worker's local
+ *     addon schema.
+ *
+ * Introduced in session 5 Sprint 3a (worker-bootstrap cap-aware wiring).
+ */
+import { z } from 'zod'
+import type { ConfigService } from '../../core/config/config.service.js'
+import { trpcRouter, protectedProcedure } from '../trpc/trpc.middleware.js'
+
+const AddonSettingsRecordSchema = z.record(z.string(), z.unknown())
+
+const AddonIdInputSchema = z.object({
+  addonId: z.string(),
+})
+
+const AddonDeviceInputSchema = z.object({
+  addonId: z.string(),
+  deviceId: z.string(),
+})
+
+const UpdateGlobalInputSchema = z.object({
+  addonId: z.string(),
+  field: z.string(),
+  value: z.unknown(),
+})
+
+const UpdateDeviceInputSchema = z.object({
+  addonId: z.string(),
+  deviceId: z.string(),
+  field: z.string(),
+  value: z.unknown(),
+})
+
+const SuccessSchema = z.object({ success: z.literal(true) })
+
+const ReplaceGlobalInputSchema = z.object({
+  addonId: z.string(),
+  config: z.record(z.string(), z.unknown()),
+})
+
+export function createAddonSettingsRouter(cfg: ConfigService) {
+  return trpcRouter({
+    /**
+     * Read the addon-global settings record for the given addon.
+     * Returns the raw stored values (no defaults, no device overrides).
+     */
+    getGlobal: protectedProcedure
+      .input(AddonIdInputSchema)
+      .output(AddonSettingsRecordSchema)
+      .query(({ input }) => cfg.getAddonConfig(input.addonId)),
+
+    /**
+     * Read the per-device override record for the given addon × device.
+     * Returns the raw stored values (schema filtering happens on the
+     * consumer side at merge time).
+     */
+    getDeviceOverrides: protectedProcedure
+      .input(AddonDeviceInputSchema)
+      .output(AddonSettingsRecordSchema)
+      .query(({ input }) => cfg.getAddonDevice(input.addonId, input.deviceId)),
+
+    /**
+     * Update a single field in the addon-global settings record.
+     * Reads the current record, merges the new value, and writes back
+     * via `setAddonConfig` (bulk replace). Intended for small per-field
+     * writes from addon code; bulk updates should use a dedicated admin
+     * endpoint (not exposed here).
+     */
+    updateGlobal: protectedProcedure
+      .input(UpdateGlobalInputSchema)
+      .output(SuccessSchema)
+      .mutation(({ input }) => {
+        const current = cfg.getAddonConfig(input.addonId)
+        cfg.setAddonConfig(input.addonId, { ...current, [input.field]: input.value })
+        return { success: true as const }
+      }),
+
+    /**
+     * Update a single field in the per-device override record for the
+     * given addon × device. Merges with the existing overrides and
+     * writes back via `setAddonDevice`. Scope enforcement (dropping
+     * fields not declared as `scope: 'device'`) is the consumer's
+     * responsibility — we preserve the raw shape at this layer so the
+     * resolver contract remains symmetric with `getDeviceOverrides`.
+     */
+    updateDevice: protectedProcedure
+      .input(UpdateDeviceInputSchema)
+      .output(SuccessSchema)
+      .mutation(({ input }) => {
+        const current = cfg.getAddonDevice(input.addonId, input.deviceId)
+        cfg.setAddonDevice(input.addonId, input.deviceId, { ...current, [input.field]: input.value })
+        return { success: true as const }
+      }),
+
+    /**
+     * Replace the entire addon-global settings record in one call.
+     * Used by forked workers for `context.config.setAll()`. Unlike
+     * `updateGlobal` (single-field merge), this overwrites the full record.
+     * Admin-level write: only workers with valid hub tokens can call this.
+     */
+    replaceGlobal: protectedProcedure
+      .input(ReplaceGlobalInputSchema)
+      .output(SuccessSchema)
+      .mutation(({ input }) => {
+        cfg.setAddonConfig(input.addonId, input.config)
+        return { success: true as const }
+      }),
+  })
+}

package/src/api/core/agents.router.ts

@@ -0,0 +1,87 @@
+/**
+ * Agents router — fixed core API (not a capability).
+ *
+ * Thin binding over AgentRegistryService which now delegates to Moleculer
+ * for node discovery and health. Only role-assignment management and
+ * node listing remain; protocol endpoints (register, heartbeat, task
+ * dispatch) are handled natively by the Moleculer service mesh.
+ */
+import { z } from 'zod'
+import type { AgentRegistryService } from '../../core/agent/agent-registry.service.js'
+import type { MoleculerService } from '../../core/moleculer/moleculer.service.js'
+import {
+  trpcRouter, adminProcedure,
+} from '../trpc/trpc.middleware.js'
+
+const AgentRoleSchema = z.enum(['decoder', 'transcoder', 'detector', 'recorder'])
+
+export function createAgentsRouter(
+  ar: AgentRegistryService,
+  moleculer: MoleculerService,
+) {
+  return trpcRouter({
+    // ── Node listing (replaces listAgents / listConnected) ────────────
+    listNodes: adminProcedure
+      .input(z.void())
+      .query(async () => {
+        const items = await ar.listNodes()
+        // Spread to mutable copies: AgentListItem uses readonly arrays; Zod output schema uses mutable.
+        return items.map(a => ({
+          ...a,
+          info: {
+            ...a.info,
+            capabilities: [...a.info.capabilities],
+          },
+          status: {
+            ...a.status,
+            fps: { ...a.status.fps },
+            errors: [...a.status.errors],
+          },
+          subProcesses: [...a.subProcesses],
+        }))
+      }),
+
+    // ── Capability discovery (via Moleculer service list) ─────────────
+    getAgentCapabilities: adminProcedure
+      .input(z.void())
+      .query(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access -- moleculer.broker.call typing chain unresolvable; runtime shape validated by the cast below
+        const services = await moleculer.broker.call('$node.services', {}) as Array<{ name: string }>
+        const capSet = new Set<string>()
+        for (const svc of services) {
+          if (svc.name.startsWith('$')) continue
+          capSet.add(svc.name)
+        }
+        return [...capSet].sort()
+      }),
+
+    // ── Role assignments ──────────────────────────────────────────────
+    getAssignments: adminProcedure
+      .input(z.object({ cameraId: z.number().optional() }))
+      .query(({ input }) => ar.getAssignments(input.cameraId)),
+
+    setAssignment: adminProcedure
+      .input(z.object({
+        cameraId: z.number(),
+        role: AgentRoleSchema,
+        agentId: z.string(),
+        priority: z.enum(['primary', 'backup', 'overflow']),
+        rtspUrl: z.string().optional(),
+      }))
+      .mutation(({ input }) => ar.setAssignment(input as never)),
+
+    removeAssignment: adminProcedure
+      .input(z.object({
+        cameraId: z.number(),
+        role: AgentRoleSchema,
+      }))
+      .mutation(({ input }) => ar.removeAssignment(input.cameraId, input.role as never)),
+
+    activateBackup: adminProcedure
+      .input(z.object({
+        cameraId: z.number(),
+        role: AgentRoleSchema,
+      }))
+      .mutation(({ input }) => ar.activateBackup(input.cameraId, input.role as never)),
+  })
+}

package/src/api/core/auth.router.ts

@@ -0,0 +1,303 @@
+/**
+ * Auth router — core API for login/logout/me.
+ *
+ * Login validates credentials via the `user-management` capability
+ * (owned by the local-auth addon) and signs a JWT.
+ *
+ * JWT signing stays in the server — it's a transport-level concern
+ * (the server owns the secret and the HTTP session).
+ *
+ * External auth providers are listed via the `auth-provider` cap collection.
+ */
+import { z } from 'zod'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { AuthService } from '../../core/auth/auth.service.js'
+import { trpcRouter, publicProcedure, protectedProcedure } from '../trpc/trpc.middleware.js'
+
+/**
+ * Login response — discriminated on `requiresTotp`.
+ *
+ *   • `requiresTotp: false` (or absent in the legacy path): the
+ *     credentials were sufficient, `token` is the real session JWT.
+ *   • `requiresTotp: true`: the user has TOTP enrolled. `token` is a
+ *     short-lived (5 min) challenge token, NOT a session. The client
+ *     prompts for a 6-digit code and submits to `loginVerifyTotp`
+ *     with `{challengeToken, code}`. Only on success does the server
+ *     mint the real session.
+ */
+const LoginResultSchema = z.object({
+  token: z.string(),
+  user: z.object({
+    id: z.string(),
+    username: z.string(),
+    isAdmin: z.boolean(),
+  }),
+  requiresTotp: z.boolean().optional(),
+})
+
+const AuthProviderSummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  icon: z.string(),
+  flowType: z.string(),
+})
+
+/** Wire shape of the authenticated user returned by `auth.me`. */
+const MeSchema = z.object({
+  id: z.string(),
+  username: z.string(),
+  isAdmin: z.boolean(),
+  permissions: z.object({
+    isAdmin: z.boolean(),
+    allowedProviders: z.union([z.literal('*'), z.array(z.string())]),
+    allowedDevices: z.record(z.string(), z.unknown()),
+  }),
+  isApiKey: z.boolean(),
+  agentId: z.string().optional(),
+}).nullable()
+
+export function createAuthRouter(
+  auth: AuthService,
+  registry: CapabilityRegistry | null,
+) {
+  return trpcRouter({
+    login: publicProcedure
+      .input(z.object({ username: z.string(), password: z.string() }))
+      .output(LoginResultSchema)
+      .mutation(async ({ input }) => {
+        const userMgmt = registry?.getSingleton('user-management')
+        if (!userMgmt) {
+          // The local-auth addon owns this cap. When this fires the
+          // addon either failed to initialize or is still booting.
+          // Check the server log for `[hub/local-auth]` errors —
+          // common cause is a settings-store regression that breaks
+          // the `users` collection query path.
+          throw new Error(
+            'Login unavailable — `user-management` capability not registered. '
+            + 'The `local-auth` addon failed to initialize; check server logs '
+            + 'for an error tagged `[hub/local-auth]`.',
+          )
+        }
+
+        const user = await userMgmt.validateCredentials({ username: input.username, password: input.password })
+        if (!user) throw new Error('Invalid credentials')
+
+        // ── TOTP gate ────────────────────────────────────────────────
+        // After credentials validate, check whether the user has
+        // active 2FA enrollment. If yes, mint a SHORT-LIVED challenge
+        // token instead of the real session — the client must follow
+        // up via `loginVerifyTotp` with a valid 6-digit code before
+        // we hand out the actual JWT. The challenge token carries
+        // `kind: 'totp-challenge'` so it can't be replayed against
+        // protected endpoints (the auth middleware rejects anything
+        // without the standard session shape).
+        const totpStatus = typeof userMgmt.getTotpStatus === 'function'
+          ? await userMgmt.getTotpStatus({ userId: user.id })
+          : { enabled: false }
+        if (totpStatus.enabled) {
+          const challengeToken = auth.signTotpChallengeToken({
+            userId: user.id,
+            username: user.username,
+            isAdmin: user.isAdmin,
+          })
+          return {
+            token: challengeToken,
+            user: { id: user.id, username: user.username, isAdmin: user.isAdmin },
+            requiresTotp: true,
+          }
+        }
+
+        // Snapshot `scopes` into the JWT payload. Admins ignore the
+        // field (middleware bypass); for non-admins this drives the
+        // entire scope-access check until the user logs out + back in.
+        // setUserScopes mutations take effect on next login — old JWTs
+        // carry the snapshot from issue time. This is the standard JWT
+        // staleness tradeoff; if you need immediate revocation, force a
+        // logout from the admin UI.
+        const token = auth.signToken({
+          userId: user.id,
+          username: user.username,
+          isAdmin: user.isAdmin,
+          allowedProviders: user.allowedProviders ?? '*',
+          allowedDevices: user.allowedDevices ?? {},
+          scopes: user.scopes ?? [],
+        })
+        return {
+          token,
+          user: { id: user.id, username: user.username, isAdmin: user.isAdmin },
+          requiresTotp: false,
+        }
+      }),
+
+    /**
+     * Second leg of the 2FA login. Accepts the challenge token minted
+     * by `login` (when `requiresTotp: true`) plus the operator-entered
+     * 6-digit code. Re-validates both, then mints the real session.
+     *
+     * Failure modes:
+     *   • Invalid/expired challenge token → 401 (session timed out,
+     *     restart login).
+     *   • Code doesn't match → 401 (try again with a fresh code from
+     *     the authenticator app).
+     *   • User vanished between leg 1 and leg 2 → 401 (operator was
+     *     deleted concurrently — rare).
+     */
+    loginVerifyTotp: publicProcedure
+      .input(z.object({ challengeToken: z.string(), code: z.string() }))
+      .output(LoginResultSchema)
+      .mutation(async ({ input }) => {
+        const claims = auth.verifyTotpChallengeToken(input.challengeToken)
+        if (!claims) {
+          throw new Error('Invalid or expired TOTP challenge — please re-enter your password')
+        }
+        const userMgmt = registry?.getSingleton('user-management')
+        if (!userMgmt) {
+          throw new Error('Login unavailable — `user-management` capability not registered')
+        }
+        const verify = typeof userMgmt.verifyTotp === 'function'
+          ? await userMgmt.verifyTotp({ userId: claims.userId, code: input.code.trim() })
+          : { valid: false }
+        if (!verify.valid) {
+          throw new Error('Invalid TOTP code')
+        }
+        // Re-fetch the user record so scopes / allowedDevices reflect
+        // any admin change made between the two legs. Without this we
+        // could mint a stale-scope session.
+        const fresh = typeof userMgmt.listUsers === 'function'
+          ? (await userMgmt.listUsers()).find((u) => u.id === claims.userId)
+          : null
+        if (!fresh) {
+          throw new Error('User no longer exists')
+        }
+        const sessionToken = auth.signToken({
+          userId: fresh.id,
+          username: fresh.username,
+          isAdmin: fresh.isAdmin,
+          allowedProviders: fresh.allowedProviders ?? '*',
+          allowedDevices: fresh.allowedDevices ?? {},
+          scopes: fresh.scopes ?? [],
+        })
+        return {
+          token: sessionToken,
+          user: { id: fresh.id, username: fresh.username, isAdmin: fresh.isAdmin },
+          requiresTotp: false,
+        }
+      }),
+
+    me: protectedProcedure
+      .input(z.void())
+      .output(MeSchema)
+      .query(({ ctx }) => ctx.user),
+
+    // ── Self-service profile operations ───────────────────────────────
+    //
+    // These route through the `user-management` capability provider but
+    // bind `userId` to the CALLER's session identity (`ctx.user.id`)
+    // — i.e. every authenticated user can manage THEIR OWN password and
+    // TOTP enrollment, without the admin gate that the corresponding
+    // cap methods enforce on the trpc layer.
+    //
+    // Provider methods themselves don't check admin status, so calling
+    // them directly here is fine. The trpc admin-gate on the cap router
+    // exists only to block third-party tampering — operators acting on
+    // themselves bypass it intentionally.
+    changeOwnPassword: protectedProcedure
+      .input(z.object({
+        currentPassword: z.string().min(1),
+        newPassword: z.string().min(8),
+      }))
+      .output(z.object({ success: z.literal(true) }))
+      .mutation(async ({ input, ctx }) => {
+        const userMgmt = registry?.getSingleton('user-management') as
+          | {
+              validateCredentials: (i: { username: string; password: string }) => Promise<{ id: string } | null>
+              resetPassword: (i: { id: string; newPassword: string }) => Promise<{ success: true }>
+            }
+          | null
+          | undefined
+        if (!userMgmt) throw new Error('user-management capability not available')
+        if (!ctx.user) throw new Error('Not authenticated')
+        // Re-validate the current password against the live store to
+        // confirm session identity → password ownership match. Stops a
+        // stolen session-token from rotating credentials silently.
+        const ok = await userMgmt.validateCredentials({ username: ctx.user.username, password: input.currentPassword })
+        if (!ok) throw new Error('Current password is incorrect')
+        await userMgmt.resetPassword({ id: ctx.user.id, newPassword: input.newPassword })
+        return { success: true as const }
+      }),
+
+    setupOwnTotp: protectedProcedure
+      .input(z.void())
+      .output(z.object({ secret: z.string(), otpauthUrl: z.string() }))
+      .mutation(async ({ ctx }) => {
+        const userMgmt = registry?.getSingleton('user-management') as
+          | { setupTotp: (i: { userId: string }) => Promise<{ secret: string; otpauthUrl: string }> }
+          | null
+          | undefined
+        if (!userMgmt) throw new Error('user-management capability not available')
+        if (!ctx.user) throw new Error('Not authenticated')
+        return userMgmt.setupTotp({ userId: ctx.user.id })
+      }),
+
+    confirmOwnTotp: protectedProcedure
+      .input(z.object({ code: z.string().min(1) }))
+      .output(z.object({ success: z.literal(true) }))
+      .mutation(async ({ input, ctx }) => {
+        const userMgmt = registry?.getSingleton('user-management') as
+          | { confirmTotp: (i: { userId: string; code: string }) => Promise<{ success: true }> }
+          | null
+          | undefined
+        if (!userMgmt) throw new Error('user-management capability not available')
+        if (!ctx.user) throw new Error('Not authenticated')
+        return userMgmt.confirmTotp({ userId: ctx.user.id, code: input.code })
+      }),
+
+    disableOwnTotp: protectedProcedure
+      .input(z.void())
+      .output(z.object({ success: z.literal(true) }))
+      .mutation(async ({ ctx }) => {
+        const userMgmt = registry?.getSingleton('user-management') as
+          | { disableTotp: (i: { userId: string }) => Promise<{ success: true }> }
+          | null
+          | undefined
+        if (!userMgmt) throw new Error('user-management capability not available')
+        if (!ctx.user) throw new Error('Not authenticated')
+        return userMgmt.disableTotp({ userId: ctx.user.id })
+      }),
+
+    getOwnTotpStatus: protectedProcedure
+      .input(z.void())
+      .output(z.object({ enabled: z.boolean(), confirmedAt: z.number().nullable() }))
+      .query(async ({ ctx }) => {
+        const userMgmt = registry?.getSingleton('user-management') as
+          | { getTotpStatus: (i: { userId: string }) => Promise<{ enabled: boolean; confirmedAt: number | null }> }
+          | null
+          | undefined
+        if (!userMgmt || !ctx.user) return { enabled: false, confirmedAt: null }
+        return userMgmt.getTotpStatus({ userId: ctx.user.id })
+      }),
+
+    logout: protectedProcedure
+      .input(z.void())
+      .output(z.object({ success: z.literal(true) }))
+      .mutation(() => ({ success: true as const })),
+
+    listProviders: publicProcedure
+      .input(z.void())
+      .output(z.array(AuthProviderSummarySchema).readonly())
+      .query(() => {
+        if (!registry) return []
+        // Validate each auth-provider entry independently. A single
+        // malformed entry (e.g. an auth addon that registers without an
+        // `icon`) must NOT sink the whole array through the tRPC output
+        // validator — that would 500 the query and lock every login
+        // method out of the UI. Drop the bad entry, keep the rest.
+        const out: z.infer<typeof AuthProviderSummarySchema>[] = []
+        for (const entry of registry.getCollection('auth-provider')) {
+          const parsed = AuthProviderSummarySchema.safeParse(entry)
+          if (parsed.success) out.push(parsed.data)
+        }
+        return out
+      }),
+  })
+}