@camstack/server 0.1.7 → 0.2.0

package/src/api/trpc/scope-access.ts

@@ -24,9 +24,7 @@
 import { METHOD_ACCESS_MAP } from '@camstack/types'
 import type { MethodAccess, TokenScope } from '@camstack/types'
 
-export type ScopeAccessResult =
-  | { ok: true; access: MethodAccess }
-  | { ok: false; reason: string }
+export type ScopeAccessResult = { ok: true; access: MethodAccess } | { ok: false; reason: string }
 
 /**
  * Resolves a deviceId to its ancestor chain (parent, grandparent, …).
@@ -101,10 +99,12 @@ export function checkScopeAccess(
     reason: `No scope grants ${meta.access} on '${meta.capName}' (${meta.capScope}-scope cap${
       deviceId !== null ? `, device=${deviceId}` : ''
     }). Have: ${
-      scopes.map((s) => {
-        const target = s.type === 'device' ? `[${s.targets.join(',')}]` : s.target
-        return `${s.type}:${target}[${s.access.join(',')}]`
-      }).join(', ') || '(none)'
+      scopes
+        .map((s) => {
+          const target = s.type === 'device' ? `[${s.targets.join(',')}]` : s.target
+          return `${s.type}:${target}[${s.access.join(',')}]`
+        })
+        .join(', ') || '(none)'
     }`,
   }
 }

package/src/api/trpc/trpc.context.ts

@@ -117,7 +117,9 @@ async function resolveUser(
   // protectedProcedure can still gate by scope match.
   if (token.startsWith('cst_')) {
     try {
-      const userMgmt = addonRegistry.getCapabilityRegistry().getSingleton('user-management') as UserManagementLike | undefined
+      const userMgmt = addonRegistry.getCapabilityRegistry().getSingleton('user-management') as
+        | UserManagementLike
+        | undefined
       if (!userMgmt) return null
       const record = await userMgmt.validateScopedToken({ token })
       if (!record) return null
@@ -182,7 +184,9 @@ async function resolveUser(
  * Bounded by hop count (defence-in-depth — the device tree should
  * never exceed 2-3 levels but a corrupt registry shouldn't loop forever).
  */
-function makeAncestorLookup(addonRegistry: AddonRegistryService): (deviceId: number) => readonly number[] {
+function makeAncestorLookup(
+  addonRegistry: AddonRegistryService,
+): (deviceId: number) => readonly number[] {
   return (deviceId: number) => {
     const out: number[] = []
     const registry = addonRegistry.getDeviceRegistry()
@@ -243,8 +247,7 @@ export async function createWsTrpcContext(
   // 1. connectionParams.token (sent by BackendClient's createWSClient)
   const paramToken = opts.info.connectionParams?.['token']
   const token =
-    (typeof paramToken === 'string' ? paramToken : null) ??
-    extractTokenFromRequest(opts.req)
+    (typeof paramToken === 'string' ? paramToken : null) ?? extractTokenFromRequest(opts.req)
 
   const user = await resolveUser(token, authService, addonRegistry)
   return {

package/src/api/trpc/trpc.middleware.ts

@@ -21,7 +21,7 @@ const t = initTRPC.context<TrpcContext>().create({
  * @param subscribe — called once; receives a `push` callback and must return an unsubscribe fn.
  */
 export async function* iterableSubscription<T>(
-  subscribe: (push: (value: T) => void) => (() => void),
+  subscribe: (push: (value: T) => void) => () => void,
 ): AsyncGenerator<T> {
   const queue: T[] = []
   let resolve: (() => void) | null = null
@@ -36,7 +36,9 @@ export async function* iterableSubscription<T>(
       while (queue.length > 0) {
         yield queue.shift()!
       }
-      await new Promise<void>((r) => { resolve = r })
+      await new Promise<void>((r) => {
+        resolve = r
+      })
     }
   } finally {
     unsub()

package/src/api/trpc/trpc.router.ts

@@ -11,7 +11,7 @@ import { trpcRouter } from './trpc.middleware'
 //   streaming → `streamingManagement` cap, events → `eventQuery` cap,
 //   logs → kept manual, live → kept manual, processes → `processMgmt`
 //   cap, agents → `nodes` cap, sessions → `session` cap, trackMedia /
-//   trackTrail → caps, recording → `recordingEngine` cap, network →
+//   trackTrail → caps, network →
 //   `networkQuality` cap, addons → `addons` cap, bridgePipeline removed
 //   (legacy), detection → `detectionConfig` cap, capabilities → kept
 //   manual, update → addons cap, addonPages → cap, notification →
@@ -20,7 +20,7 @@ import { trpcRouter } from './trpc.middleware'
 //   `pipelineExecutor` cap, pipeline → `pipelineConfig` cap,
 //   systemEvents → kept manual.
 import type { CapabilityRegistry } from '@camstack/kernel'
-import type { InferProvider } from '@camstack/types'
+import type { InferProvider, BrokerConsumerAttribution } from '@camstack/types'
 import {
   pipelineExecutorCapability,
   pipelineRunnerCapability,
@@ -76,6 +76,7 @@ import { createCapabilitiesRouter } from '../core/capabilities.router.js'
 import { createStreamProbeRouter } from '../core/stream-probe.router.js'
 import { createHwAccelRouter } from '../core/hwaccel.router.js'
 import { requireSingleton, firstSupported, anySupports } from './cap-mount-helpers.js'
+import { extractUserAgent } from './client-ip.js'
 import type { TrpcContext } from './trpc.context.js'
 import type { AuthService } from '../../core/auth/auth.service'
 import type { ConfigService } from '../../core/config/config.service'
@@ -112,6 +113,27 @@ export interface RouterServices {
 }
 
 type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
+type CreateSessionInput = Parameters<WebrtcSessionProvider['createSession']>[0]
+type HandleOfferInput = Parameters<WebrtcSessionProvider['handleOffer']>[0]
+
+/**
+ * Merge the server-read User-Agent into a signaling call's
+ * `consumerAttribution`, building a NEW input object (immutable — never
+ * mutates the caller's input). When `userAgent` is null (mesh-originated
+ * call, or a client that omits the header) the input passes through
+ * unchanged. Any client-supplied `userAgent` is OVERWRITTEN — the hub
+ * trusts only the request context, never the client.
+ */
+export function enrichInputWithUserAgent<
+  TInput extends { consumerAttribution?: BrokerConsumerAttribution },
+>(input: TInput, userAgent: string | null): TInput {
+  if (userAgent === null) return input
+  const base: BrokerConsumerAttribution = input.consumerAttribution ?? { kind: 'webrtc-browser' }
+  return {
+    ...input,
+    consumerAttribution: { ...base, userAgent },
+  }
+}
 
 /**
  * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
@@ -124,13 +146,26 @@ type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
  * advertised Tailscale address, srflx, relay) and let ICE nominate the best
  * reachable pair: direct when possible, relay only as a fallback. The
  * `relayOnly` cap field + broker support remain for when relay media-forward
- * is fixed; this wrapper is a pass-through for now.
+ * is fixed.
+ *
+ * The wrapper additionally enriches the `createSession` / `handleOffer`
+ * subscriber attribution with the originating client's User-Agent, read
+ * from the tRPC request context (browser sessions). All OTHER methods
+ * delegate straight through — auth, the remote-proxy factory and every
+ * signaling behaviour are untouched.
  */
-function wrapWebrtcSessionProviderWithRelay(
+export function wrapWebrtcSessionProviderWithRelay(
   provider: WebrtcSessionProvider,
-  _ctx: TrpcContext,
+  ctx: TrpcContext,
 ): WebrtcSessionProvider {
-  return provider
+  const userAgent = extractUserAgent(ctx.req)
+  return {
+    ...provider,
+    createSession: (input: CreateSessionInput) =>
+      provider.createSession(enrichInputWithUserAgent(input, userAgent)),
+    handleOffer: (input: HandleOfferInput) =>
+      provider.handleOffer(enrichInputWithUserAgent(input, userAgent)),
+  }
 }
 
 /**
@@ -181,27 +216,26 @@ function buildCapabilityRouters(services: RouterServices) {
     // CapabilityRegistry — the provider is built on-demand from
     // backend services. `mountAllCaps` would return `null` for them
     // (registry lookup miss), so we re-mount with `buildXProvider`.
-    networkQuality: createCapRouter_networkQuality(
-      (_ctx) => buildNetworkQualityProvider(services.networkQualityService),
+    networkQuality: createCapRouter_networkQuality((_ctx) =>
+      buildNetworkQualityProvider(services.networkQualityService),
     ),
-    system: createCapRouter_system(
-      (_ctx) => buildSystemProvider(services.featureService, services.capabilityRegistry),
+    system: createCapRouter_system((_ctx) =>
+      buildSystemProvider(services.featureService, services.capabilityRegistry),
     ),
-    toast: createCapRouter_toast(
-      (ctx) => buildToastProvider(services.toastService, ctx),
-    ),
-    integrations: createCapRouter_integrations(
-      (_ctx) => buildIntegrationsProvider(services.addonRegistry, services.eventBus, services.loggingService),
-    ),
-    nodes: createCapRouter_nodes(
-      (_ctx) => buildNodesProvider(
-        services.agentRegistry,
-        services.moleculer,
+    toast: createCapRouter_toast((ctx) => buildToastProvider(services.toastService, ctx)),
+    integrations: createCapRouter_integrations((_ctx) =>
+      buildIntegrationsProvider(
         services.addonRegistry,
+        services.eventBus,
+        services.loggingService,
+        services.capabilityRegistry,
       ),
     ),
-    addons: createCapRouter_addons(
-      (ctx) => buildAddonsProvider(
+    nodes: createCapRouter_nodes((_ctx) =>
+      buildNodesProvider(services.agentRegistry, services.moleculer, services.addonRegistry),
+    ),
+    addons: createCapRouter_addons((ctx) =>
+      buildAddonsProvider(
         services.addonRegistry,
         services.addonPackageService,
         services.loggingService,
@@ -218,32 +252,68 @@ function buildCapabilityRouters(services: RouterServices) {
     // distinct. Casting at the override site is cheaper than reworking
     // the provider declarations. Auto-mount can't infer the cast.
     pipelineExecutor: createCapRouter_pipelineExecutor(
-      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-executor') as InferProvider<typeof pipelineExecutorCapability> | null,
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineExecutorCapability> | null,
+      (_ctx) =>
+        requireSingleton(services.capabilityRegistry, 'pipeline-executor') as InferProvider<
+          typeof pipelineExecutorCapability
+        > | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof pipelineExecutorCapability
+        > | null,
     ),
     pipelineRunner: createCapRouter_pipelineRunner(
-      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-runner') as InferProvider<typeof pipelineRunnerCapability> | null,
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineRunnerCapability> | null,
+      (_ctx) =>
+        requireSingleton(services.capabilityRegistry, 'pipeline-runner') as InferProvider<
+          typeof pipelineRunnerCapability
+        > | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof pipelineRunnerCapability
+        > | null,
     ),
     pipelineOrchestrator: createCapRouter_pipelineOrchestrator(
-      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-orchestrator') as InferProvider<typeof pipelineOrchestratorCapability> | null,
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineOrchestratorCapability> | null,
+      (_ctx) =>
+        requireSingleton(services.capabilityRegistry, 'pipeline-orchestrator') as InferProvider<
+          typeof pipelineOrchestratorCapability
+        > | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof pipelineOrchestratorCapability
+        > | null,
     ),
     audioAnalyzer: createCapRouter_audioAnalyzer(
       (_ctx) => requireSingleton(services.capabilityRegistry, 'audio-analyzer'),
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof audioAnalyzerCapability> | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof audioAnalyzerCapability
+        > | null,
     ),
     audioCodec: createCapRouter_audioCodec(
-      (_ctx) => requireSingleton(services.capabilityRegistry, 'audio-codec') as InferProvider<typeof audioCodecCapability> | null,
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof audioCodecCapability> | null,
+      (_ctx) =>
+        requireSingleton(services.capabilityRegistry, 'audio-codec') as InferProvider<
+          typeof audioCodecCapability
+        > | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof audioCodecCapability
+        > | null,
     ),
     decoder: createCapRouter_decoder(
-      (_ctx) => requireSingleton(services.capabilityRegistry, 'decoder') as InferProvider<typeof decoderCapability> | null,
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof decoderCapability> | null,
+      (_ctx) =>
+        requireSingleton(services.capabilityRegistry, 'decoder') as InferProvider<
+          typeof decoderCapability
+        > | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof decoderCapability
+        > | null,
     ),
     platformProbe: createCapRouter_platformProbe(
       (_ctx) => requireSingleton(services.capabilityRegistry, 'platform-probe'),
-      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof platformProbeCapability> | null,
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<
+          typeof platformProbeCapability
+        > | null,
     ),
 
     // ── Cap overrides: hub-only, no remote fallback ─────────────────
@@ -266,18 +336,17 @@ function buildCapabilityRouters(services: RouterServices) {
     // `getSnapshot` picks the first one that claims the device. The
     // generic first-provider resolver from the auto-mount can't model
     // this — we hand-write the probe + fan-out logic.
-    snapshotProvider: createCapRouter_snapshotProvider(
-      (_ctx) => {
-        const reg = services.capabilityRegistry
-        if (!reg) return null
-        type SnapshotProviderInferred = import('@camstack/types').CapabilityProviderMap['snapshot-provider']
-        const providers = reg.getCollection<SnapshotProviderInferred>('snapshot-provider')
-        if (!providers || providers.length === 0) return null
-        const supportsDevice = anySupports(providers, 'supportsDevice')
-        const getSnapshot = firstSupported(providers, 'supportsDevice', 'getSnapshot')
-        return { supportsDevice, getSnapshot }
-      },
-    ),
+    snapshotProvider: createCapRouter_snapshotProvider((_ctx) => {
+      const reg = services.capabilityRegistry
+      if (!reg) return null
+      type SnapshotProviderInferred =
+        import('@camstack/types').CapabilityProviderMap['snapshot-provider']
+      const providers = reg.getCollection<SnapshotProviderInferred>('snapshot-provider')
+      if (!providers || providers.length === 0) return null
+      const supportsDevice = anySupports(providers, 'supportsDevice')
+      const getSnapshot = firstSupported(providers, 'supportsDevice', 'getSnapshot')
+      return { supportsDevice, getSnapshot }
+    }),
 
     // ── Cap override: server-detected remote → relay-only ────────────
     // The broker (a forked addon) can't see the HTTP request, so it
@@ -290,8 +359,8 @@ function buildCapabilityRouters(services: RouterServices) {
     // remote-proxy routing is preserved (forked/agent-hosted brokers).
     webrtcSession: createCapRouter_webrtcSession(
       (ctx) => {
-        const provider = services.capabilityRegistry
-          ?.getSingleton<WebrtcSessionProvider>('webrtc-session') ?? null
+        const provider =
+          services.capabilityRegistry?.getSingleton<WebrtcSessionProvider>('webrtc-session') ?? null
         return provider ? wrapWebrtcSessionProviderWithRelay(provider, ctx) : null
       },
       (capName, nodeId) =>

package/src/auth/session-cookie.ts

@@ -42,3 +42,13 @@ export function shouldRedirectToLogin(method: string, accept: string | undefined
 export function loginRedirectUrl(originalUrl: string): string {
   return `/login?next=${encodeURIComponent(originalUrl)}`
 }
+
+/** Allowed redirect target for `GET /api/embed-auth`: a same-origin RELATIVE
+ *  path to a stream-broker embed page. Defeats open-redirects — the endpoint
+ *  sets the session cookie from a Bearer token, so the `next` must be safe to
+ *  bounce to. Rejects absolute/protocol-relative URLs, backslashes, and `..`. */
+export function isEmbedRedirectTarget(next: string): boolean {
+  if (!next.startsWith('/addon/stream-broker/embed/')) return false
+  if (next.includes('\\') || next.includes('://') || next.includes('..')) return false
+  return true
+}

package/src/boot/__tests__/integration-id-backfill.spec.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from 'vitest'
+import {
+  planIntegrationIdBackfill,
+  planDeleteTimeStamps,
+  runIntegrationIdBackfill,
+} from '../integration-id-backfill'
+
+describe('planDeleteTimeStamps', () => {
+  it("claims an untagged top-level device of the deleted integration's single-integration addon", () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [{ id: 'int_rtsp', addonId: 'provider-rtsp' }],
+      [
+        { id: 4, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 6, addonId: 'provider-rtsp', parentDeviceId: null },
+      ],
+    )
+    expect(stamps).toEqual([
+      { deviceId: 4, integrationId: 'int_rtsp' },
+      { deviceId: 6, integrationId: 'int_rtsp' },
+    ])
+  })
+
+  it('returns no stamps for a multi-integration addon (ambiguous — never auto-claim)', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_a',
+      [
+        { id: 'int_a', addonId: 'provider-ha' },
+        { id: 'int_b', addonId: 'provider-ha' },
+      ],
+      [{ id: 11, addonId: 'provider-ha', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('only returns stamps for the integration being deleted, not siblings of other addons', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [
+        { id: 'int_rtsp', addonId: 'provider-rtsp' },
+        { id: 'int_onvif', addonId: 'provider-onvif' },
+      ],
+      [
+        { id: 4, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 5, addonId: 'provider-onvif', parentDeviceId: null },
+      ],
+    )
+    expect(stamps).toEqual([{ deviceId: 4, integrationId: 'int_rtsp' }])
+  })
+
+  it('skips devices already tagged with the deleted integration', () => {
+    const stamps = planDeleteTimeStamps(
+      'int_rtsp',
+      [{ id: 'int_rtsp', addonId: 'provider-rtsp' }],
+      [{ id: 4, addonId: 'provider-rtsp', parentDeviceId: null, integrationId: 'int_rtsp' }],
+    )
+    expect(stamps).toEqual([])
+  })
+})
+
+describe('planIntegrationIdBackfill', () => {
+  it('stamps a top-level untagged device whose addon has exactly one integration', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [{ id: 10, addonId: 'provider-rtsp', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([{ deviceId: 10, integrationId: 'int_1' }])
+  })
+
+  it('skips devices whose addon hosts multiple integrations (ambiguous)', () => {
+    const stamps = planIntegrationIdBackfill(
+      [
+        { id: 'int_a', addonId: 'provider-ha' },
+        { id: 'int_b', addonId: 'provider-ha' },
+      ],
+      [{ id: 11, addonId: 'provider-ha', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('skips already-tagged devices and child devices', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [
+        { id: 12, addonId: 'provider-rtsp', parentDeviceId: null, integrationId: 'int_1' },
+        { id: 13, addonId: 'provider-rtsp', parentDeviceId: 12 },
+      ],
+    )
+    expect(stamps).toEqual([])
+  })
+
+  it('skips devices whose addon has no integration', () => {
+    const stamps = planIntegrationIdBackfill(
+      [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      [{ id: 14, addonId: 'provider-onvif', parentDeviceId: null }],
+    )
+    expect(stamps).toEqual([])
+  })
+})
+
+describe('runIntegrationIdBackfill', () => {
+  it('applies stamps and reports the count, skipping failures', async () => {
+    const stamped: Array<{ deviceId: number; integrationId: string }> = []
+    const result = await runIntegrationIdBackfill({
+      listIntegrations: async () => [{ id: 'int_1', addonId: 'provider-rtsp' }],
+      listDevices: async () => [
+        { id: 10, addonId: 'provider-rtsp', parentDeviceId: null },
+        { id: 11, addonId: 'provider-rtsp', parentDeviceId: null },
+      ],
+      setIntegrationId: async (deviceId, integrationId) => {
+        if (deviceId === 11) throw new Error('boom')
+        stamped.push({ deviceId, integrationId })
+      },
+      logger: { info: () => {}, warn: () => {} },
+    })
+    expect(result).toEqual({ stamped: 1 })
+    expect(stamped).toEqual([{ deviceId: 10, integrationId: 'int_1' }])
+  })
+
+  it('does nothing when there is nothing to stamp', async () => {
+    const result = await runIntegrationIdBackfill({
+      listIntegrations: async () => [],
+      listDevices: async () => [],
+      setIntegrationId: async () => {
+        throw new Error('should not be called')
+      },
+      logger: { info: () => {}, warn: () => {} },
+    })
+    expect(result).toEqual({ stamped: 0 })
+  })
+})