@camstack/server 0.1.3

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

@@ -0,0 +1,142 @@
+/**
+ * Settings backend router — tRPC proxy for ISettingsBackend operations.
+ *
+ * Exposes the core collection-based operations (get, set, query, insert,
+ * update, delete, count, isEmpty) so forked worker addons can use
+ * context.settingsBackend via tRPC instead of requiring in-process access
+ * to the SQLite database.
+ *
+ * Introduced for Task 11 — TrpcSettingsBackend for forked workers.
+ */
+import { z } from 'zod'
+import type { ISettingsBackend } from '@camstack/types'
+import { trpcRouter, protectedProcedure } from '../trpc/trpc.middleware.js'
+
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+
+const CollectionKeySchema = z.object({
+  collection: z.string(),
+  key: z.string(),
+})
+
+const SetValueSchema = z.object({
+  collection: z.string(),
+  key: z.string(),
+  value: z.unknown(),
+})
+
+const QueryFilterSchema = z.object({
+  where: z.record(z.string(), z.unknown()).optional(),
+  whereIn: z.record(z.string(), z.array(z.unknown())).optional(),
+  whereBetween: z.record(z.string(), z.tuple([z.unknown(), z.unknown()])).optional(),
+  orderBy: z.object({
+    field: z.string(),
+    direction: z.enum(['asc', 'desc']),
+  }).optional(),
+  limit: z.number().optional(),
+  offset: z.number().optional(),
+}).optional()
+
+const QueryInputSchema = z.object({
+  collection: z.string(),
+  filter: QueryFilterSchema,
+})
+
+const InsertInputSchema = z.object({
+  collection: z.string(),
+  record: z.object({
+    id: z.string(),
+    data: z.record(z.string(), z.unknown()),
+  }),
+})
+
+const UpdateInputSchema = z.object({
+  collection: z.string(),
+  id: z.string(),
+  data: z.record(z.string(), z.unknown()),
+})
+
+const CountInputSchema = z.object({
+  collection: z.string(),
+  filter: QueryFilterSchema,
+})
+
+const IsEmptyInputSchema = z.object({
+  collection: z.string(),
+})
+
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+
+export function createSettingsBackendRouter(
+  getBackend: () => ISettingsBackend | null,
+) {
+  const requireBackend = (): ISettingsBackend => {
+    const backend = getBackend()
+    if (!backend) {
+      throw new Error('Settings backend not available — settings-store addon may not be initialized yet')
+    }
+    return backend
+  }
+
+  return trpcRouter({
+    get: protectedProcedure
+      .input(CollectionKeySchema)
+      .query(async ({ input }) => {
+        const result = await requireBackend().get(input)
+        return { value: result }
+      }),
+
+    set: protectedProcedure
+      .input(SetValueSchema)
+      .mutation(async ({ input }) => {
+        await requireBackend().set({ collection: input.collection, key: input.key, value: input.value })
+        return { success: true as const }
+      }),
+
+    query: protectedProcedure
+      .input(QueryInputSchema)
+      .query(async ({ input }) => {
+        const records = await requireBackend().query({ collection: input.collection, filter: input.filter ?? undefined })
+        return { records: records.map(r => ({ id: r.id, data: r.data })) }
+      }),
+
+    insert: protectedProcedure
+      .input(InsertInputSchema)
+      .mutation(async ({ input }) => {
+        await requireBackend().insert(input)
+        return { success: true as const }
+      }),
+
+    update: protectedProcedure
+      .input(UpdateInputSchema)
+      .mutation(async ({ input }) => {
+        await requireBackend().update(input)
+        return { success: true as const }
+      }),
+
+    delete: protectedProcedure
+      .input(CollectionKeySchema)
+      .mutation(async ({ input }) => {
+        await requireBackend().delete(input)
+        return { success: true as const }
+      }),
+
+    count: protectedProcedure
+      .input(CountInputSchema)
+      .query(async ({ input }) => {
+        const result = await requireBackend().count({ collection: input.collection, filter: input.filter ?? undefined })
+        return { count: result }
+      }),
+
+    isEmpty: protectedProcedure
+      .input(IsEmptyInputSchema)
+      .query(async ({ input }) => {
+        const result = await requireBackend().isEmpty(input)
+        return { empty: result }
+      }),
+  })
+}

package/src/api/core/stream-probe.router.ts

@@ -0,0 +1,57 @@
+/**
+ * Stream probe router — fixed core API (not a capability).
+ *
+ * Thin wrapper over `StreamProbeService` (backend REAL_LOGIC: ffprobe +
+ * HTTP probes + 1h cache). Not pluggable: there is exactly one stream
+ * probe implementation shipping with the server.
+ *
+ * Previously these endpoints lived under `streaming.probeStream` — moved
+ * here as part of eliminating the `streaming` aggregator capability.
+ */
+import { z } from 'zod'
+import { classifyStream } from '@camstack/types'
+import type { StreamProbeService } from '../../core/streaming/stream-probe.service.js'
+import { trpcRouter, adminProcedure } from '../trpc/trpc.middleware.js'
+
+const ProbedStreamSchema = z.object({
+  width: z.number().optional(),
+  height: z.number().optional(),
+  codec: z.string().optional(),
+  fps: z.number().optional(),
+  bitrateKbps: z.number().optional(),
+  quality: z.enum(['high', 'mid', 'low']),
+})
+
+const FieldProbeResultSchema = z.object({
+  status: z.enum(['ok', 'error']),
+  labels: z.array(z.string()).optional(),
+  error: z.string().optional(),
+})
+
+export function createStreamProbeRouter(sp: StreamProbeService | null) {
+  return trpcRouter({
+    probe: adminProcedure
+      .input(z.object({ url: z.string(), force: z.boolean().optional() }))
+      .output(ProbedStreamSchema)
+      .mutation(async ({ input }) => {
+        if (!sp) throw new Error('StreamProbeService not available')
+        const metadata = await sp.probe(input.url, { force: input.force })
+        return { ...metadata, quality: classifyStream(metadata) }
+      }),
+    /**
+     * Generic field probe — decides stream vs HTTP reachability based on
+     * the field key (keys starting with `stream` trigger ffprobe;
+     * everything else falls back to an HTTP GET that aborts at headers).
+     * Wraps `StreamProbeService.probeField` — used by device providers
+     * that need the kernel's probe without re-implementing ffprobe /
+     * HTTP fetch in every addon.
+     */
+    probeField: adminProcedure
+      .input(z.object({ key: z.string(), value: z.unknown() }))
+      .output(FieldProbeResultSchema)
+      .mutation(async ({ input }) => {
+        if (!sp) throw new Error('StreamProbeService not available')
+        return sp.probeField(input.key, input.value)
+      }),
+  })
+}

package/src/api/core/system-events.router.ts

@@ -0,0 +1,116 @@
+/**
+ * System events router — fixed core API (not a capability).
+ *
+ * Exposes recent-events query and live subscribe over the `EventBusService`.
+ * Supports hierarchical filtering via EventFilter: agentId → addonId → deviceId.
+ * All filters are applied server-side by the SystemEventBus — the client
+ * only receives matching events.
+ */
+import { z } from 'zod'
+import type { SystemEvent } from '@camstack/types'
+import type { EventBusService } from '../../core/events/event-bus.service.js'
+import { trpcRouter, protectedProcedure, iterableSubscription } from '../trpc/trpc.middleware.js'
+
+type SerializedEvent = {
+  id: string
+  timestamp: string
+  source: { type: string; id: string | number; nodeId?: string; addonId?: string; deviceId?: number }
+  category: string
+  data: unknown
+}
+
+function serialize(e: SystemEvent): SerializedEvent {
+  return {
+    id: e.id,
+    timestamp: new Date(e.timestamp).toISOString(),
+    source: {
+      type: e.source.type,
+      id: e.source.id,
+      ...(e.source.nodeId ? { nodeId: e.source.nodeId } : {}),
+      ...(e.source.addonId ? { addonId: e.source.addonId } : {}),
+      ...(e.source.deviceId !== undefined ? { deviceId: e.source.deviceId } : {}),
+    },
+    category: e.category,
+    data: e.data,
+  }
+}
+
+/**
+ * Source / agent / addon / device fields shared by query + subscribe.
+ * Category handling is split (asymmetric): see the per-method schemas
+ * below.
+ */
+const ScopeFieldsSchema = z.object({
+  /** Legacy source filter (exact type+id match). */
+  source: z.object({
+    type: z.string(),
+    id: z.union([z.string(), z.number()]),
+  }).optional(),
+  /** Agent/node filter (prefix match: 'hub' matches 'hub/pipeline'). */
+  agentId: z.string().optional(),
+  /** Addon filter. Matches source.addonId or source.id when type='addon'. */
+  addonId: z.string().optional(),
+  /** Device filter. Matches source.deviceId or source.id when type='device'. */
+  deviceId: z.number().optional(),
+})
+
+/**
+ * `getRecent` accepts a category array so the UI can drive a
+ * server-side whitelist when reading the historical buffer. Without
+ * this, getRecent returns the last `limit` events of any category and
+ * a noisy category (per-frame metrics) can displace relevant events
+ * (provider.motion, detection.result) out of the window — which was
+ * the symptom of "no events visible after page refresh".
+ *
+ * The underlying ring-buffer filter
+ * (`addon-context-factory.ts:getRecent`) already iterates the
+ * `category` field as `string | string[]`.
+ */
+const GetRecentInputSchema = ScopeFieldsSchema.extend({
+  category: z.union([z.string(), z.array(z.string())]).optional(),
+  limit: z.number().int().min(1).max(500).optional(),
+})
+
+/**
+ * `subscribe` keeps category as a single string. The bus's
+ * `extractCategoryPattern` keys handlers by a single pattern; passing
+ * an array would silently route only the first category. UIs that
+ * need multi-category live filtering must subscribe by deviceId
+ * (single-category-per-call or wildcard) and narrow client-side.
+ */
+const SubscribeInputSchema = ScopeFieldsSchema.extend({
+  category: z.string().optional(),
+})
+
+export function createSystemEventsRouter(eb: EventBusService) {
+  return trpcRouter({
+    getRecent: protectedProcedure
+      .input(GetRecentInputSchema)
+      .query(({ input }) => {
+        return eb.getRecent({
+          ...(input.source ? { source: input.source } : {}),
+          ...(input.agentId ? { agentId: input.agentId } : {}),
+          ...(input.addonId ? { addonId: input.addonId } : {}),
+          ...(input.deviceId !== undefined ? { deviceId: input.deviceId } : {}),
+          ...(input.category ? { category: input.category } : {}),
+        }, input.limit).map(serialize)
+      }),
+
+    subscribe: protectedProcedure
+      .input(SubscribeInputSchema)
+      .subscription(({ input }) => {
+        return iterableSubscription<unknown>((push) => {
+          return eb.subscribe(
+            {
+              ...(input.source ? { source: input.source } : {}),
+              ...(input.agentId ? { agentId: input.agentId } : {}),
+              ...(input.addonId ? { addonId: input.addonId } : {}),
+              ...(input.deviceId !== undefined ? { deviceId: input.deviceId } : {}),
+              ...(input.category ? { category: input.category } : {}),
+            },
+            (event: SystemEvent) => push(serialize(event)),
+          )
+        })
+      }),
+  })
+}

package/src/api/health/health.routes.ts

@@ -0,0 +1,123 @@
+/**
+ * Health endpoints — fast probe surface for monitoring (k8s, uptime,
+ * external watchdogs).
+ *
+ * Routes:
+ *   - GET /health                 → hub self-health
+ *   - GET /health/agents          → list of online agent node IDs
+ *   - GET /health/agents/:nodeId  → forward to agent's `$agent.health`
+ *   - GET /health/cluster         → hub + every online agent in one shot
+ *
+ * The same health shape is exposed by every agent at its own
+ * `http://<agent>:4444/health`. Both surfaces are backed by the
+ * `$agent.health` Moleculer action so monitors that talk to the hub
+ * and monitors that talk directly to an agent see identical payloads.
+ */
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import type {
+  AgentHealth,
+  AgentHealthError,
+  ClusterHealth,
+  HubHealth,
+} from '@camstack/types'
+import type { MoleculerService } from '../../core/moleculer/moleculer.service'
+import type { AgentRegistryService } from '../../core/agent/agent-registry.service'
+
+interface HealthRoutesDeps {
+  readonly moleculer: MoleculerService
+  readonly agentRegistry: AgentRegistryService
+  readonly hubVersion: string
+}
+
+interface ProcessLike {
+  uptime(): number
+  pid: number
+  cpuUsage(previous?: NodeJS.CpuUsage): NodeJS.CpuUsage
+  memoryUsage(): NodeJS.MemoryUsage
+}
+
+const AGENT_HEALTH_TIMEOUT_MS = 3_000
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+async function buildHubHealth(deps: HealthRoutesDeps, proc: ProcessLike = process): Promise<HubHealth> {
+  const nodes = await deps.agentRegistry.listNodes()
+  const remote = nodes.filter((n) => !n.isHub)
+  const online = remote.filter((n) => n.isOnline !== false).length
+  const total = remote.length
+  const memUsage = proc.memoryUsage()
+  const totalMem = memUsage.heapTotal + memUsage.external + memUsage.arrayBuffers
+  const memoryPercent = totalMem > 0 ? Math.round((memUsage.heapUsed / totalMem) * 100) : 0
+  return {
+    ok: true,
+    nodeId: 'hub',
+    version: deps.hubVersion,
+    uptimeSeconds: Math.round(proc.uptime()),
+    pid: proc.pid,
+    agents: { total, online, offline: total - online },
+    cpuPercent: 0,
+    memoryPercent,
+    checkedAt: nowIso(),
+  }
+}
+
+async function fetchAgentHealth(
+  deps: HealthRoutesDeps,
+  nodeId: string,
+): Promise<AgentHealth | AgentHealthError> {
+  try {
+    const result = (await deps.moleculer.broker.call(
+      '$agent.health',
+      {},
+      { nodeID: nodeId, timeout: AGENT_HEALTH_TIMEOUT_MS },
+    )) as AgentHealth
+    return result
+  } catch (err) {
+    return {
+      ok: false,
+      nodeId,
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}
+
+export function registerHealthRoutes(fastify: FastifyInstance, deps: HealthRoutesDeps): void {
+  fastify.get('/health', async (): Promise<HubHealth> => buildHubHealth(deps))
+
+  fastify.get('/health/agents', async (): Promise<{ readonly agents: readonly string[] }> => {
+    const nodes = await deps.agentRegistry.listNodes()
+    return {
+      agents: nodes
+        .filter((n) => !n.isHub && n.isOnline !== false)
+        .map((n) => n.info.id),
+    }
+  })
+
+  fastify.get<{ Params: { nodeId: string } }>(
+    '/health/agents/:nodeId',
+    async (req, reply: FastifyReply) => {
+      const { nodeId } = req.params
+      if (!nodeId) {
+        return reply.status(400).send({ ok: false, error: 'nodeId required' })
+      }
+      const result = await fetchAgentHealth(deps, nodeId)
+      if (!result.ok) {
+        return reply.status(503).send(result)
+      }
+      return result
+    },
+  )
+
+  fastify.get('/health/cluster', async (): Promise<ClusterHealth> => {
+    const hub = await buildHubHealth(deps)
+    const nodes = await deps.agentRegistry.listNodes()
+    const remote = nodes.filter((n) => !n.isHub && n.isOnline !== false)
+    const agents = await Promise.all(
+      remote.map((n) => fetchAgentHealth(deps, n.info.id)),
+    )
+    const ok = hub.ok && agents.every((a) => a.ok)
+    return { ok, hub, agents, checkedAt: nowIso() }
+  })
+}

package/src/api/oauth2/__tests__/oauth2-routes.spec.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { validateAuthorizeQuery, isRedirectUriAllowed } from '../oauth2-routes.js'
+
+describe('validateAuthorizeQuery', () => {
+  const known = new Set(['export-alexa'])
+  it('accepts a well-formed query for a known integration', () => {
+    const r = validateAuthorizeQuery(
+      { response_type: 'code', integration: 'export-alexa', redirect_uri: 'https://cb/r', state: 's' },
+      known,
+    )
+    expect(r.ok).toBe(true)
+  })
+  it('rejects an unknown integration', () => {
+    const r = validateAuthorizeQuery(
+      { response_type: 'code', integration: 'nope', redirect_uri: 'https://cb/r', state: 's' },
+      known,
+    )
+    expect(r.ok).toBe(false)
+  })
+  it('rejects a missing state', () => {
+    const r = validateAuthorizeQuery(
+      { response_type: 'code', integration: 'export-alexa', redirect_uri: 'https://cb/r' },
+      known,
+    )
+    expect(r.ok).toBe(false)
+  })
+  it('rejects a non-code response_type', () => {
+    const r = validateAuthorizeQuery(
+      { response_type: 'token', integration: 'export-alexa', redirect_uri: 'https://cb/r', state: 's' },
+      known,
+    )
+    expect(r.ok).toBe(false)
+  })
+})
+
+describe('isRedirectUriAllowed', () => {
+  const prefixes = ['https://layla.amazon.com/', 'https://pitangui.amazon.com/']
+
+  it('returns true when redirect_uri starts with an allowed prefix', () => {
+    expect(isRedirectUriAllowed('https://layla.amazon.com/oauth/callback', prefixes)).toBe(true)
+    expect(isRedirectUriAllowed('https://pitangui.amazon.com/oauth/callback', prefixes)).toBe(true)
+  })
+
+  it('returns false when redirect_uri does not match any allowed prefix', () => {
+    expect(isRedirectUriAllowed('https://evil.example/grab', prefixes)).toBe(false)
+    expect(isRedirectUriAllowed('https://layla.amazon.com.evil.example/', prefixes)).toBe(false)
+  })
+
+  it('returns false when allowedPrefixes is empty', () => {
+    expect(isRedirectUriAllowed('https://layla.amazon.com/oauth/callback', [])).toBe(false)
+  })
+})

package/src/api/oauth2/consent-page.ts

@@ -0,0 +1,42 @@
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!
+  ))
+}
+
+interface ConsentPageInput {
+  displayName: string
+  username: string
+  scopeSummary: string
+  /** Hidden form fields replayed on POST. */
+  hidden: Record<string, string>
+}
+
+/** Allow/Deny consent screen. Submitting POSTs to the same path with the
+ *  hidden query fields + `consent=allow|deny`. */
+export function renderConsentPage(input: ConsentPageInput): string {
+  const hidden = Object.entries(input.hidden)
+    .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
+    .join('\n      ')
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>CamStack · Authorize ${escapeHtml(input.displayName)}</title>
+<style>
+ body{font-family:system-ui,sans-serif;max-width:480px;margin:4rem auto;padding:0 1rem;color:#1f2937}
+ .card{border:1px solid #e5e7eb;border-radius:.5rem;padding:1.5rem}
+ .meta{font-size:.85rem;color:#6b7280;margin:.5rem 0}
+ button{font-size:1rem;padding:.5rem 1.25rem;border-radius:.375rem;cursor:pointer;border:1px solid transparent}
+ .allow{background:#2563eb;color:#fff}.deny{background:#f3f4f6;color:#1f2937;border-color:#d1d5db;margin-left:.5rem}
+</style></head><body>
+  <div class="card">
+    <h1>Authorize ${escapeHtml(input.displayName)}</h1>
+    <p class="meta">Signed in as <strong>${escapeHtml(input.username)}</strong></p>
+    <p class="meta">This will grant: ${escapeHtml(input.scopeSummary)}</p>
+    <form method="POST">
+      ${hidden}
+      <button class="allow" name="consent" value="allow" type="submit">Allow</button>
+      <button class="deny" name="consent" value="deny" type="submit">Deny</button>
+    </form>
+  </div>
+</body></html>`
+}