@camstack/server 0.1.7 → 0.2.0

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

@@ -14,12 +14,7 @@
  * 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 { AgentHealth, AgentHealthError, ClusterHealth, HubHealth } from '@camstack/types'
 import type { MoleculerService } from '../../core/moleculer/moleculer.service'
 import type { AgentRegistryService } from '../../core/agent/agent-registry.service'
 
@@ -42,7 +37,10 @@ function nowIso(): string {
   return new Date().toISOString()
 }
 
-async function buildHubHealth(deps: HealthRoutesDeps, proc: ProcessLike = process): Promise<HubHealth> {
+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
@@ -89,9 +87,7 @@ export function registerHealthRoutes(fastify: FastifyInstance, deps: HealthRoute
   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),
+      agents: nodes.filter((n) => !n.isHub && n.isOnline !== false).map((n) => n.info.id),
     }
   })
 
@@ -114,9 +110,7 @@ export function registerHealthRoutes(fastify: FastifyInstance, deps: HealthRoute
     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 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

@@ -5,7 +5,12 @@ 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' },
+      {
+        response_type: 'code',
+        integration: 'export-alexa',
+        redirect_uri: 'https://cb/r',
+        state: 's',
+      },
       known,
     )
     expect(r.ok).toBe(true)
@@ -26,7 +31,12 @@ describe('validateAuthorizeQuery', () => {
   })
   it('rejects a non-code response_type', () => {
     const r = validateAuthorizeQuery(
-      { response_type: 'token', integration: 'export-alexa', redirect_uri: 'https://cb/r', state: 's' },
+      {
+        response_type: 'token',
+        integration: 'export-alexa',
+        redirect_uri: 'https://cb/r',
+        state: 's',
+      },
       known,
     )
     expect(r.ok).toBe(false)

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

@@ -1,7 +1,8 @@
 function escapeHtml(s: string): string {
-  return s.replace(/[&<>"']/g, (c) => (
-    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!
-  ))
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!,
+  )
 }
 
 interface ConsentPageInput {

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

@@ -1,8 +1,17 @@
 import type { FastifyInstance } from 'fastify'
 import type { CapabilityRegistry } from '@camstack/kernel'
-import type { IOauthIntegrationProvider, IUserManagementProvider, OauthIntegrationDescriptor, TokenScope } from '@camstack/types'
+import type {
+  IOauthIntegrationProvider,
+  IUserManagementProvider,
+  OauthIntegrationDescriptor,
+  TokenScope,
+} from '@camstack/types'
 import { renderConsentPage } from './consent-page.js'
-import { SESSION_COOKIE, shouldRedirectToLogin, loginRedirectUrl } from '../../auth/session-cookie.js'
+import {
+  SESSION_COOKIE,
+  shouldRedirectToLogin,
+  loginRedirectUrl,
+} from '../../auth/session-cookie.js'
 
 export interface AuthorizeQuery {
   response_type?: string
@@ -17,16 +26,25 @@ export type AuthorizeValidation =
 
 /** Validate the inbound authorize query. `client_id` is intentionally
  *  NOT checked — that pair is verified only at the Lambda boundary. */
-export function validateAuthorizeQuery(q: AuthorizeQuery, knownIntegrations: ReadonlySet<string>): AuthorizeValidation {
-  if (q.response_type !== 'code') return { ok: false, status: 400, error: 'unsupported_response_type' }
-  if (!q.integration || !knownIntegrations.has(q.integration)) return { ok: false, status: 400, error: 'invalid_request — unknown integration' }
-  if (!q.redirect_uri) return { ok: false, status: 400, error: 'invalid_request — redirect_uri required' }
+export function validateAuthorizeQuery(
+  q: AuthorizeQuery,
+  knownIntegrations: ReadonlySet<string>,
+): AuthorizeValidation {
+  if (q.response_type !== 'code')
+    return { ok: false, status: 400, error: 'unsupported_response_type' }
+  if (!q.integration || !knownIntegrations.has(q.integration))
+    return { ok: false, status: 400, error: 'invalid_request — unknown integration' }
+  if (!q.redirect_uri)
+    return { ok: false, status: 400, error: 'invalid_request — redirect_uri required' }
   if (!q.state) return { ok: false, status: 400, error: 'invalid_request — state required' }
   return { ok: true, integration: q.integration, redirectUri: q.redirect_uri, state: q.state }
 }
 
 /** True if `redirectUri` starts with one of the integration's allowed prefixes. */
-export function isRedirectUriAllowed(redirectUri: string, allowedPrefixes: readonly string[]): boolean {
+export function isRedirectUriAllowed(
+  redirectUri: string,
+  allowedPrefixes: readonly string[],
+): boolean {
   return allowedPrefixes.some((p) => redirectUri.startsWith(p))
 }
 
@@ -121,7 +139,9 @@ export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps)
 
     const descriptor = descriptorMap.get(v.integration)!
     if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes)) {
-      return reply.status(400).send({ error: 'invalid_request — redirect_uri not allowed for this integration' })
+      return reply
+        .status(400)
+        .send({ error: 'invalid_request — redirect_uri not allowed for this integration' })
     }
 
     const html = renderConsentPage({
@@ -178,11 +198,15 @@ export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps)
 
     const descriptor = descriptorMap.get(v.integration)!
     if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes)) {
-      return reply.status(400).send({ error: 'invalid_request — redirect_uri not allowed for this integration' })
+      return reply
+        .status(400)
+        .send({ error: 'invalid_request — redirect_uri not allowed for this integration' })
     }
 
     if (body.consent !== 'allow') {
-      return reply.redirect(`${v.redirectUri}?error=access_denied&state=${encodeURIComponent(v.state)}`)
+      return reply.redirect(
+        `${v.redirectUri}?error=access_denied&state=${encodeURIComponent(v.state)}`,
+      )
     }
 
     const userMgmt = registry.getSingleton<IUserManagementProvider>('user-management')
@@ -203,7 +227,9 @@ export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps)
       hubUrl: descriptor.hubUrl ?? deps.publicHubUrl(),
     })
 
-    return reply.redirect(`${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`)
+    return reply.redirect(
+      `${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`,
+    )
   })
 
   // ─── POST /api/oauth2/token ───────────────────────────────────────────────
@@ -228,7 +254,10 @@ export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps)
       if (!body.code || !body.redirect_uri) {
         return reply.status(400).send({ error: 'invalid_request' })
       }
-      tokenResult = await userMgmt.oauthExchangeCode({ code: body.code, redirectUri: body.redirect_uri })
+      tokenResult = await userMgmt.oauthExchangeCode({
+        code: body.code,
+        redirectUri: body.redirect_uri,
+      })
     } else if (body.grant_type === 'refresh_token') {
       if (!body.refresh_token) {
         return reply.status(400).send({ error: 'invalid_request' })

package/src/api/trpc/__tests__/client-ip.spec.ts

@@ -11,15 +11,17 @@
  */
 import { describe, it, expect } from 'vitest'
 import type { IncomingMessage } from 'node:http'
-import { extractClientIp, isRemoteClientIp } from '../client-ip.js'
+import { extractClientIp, extractUserAgent, isRemoteClientIp } from '../client-ip.js'
 
 function reqWith(opts: {
   xff?: string | string[]
   ip?: string
   remoteAddress?: string
+  userAgent?: string | string[]
 }): IncomingMessage {
   const headers: Record<string, string | string[]> = {}
   if (opts.xff !== undefined) headers['x-forwarded-for'] = opts.xff
+  if (opts.userAgent !== undefined) headers['user-agent'] = opts.userAgent
   const req = {
     headers,
     socket: { remoteAddress: opts.remoteAddress },
@@ -66,6 +68,30 @@ describe('extractClientIp', () => {
   })
 })
 
+describe('extractUserAgent', () => {
+  it('returns null for an absent request (mesh-originated call)', () => {
+    expect(extractUserAgent(undefined)).toBeNull()
+  })
+
+  it('returns null when the header is missing', () => {
+    expect(extractUserAgent(reqWith({}))).toBeNull()
+  })
+
+  it('reads the user-agent header', () => {
+    const req = reqWith({ userAgent: 'Mozilla/5.0 (Macintosh) Chrome/120' })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (Macintosh) Chrome/120')
+  })
+
+  it('reads the first entry when the header is an array', () => {
+    const req = reqWith({ userAgent: ['Mozilla/5.0 (X11) Firefox/121', 'ignored'] })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (X11) Firefox/121')
+  })
+
+  it('returns null for an empty header value', () => {
+    expect(extractUserAgent(reqWith({ userAgent: '' }))).toBeNull()
+  })
+})
+
 describe('isRemoteClientIp', () => {
   it('null → false (treated as LAN — safe default)', () => {
     expect(isRemoteClientIp(null)).toBe(false)

package/src/api/trpc/__tests__/scope-access-device.spec.ts

@@ -38,13 +38,13 @@ interface DeviceNode {
 }
 
 const TREE: readonly DeviceNode[] = [
-  { id: 5,  parentDeviceId: null }, // Reolink (parent)
-  { id: 51, parentDeviceId: 5 },    // siren child
-  { id: 52, parentDeviceId: 5 },    // floodlight child
-  { id: 53, parentDeviceId: 5 },    // PIR child
-  { id: 7,  parentDeviceId: null }, // Hikvision (parent)
-  { id: 71, parentDeviceId: 7 },    // hik siren child
-  { id: 9,  parentDeviceId: null }, // Frigate (parent, NOT granted)
+  { id: 5, parentDeviceId: null }, // Reolink (parent)
+  { id: 51, parentDeviceId: 5 }, // siren child
+  { id: 52, parentDeviceId: 5 }, // floodlight child
+  { id: 53, parentDeviceId: 5 }, // PIR child
+  { id: 7, parentDeviceId: null }, // Hikvision (parent)
+  { id: 71, parentDeviceId: 7 }, // hik siren child
+  { id: 9, parentDeviceId: null }, // Frigate (parent, NOT granted)
 ]
 
 /** Walks the parent chain — mirrors the real lookup in trpc.context.ts. */
@@ -69,15 +69,15 @@ function deviceScope(targets: readonly string[], access: TokenScope['access']):
  * just on the matcher's logic.
  */
 const VIEW_METHODS = [
-  'webrtcSession.listStreams',       // view, webrtc-session cap
-  'cameraStreams.getCameraStreams',  // view, camera-streams cap
+  'webrtcSession.listStreams', // view, webrtc-session cap
+  'cameraStreams.getCameraStreams', // view, camera-streams cap
   'audioMetrics.getCurrentSnapshot', // view, audio-metrics cap
 ] as const
 
 const CREATE_METHODS = [
   'webrtcSession.createSession', // create, webrtc-session cap
-  'switch.setState',             // create, switch cap (accessory typical)
-  'reboot.reboot',               // create, reboot cap
+  'switch.setState', // create, switch cap (accessory typical)
+  'reboot.reboot', // create, reboot cap
 ] as const
 
 // ── Direct match — granted device, any cap method ──────────────────
@@ -102,7 +102,12 @@ describe('checkScopeAccess — device scope, direct grant', () => {
   it('admits multiple deviceIds listed in a single scope row', () => {
     const scopes = [deviceScope(['5', '7'], ['view'])]
     for (const id of [5, 7]) {
-      const result = checkScopeAccess(scopes, 'webrtcSession.listStreams', { deviceId: id }, lookupAncestors)
+      const result = checkScopeAccess(
+        scopes,
+        'webrtcSession.listStreams',
+        { deviceId: id },
+        lookupAncestors,
+      )
       expect(result.ok, `device ${id} should be allowed`).toBe(true)
     }
   })
@@ -125,14 +130,24 @@ describe('checkScopeAccess — device scope, accessory inheritance', () => {
 
   it('grant on parent 5 covers PIR 53 (read-only)', () => {
     const scopes = [deviceScope(['5'], ['view'])]
-    const result = checkScopeAccess(scopes, 'cameraStreams.getCameraStreams', { deviceId: 53 }, lookupAncestors)
+    const result = checkScopeAccess(
+      scopes,
+      'cameraStreams.getCameraStreams',
+      { deviceId: 53 },
+      lookupAncestors,
+    )
     expect(result.ok).toBe(true)
   })
 
   it('grant on parent 5 does NOT cover Hikvision parent 7 nor its siren 71', () => {
     const scopes = [deviceScope(['5'], ['view', 'create'])]
     for (const orphanId of [7, 71]) {
-      const result = checkScopeAccess(scopes, 'webrtcSession.listStreams', { deviceId: orphanId }, lookupAncestors)
+      const result = checkScopeAccess(
+        scopes,
+        'webrtcSession.listStreams',
+        { deviceId: orphanId },
+        lookupAncestors,
+      )
       expect(result.ok, `device ${orphanId} should NOT be allowed`).toBe(false)
     }
   })
@@ -143,14 +158,24 @@ describe('checkScopeAccess — device scope, accessory inheritance', () => {
 describe('checkScopeAccess — device scope, denial cases', () => {
   it('denies access to a sibling device not in the grant', () => {
     const scopes = [deviceScope(['5'], ['view'])]
-    const result = checkScopeAccess(scopes, 'webrtcSession.listStreams', { deviceId: 9 }, lookupAncestors)
+    const result = checkScopeAccess(
+      scopes,
+      'webrtcSession.listStreams',
+      { deviceId: 9 },
+      lookupAncestors,
+    )
     expect(result.ok).toBe(false)
     if (!result.ok) expect(result.reason).toContain('device=9')
   })
 
   it('denies create-flavoured methods when the grant is view-only', () => {
     const scopes = [deviceScope(['5'], ['view'])]
-    const result = checkScopeAccess(scopes, 'webrtcSession.createSession', { deviceId: 5 }, lookupAncestors)
+    const result = checkScopeAccess(
+      scopes,
+      'webrtcSession.createSession',
+      { deviceId: 5 },
+      lookupAncestors,
+    )
     expect(result.ok).toBe(false)
   })
 
@@ -162,11 +187,16 @@ describe('checkScopeAccess — device scope, denial cases', () => {
   })
 
   it('denies when the user has no scopes at all', () => {
-    const result = checkScopeAccess([], 'webrtcSession.listStreams', { deviceId: 5 }, lookupAncestors)
+    const result = checkScopeAccess(
+      [],
+      'webrtcSession.listStreams',
+      { deviceId: 5 },
+      lookupAncestors,
+    )
     expect(result.ok).toBe(false)
   })
 
-  it('does not leak across system-scope caps — device grant doesn\'t cover `addons.list`', () => {
+  it("does not leak across system-scope caps — device grant doesn't cover `addons.list`", () => {
     const scopes = [deviceScope(['5'], ['view', 'create', 'delete'])]
     // `addons.list` is system-scope; device scope shouldn't help.
     const result = checkScopeAccess(scopes, 'addons.list')
@@ -182,21 +212,36 @@ describe('checkScopeAccess — device scope mixed with other types', () => {
     // Operator hands out a broad viewer access. No `device` scope needed.
     const scopes: TokenScope[] = [{ type: 'category', target: 'device', access: ['view'] }]
     for (const id of [5, 7, 9, 51, 71]) {
-      const result = checkScopeAccess(scopes, 'cameraStreams.getCameraStreams', { deviceId: id }, lookupAncestors)
+      const result = checkScopeAccess(
+        scopes,
+        'cameraStreams.getCameraStreams',
+        { deviceId: id },
+        lookupAncestors,
+      )
       expect(result.ok, `category grant should cover device ${id}`).toBe(true)
     }
   })
 
   it('disjunction — device grant + capability grant compose by union', () => {
     const scopes: TokenScope[] = [
-      deviceScope(['5'], ['view', 'create']),                                    // PTZ, WebRTC on device 5 + accessories
-      { type: 'capability', target: 'camera-streams', access: ['view'] },        // read streams on any device
+      deviceScope(['5'], ['view', 'create']), // PTZ, WebRTC on device 5 + accessories
+      { type: 'capability', target: 'camera-streams', access: ['view'] }, // read streams on any device
     ]
     // Device 9 not in device grant, but capability grant lets streams through:
-    const streamRead = checkScopeAccess(scopes, 'cameraStreams.getCameraStreams', { deviceId: 9 }, lookupAncestors)
+    const streamRead = checkScopeAccess(
+      scopes,
+      'cameraStreams.getCameraStreams',
+      { deviceId: 9 },
+      lookupAncestors,
+    )
     expect(streamRead.ok).toBe(true)
     // But a create-flavoured method on device 9 still blocked:
-    const ptzMove = checkScopeAccess(scopes, 'webrtcSession.createSession', { deviceId: 9 }, lookupAncestors)
+    const ptzMove = checkScopeAccess(
+      scopes,
+      'webrtcSession.createSession',
+      { deviceId: 9 },
+      lookupAncestors,
+    )
     expect(ptzMove.ok).toBe(false)
   })
 })

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

@@ -11,7 +11,11 @@ import { describe, it, expect } from 'vitest'
 import { checkScopeAccess } from '../scope-access.js'
 import type { TokenScope } from '@camstack/types'
 
-function scope(type: 'addon' | 'capability', target: string, access: TokenScope['access']): TokenScope {
+function scope(
+  type: 'addon' | 'capability',
+  target: string,
+  access: TokenScope['access'],
+): TokenScope {
   return { type, target, access }
 }
 
@@ -29,20 +33,14 @@ describe('checkScopeAccess', () => {
   // ── Capability-typed scopes ─────────────────────────────────────
 
   it('accepts when capability scope matches target + access', () => {
-    const result = checkScopeAccess(
-      [scope('capability', 'backup', ['view'])],
-      'backup.list',
-    )
+    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'backup.list')
     expect(result.ok).toBe(true)
     if (result.ok) expect(result.access).toBe('view')
   })
 
   it('rejects when capability scope matches target but lacks the required access', () => {
     // backup.trigger requires `create`; the scope only grants `view`.
-    const result = checkScopeAccess(
-      [scope('capability', 'backup', ['view'])],
-      'backup.trigger',
-    )
+    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'backup.trigger')
     expect(result.ok).toBe(false)
     if (!result.ok) {
       // Matcher's reason format: "No scope grants <access> on '<cap>' (<scope>-scope cap)"
@@ -93,10 +91,7 @@ describe('checkScopeAccess', () => {
   // ── Reason string contains debug-friendly diff ──────────────────
 
   it('reason string surfaces what the caller actually has', () => {
-    const result = checkScopeAccess(
-      [scope('capability', 'devices', ['view'])],
-      'backup.trigger',
-    )
+    const result = checkScopeAccess([scope('capability', 'devices', ['view'])], 'backup.trigger')
     expect(result.ok).toBe(false)
     if (!result.ok) {
       // Format: "No scope grants create on 'backup' (system-scope cap). Have: capability:devices[view]"

package/src/api/trpc/__tests__/webrtc-session-ua-enrich.spec.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for the User-Agent enrichment the hub applies to the
+ * `webrtc-session` mount. The hub reads the UA from the tRPC request
+ * context and merges it into the subscriber attribution so the
+ * stream-broker SUBSCRIBERS panel can identify a browser viewer. Any
+ * client-supplied `userAgent` is OVERWRITTEN — the server trusts only the
+ * request context, never the client.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { IncomingMessage } from 'node:http'
+import type { InferProvider, BrokerConsumerAttribution } from '@camstack/types'
+import { webrtcSessionCapability } from '@camstack/types'
+import { enrichInputWithUserAgent, wrapWebrtcSessionProviderWithRelay } from '../trpc.router.js'
+import type { TrpcContext } from '../trpc.context.js'
+
+type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
+
+function reqWithUa(userAgent?: string): IncomingMessage {
+  const headers: Record<string, string | string[]> = {}
+  if (userAgent !== undefined) headers['user-agent'] = userAgent
+  return { headers, socket: {} } as unknown as IncomingMessage
+}
+
+describe('enrichInputWithUserAgent', () => {
+  it('passes input through unchanged when userAgent is null', () => {
+    const input = { deviceId: 1, consumerAttribution: { kind: 'webrtc-browser' } as const }
+    expect(enrichInputWithUserAgent(input, null)).toBe(input)
+  })
+
+  it('merges userAgent into an existing attribution (new object)', () => {
+    const attribution: BrokerConsumerAttribution = { kind: 'webrtc-browser', label: 'alice' }
+    const input = { deviceId: 1, consumerAttribution: attribution }
+    const out = enrichInputWithUserAgent(input, 'Chrome/120')
+    expect(out.consumerAttribution).toEqual({
+      kind: 'webrtc-browser',
+      label: 'alice',
+      userAgent: 'Chrome/120',
+    })
+    // Immutability: the original attribution is untouched.
+    expect(attribution.userAgent).toBeUndefined()
+  })
+
+  it('defaults to webrtc-browser when no attribution was supplied', () => {
+    const out = enrichInputWithUserAgent({ deviceId: 1 }, 'Firefox/121')
+    expect(out.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Firefox/121' })
+  })
+
+  it('OVERWRITES a client-supplied userAgent (never trust the client)', () => {
+    const input = {
+      deviceId: 1,
+      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed' } as const,
+    }
+    const out = enrichInputWithUserAgent(input, 'Safari/17')
+    expect(out.consumerAttribution?.userAgent).toBe('Safari/17')
+  })
+})
+
+describe('wrapWebrtcSessionProviderWithRelay — UA enrichment', () => {
+  function mockProvider(): WebrtcSessionProvider {
+    const createSession = vi.fn().mockResolvedValue({ sessionId: 's', sdpOffer: 'o' })
+    const handleOffer = vi.fn().mockResolvedValue({ sessionId: 's', sdpAnswer: 'a' })
+    const passthrough = vi.fn().mockResolvedValue(undefined)
+    return {
+      createSession,
+      handleOffer,
+      listStreams: vi.fn().mockResolvedValue([]),
+      handleAnswer: passthrough,
+      addIceCandidate: passthrough,
+      getIceCandidates: vi.fn().mockResolvedValue({ candidates: [], done: true }),
+      closeSession: passthrough,
+      hasAdaptiveBitrate: vi.fn().mockResolvedValue(false),
+      getSessionState: vi.fn().mockResolvedValue({ pendingRenegotiation: null }),
+    }
+  }
+
+  function ctxWith(userAgent?: string): TrpcContext {
+    return { user: null, req: reqWithUa(userAgent) }
+  }
+
+  it('injects the request UA into createSession attribution', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Edg/120'))
+
+    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
+
+    expect(provider.createSession).toHaveBeenCalledTimes(1)
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Edg/120' })
+  })
+
+  it('injects the request UA into handleOffer attribution', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('CriOS/120'))
+
+    await wrapped.handleOffer({ deviceId: 1, sdpOffer: 'x' })
+
+    const arg = vi.mocked(provider.handleOffer).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'CriOS/120' })
+  })
+
+  it('overwrites a client-supplied UA on createSession', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('TrustedUA/1'))
+
+    await wrapped.createSession({
+      deviceId: 1,
+      target: { kind: 'adaptive' },
+      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed', label: 'bob' },
+    })
+
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({
+      kind: 'webrtc-browser',
+      label: 'bob',
+      userAgent: 'TrustedUA/1',
+    })
+  })
+
+  it('does not alter the call when no UA header is present', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith(undefined))
+
+    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
+
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toBeUndefined()
+  })
+
+  it('delegates other methods straight through', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Chrome/120'))
+
+    await wrapped.closeSession({ deviceId: 1, sessionId: 's' })
+    expect(provider.closeSession).toHaveBeenCalledWith({ deviceId: 1, sessionId: 's' })
+  })
+})