@camstack/server 0.1.7 → 0.1.8

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

@@ -0,0 +1,128 @@
+/**
+ * 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' })
+  })
+})

package/src/api/trpc/cap-mount-helpers.ts

@@ -92,7 +92,18 @@ export function requireDeviceScoped<K extends keyof CapabilityProviderMap>(
             message: `Capability "${String(capName)}" provider for device ${deviceId} does not implement "${prop}"`,
           })
         }
-        return fn.call(native, input)
+        const result = await fn.call(native, input)
+        // Device-property-wiring overlay (read-time): only `getStatus`, and only
+        // when the device has links for this cap (resolveLinkedStatus returns
+        // null otherwise → base result untouched). One in-process singleton hop.
+        if (prop === 'getStatus') {
+          const deviceManager = registry.getSingleton<{
+            resolveLinkedStatus?: (i: { deviceId: number; cap: string; baseStatus: unknown }) => Promise<Record<string, unknown> | null>
+          }>('device-manager')
+          const overlaid = await deviceManager?.resolveLinkedStatus?.({ deviceId, cap: String(capName), baseStatus: result })
+          if (overlaid != null) return overlaid
+        }
+        return result
       }
     },
   })

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

@@ -53,6 +53,23 @@ export function extractClientIp(req: ClientRequest | undefined): string | null {
   return null
 }
 
+/**
+ * Best-effort read of the originating client's `User-Agent` header. Both
+ * request shapes in the union (`FastifyRequest` and the raw WS-transport
+ * `IncomingMessage`) expose `.headers['user-agent']`. Returns `null` when
+ * absent (mesh-originated calls carry no HTTP request, and some clients
+ * omit the header). Used by the `webrtc-session` mount to tag a browser
+ * subscriber's broker attribution with the viewer's UA — the SERVER reads
+ * it from the request context; any client-supplied value is ignored.
+ */
+export function extractUserAgent(req: ClientRequest | undefined): string | null {
+  if (!req) return null
+  const ua = req.headers['user-agent']
+  const value = Array.isArray(ua) ? ua[0] : ua
+  if (typeof value === 'string' && value.length > 0) return value
+  return null
+}
+
 /**
  * Strip an IPv4-mapped IPv6 prefix (`::ffff:192.168.1.5` → `192.168.1.5`)
  * and any zone id (`fe80::1%en0` → `fe80::1`) so the range checks below