@camstack/server 0.2.2 → 1.0.1

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

@@ -1,281 +0,0 @@
-import type { FastifyInstance } from 'fastify'
-import type { CapabilityRegistry } from '@camstack/kernel'
-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'
-
-export interface AuthorizeQuery {
-  response_type?: string
-  integration?: string
-  redirect_uri?: string
-  state?: string
-}
-
-export type AuthorizeValidation =
-  | { ok: true; integration: string; redirectUri: string; state: string }
-  | { ok: false; status: number; error: string }
-
-/** 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' }
-  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 {
-  return allowedPrefixes.some((p) => redirectUri.startsWith(p))
-}
-
-/** One-line human summary of a scope list for the consent screen. */
-export function summariseScopes(scopes: readonly TokenScope[]): string {
-  if (scopes.some((s) => s.type === 'category' && s.target === 'device')) {
-    return 'view and control all your cameras and devices'
-  }
-  return scopes.map((s) => s.type).join(', ') || 'no permissions'
-}
-
-export interface Oauth2Deps {
-  getRegistry: () => CapabilityRegistry | null
-  verifyToken: (token: string) => { userId?: string; username?: string }
-  publicHubUrl: () => string
-}
-
-/** Build a map of integrationId → descriptor from all registered oauth-integration providers. */
-async function buildIntegrationMap(
-  registry: CapabilityRegistry,
-): Promise<{ descriptorMap: Map<string, OauthIntegrationDescriptor>; knownSet: Set<string> }> {
-  const entries = registry.getCollectionEntries<IOauthIntegrationProvider>('oauth-integration')
-  const descriptorMap = new Map<string, OauthIntegrationDescriptor>()
-  for (const [, provider] of entries) {
-    const descriptor = await provider.getDescriptor()
-    descriptorMap.set(descriptor.integrationId, descriptor)
-  }
-  const knownSet = new Set(descriptorMap.keys())
-  return { descriptorMap, knownSet }
-}
-
-/** Parse an application/x-www-form-urlencoded body string into a plain object. */
-function parseFormBody(raw: string): Record<string, string> {
-  const params = new URLSearchParams(raw)
-  const result: Record<string, string> = {}
-  for (const [key, value] of params.entries()) {
-    result[key] = value
-  }
-  return result
-}
-
-export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps): void {
-  // Register a content-type parser for application/x-www-form-urlencoded so that
-  // consent POST and token POST can read form bodies. @fastify/formbody is not in
-  // the project's dependencies; we use URLSearchParams (Node built-in) instead.
-  fastify.addContentTypeParser(
-    'application/x-www-form-urlencoded',
-    { parseAs: 'string' },
-    (_req, body, done) => {
-      try {
-        done(null, parseFormBody(body as string))
-      } catch (err) {
-        done(err as Error, undefined)
-      }
-    },
-  )
-
-  // ─── GET /api/oauth2/authorize ────────────────────────────────────────────
-  // Mounted under /api/* so it is naturally excluded from the SPA catch-all,
-  // the PWA service-worker navigate fallback, and the Vite dev proxy — no
-  // per-path special-casing anywhere.
-  fastify.get('/api/oauth2/authorize', async (request, reply) => {
-    const cookie = (request.cookies as Record<string, string | undefined>)[SESSION_COOKIE]
-    if (!cookie) {
-      if (shouldRedirectToLogin(request.method, request.headers.accept)) {
-        return reply.redirect(loginRedirectUrl(request.url))
-      }
-      return reply.status(401).send({ error: 'unauthorized' })
-    }
-
-    let tokenInfo: { userId?: string; username?: string }
-    try {
-      tokenInfo = deps.verifyToken(cookie)
-    } catch {
-      if (shouldRedirectToLogin(request.method, request.headers.accept)) {
-        return reply.redirect(loginRedirectUrl(request.url))
-      }
-      return reply.status(401).send({ error: 'unauthorized' })
-    }
-
-    const registry = deps.getRegistry()
-    if (!registry) {
-      return reply.status(503).send({ error: 'service_unavailable' })
-    }
-
-    const { descriptorMap, knownSet } = await buildIntegrationMap(registry)
-    const query = request.query as AuthorizeQuery
-    const v = validateAuthorizeQuery(query, knownSet)
-    if (!v.ok) {
-      return reply.status(v.status).send({ error: v.error })
-    }
-
-    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' })
-    }
-
-    const html = renderConsentPage({
-      displayName: descriptor.displayName,
-      username: tokenInfo.username ?? '',
-      scopeSummary: summariseScopes(descriptor.requestedScopes),
-      hidden: {
-        integration: v.integration,
-        redirect_uri: v.redirectUri,
-        state: v.state,
-        response_type: 'code',
-      },
-    })
-    return reply.type('text/html').send(html)
-  })
-
-  // ─── POST /api/oauth2/authorize ───────────────────────────────────────────
-  fastify.post('/api/oauth2/authorize', async (request, reply) => {
-    const cookie = (request.cookies as Record<string, string | undefined>)[SESSION_COOKIE]
-    if (!cookie) {
-      if (shouldRedirectToLogin(request.method, request.headers.accept)) {
-        return reply.redirect(loginRedirectUrl(request.url))
-      }
-      return reply.status(401).send({ error: 'unauthorized' })
-    }
-
-    let tokenInfo: { userId?: string; username?: string }
-    try {
-      tokenInfo = deps.verifyToken(cookie)
-    } catch {
-      if (shouldRedirectToLogin(request.method, request.headers.accept)) {
-        return reply.redirect(loginRedirectUrl(request.url))
-      }
-      return reply.status(401).send({ error: 'unauthorized' })
-    }
-
-    const registry = deps.getRegistry()
-    if (!registry) {
-      return reply.status(503).send({ error: 'service_unavailable' })
-    }
-
-    const { descriptorMap, knownSet } = await buildIntegrationMap(registry)
-    const body = request.body as Record<string, string | undefined>
-    const formQuery: AuthorizeQuery = {
-      response_type: body.response_type,
-      integration: body.integration,
-      redirect_uri: body.redirect_uri,
-      state: body.state,
-    }
-    const v = validateAuthorizeQuery(formQuery, knownSet)
-    if (!v.ok) {
-      return reply.status(v.status).send({ error: v.error })
-    }
-
-    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' })
-    }
-
-    if (body.consent !== 'allow') {
-      return reply.redirect(
-        `${v.redirectUri}?error=access_denied&state=${encodeURIComponent(v.state)}`,
-      )
-    }
-
-    const userMgmt = registry.getSingleton<IUserManagementProvider>('user-management')
-    if (!userMgmt) {
-      return reply.status(503).send({ error: 'service_unavailable' })
-    }
-
-    const { code } = await userMgmt.oauthIssueCode({
-      integrationId: v.integration,
-      userId: tokenInfo.userId ?? '',
-      username: tokenInfo.username ?? '',
-      scopes: descriptor.requestedScopes,
-      redirectUri: v.redirectUri,
-      // Prefer the integration's own public origin (e.g. the operator-selected
-      // external-access endpoint surfaced by a forked exporter addon) so the
-      // claim the cloud Lambda routes back on is the reachable public URL, not
-      // the hub-global fallback (which defaults to localhost in dev).
-      hubUrl: descriptor.hubUrl ?? deps.publicHubUrl(),
-    })
-
-    return reply.redirect(
-      `${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`,
-    )
-  })
-
-  // ─── POST /api/oauth2/token ───────────────────────────────────────────────
-  // No session gate — called by Alexa/Lambda directly.
-  fastify.post('/api/oauth2/token', async (request, reply) => {
-    const registry = deps.getRegistry()
-    if (!registry) {
-      return reply.status(503).send({ error: 'service_unavailable' })
-    }
-
-    const userMgmt = registry.getSingleton<IUserManagementProvider>('user-management')
-    if (!userMgmt) {
-      return reply.status(503).send({ error: 'service_unavailable' })
-    }
-
-    const body = request.body as Record<string, string | undefined>
-
-    type TokenResult = { accessToken: string; refreshToken: string; expiresIn: number } | null
-
-    let tokenResult: TokenResult
-    if (body.grant_type === 'authorization_code') {
-      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,
-      })
-    } else if (body.grant_type === 'refresh_token') {
-      if (!body.refresh_token) {
-        return reply.status(400).send({ error: 'invalid_request' })
-      }
-      tokenResult = await userMgmt.oauthRefresh({ refreshToken: body.refresh_token })
-    } else {
-      return reply.status(400).send({ error: 'unsupported_grant_type' })
-    }
-
-    if (tokenResult === null) {
-      return reply.status(400).send({ error: 'invalid_grant' })
-    }
-
-    return reply.send({
-      access_token: tokenResult.accessToken,
-      refresh_token: tokenResult.refreshToken,
-      expires_in: tokenResult.expiresIn,
-      token_type: 'Bearer',
-    })
-  })
-}

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

@@ -1,146 +0,0 @@
-/**
- * Unit tests for the client-IP extraction + LAN/remote classification
- * used by the `webrtcSession.createSession` relay-only override.
- *
- * The classification is the load-bearing decision: a `true` from
- * `isRemoteClientIp` forces TURN-relay-only ICE for that live-view
- * session. A false positive would needlessly relay a LAN viewer
- * (latency); a false negative would leave a remote viewer on the dead
- * direct path (the bug being fixed). The private-range edges are
- * therefore exercised explicitly.
- */
-import { describe, it, expect } from 'vitest'
-import type { IncomingMessage } from 'node:http'
-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 },
-  } as unknown as IncomingMessage
-  if (opts.ip !== undefined) {
-    Object.defineProperty(req, 'ip', { value: opts.ip, enumerable: true })
-  }
-  return req
-}
-
-describe('extractClientIp', () => {
-  it('returns null for an absent request (mesh-originated call)', () => {
-    expect(extractClientIp(undefined)).toBeNull()
-  })
-
-  it('prefers the first X-Forwarded-For hop over socket/ip', () => {
-    const req = reqWith({ xff: '203.0.113.7, 10.0.0.1', ip: '10.0.0.1', remoteAddress: '10.0.0.1' })
-    expect(extractClientIp(req)).toBe('203.0.113.7')
-  })
-
-  it('handles X-Forwarded-For as an array', () => {
-    const req = reqWith({ xff: ['198.51.100.4, 10.0.0.1'] })
-    expect(extractClientIp(req)).toBe('198.51.100.4')
-  })
-
-  it('falls back to req.ip when no XFF', () => {
-    const req = reqWith({ ip: '192.168.1.50', remoteAddress: '192.168.1.50' })
-    expect(extractClientIp(req)).toBe('192.168.1.50')
-  })
-
-  it('falls back to socket.remoteAddress when no XFF or ip', () => {
-    const req = reqWith({ remoteAddress: '127.0.0.1' })
-    expect(extractClientIp(req)).toBe('127.0.0.1')
-  })
-
-  it('strips IPv4-mapped IPv6 prefix', () => {
-    const req = reqWith({ remoteAddress: '::ffff:192.168.1.5' })
-    expect(extractClientIp(req)).toBe('192.168.1.5')
-  })
-
-  it('strips IPv6 zone id', () => {
-    const req = reqWith({ remoteAddress: 'fe80::1%en0' })
-    expect(extractClientIp(req)).toBe('fe80::1')
-  })
-})
-
-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)
-  })
-
-  // Private / loopback / link-local / Tailscale ranges → LAN (direct path kept)
-  const lan = [
-    '10.0.0.1',
-    '10.255.255.255',
-    '172.16.0.1',
-    '172.31.255.255',
-    '192.168.1.1',
-    '127.0.0.1',
-    '169.254.1.1',
-    // Tailscale CGNAT overlay (100.64.0.0/10) — direct host↔host over the mesh
-    '100.64.0.1', // bottom of 100.64/10
-    '100.104.179.3', // the hub's own Tailscale IP (confirmed live)
-    '100.127.255.255', // top of 100.64/10
-    '::1',
-    'fe80::1',
-    'fc00::1',
-    'fd12:3456::1',
-    // Tailscale ULA overlay (fd7a::/16) — subset of fc00::/7
-    'fd7a:115c:a1e0::1',
-  ]
-  for (const ip of lan) {
-    it(`LAN: ${ip} → not remote`, () => {
-      expect(isRemoteClientIp(ip)).toBe(false)
-    })
-  }
-
-  // Public ranges → remote (relay-only forced)
-  const remote = [
-    '203.0.113.7', // TEST-NET-3 (public)
-    '8.8.8.8',
-    '172.15.0.1', // just below the 172.16/12 private block
-    '172.32.0.1', // just above the 172.16/12 private block
-    '11.0.0.1', // just above 10/8
-    '100.63.255.255', // just below the 100.64/10 Tailscale block (public)
-    '100.128.0.1', // just above the 100.64/10 Tailscale block (public)
-    '2001:4860:4860::8888', // public IPv6
-  ]
-  for (const ip of remote) {
-    it(`remote: ${ip} → remote`, () => {
-      expect(isRemoteClientIp(ip)).toBe(true)
-    })
-  }
-
-  it('unparseable literal → false (conservative LAN default)', () => {
-    expect(isRemoteClientIp('not-an-ip')).toBe(false)
-  })
-})

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

@@ -1,268 +0,0 @@
-/**
- * Behaviour tests for the `device` scope type — the operator's main lever
- * for "this user can manage cameras 5 and 7 only".
- *
- * Coverage matrix:
- *  - Direct device match: every device-scope cap method on a granted
- *    deviceId is allowed (PTZ, WebRTC, switch, intercom, reboot, …).
- *  - Accessory inheritance: a grant on a Reolink parent (deviceId=5)
- *    transparently covers its child accessories (siren=51, floodlight=52,
- *    PIR=53). No re-listing required.
- *  - Negative path: devices NOT in the grant — including unrelated
- *    siblings AND accessories of un-granted parents — are denied.
- *  - Access tier: a `view`-only grant doesn't permit `create`-flavoured
- *    methods on the same device.
- *  - Decoupling: device scopes don't bleed into system-scope caps; a
- *    non-admin with only `device:5` still gets 403 on `addons.list` etc.
- *  - JWT staleness: a child accessory adopted AFTER the grant is still
- *    covered (the matcher walks the live tree, not a frozen snapshot).
- *
- * The fixture mimics the Reolink topology described in CLAUDE.md:
- *   - device 5 (Reolink camera, parent)
- *     ├── device 51 (siren accessory)
- *     ├── device 52 (floodlight accessory)
- *     └── device 53 (PIR accessory)
- *   - device 7 (Hikvision camera, parent)
- *     └── device 71 (siren accessory)
- *   - device 9 (Frigate camera, NO accessories, NOT granted)
- */
-import { describe, it, expect } from 'vitest'
-import { checkScopeAccess, type DeviceAncestorLookup } from '../scope-access.js'
-import type { TokenScope } from '@camstack/types'
-
-// ── Fixtures ────────────────────────────────────────────────────────
-
-interface DeviceNode {
-  readonly id: number
-  readonly parentDeviceId: number | null
-}
-
-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)
-]
-
-/** Walks the parent chain — mirrors the real lookup in trpc.context.ts. */
-const lookupAncestors: DeviceAncestorLookup = (deviceId) => {
-  const out: number[] = []
-  let current = TREE.find((d) => d.id === deviceId)
-  for (let hop = 0; hop < 8 && current?.parentDeviceId != null; hop++) {
-    out.push(current.parentDeviceId)
-    current = TREE.find((d) => d.id === current?.parentDeviceId)
-  }
-  return out
-}
-
-function deviceScope(targets: readonly string[], access: TokenScope['access']): TokenScope {
-  return { type: 'device', targets: [...targets], access: [...access] }
-}
-
-/**
- * Representative device-scope cap methods drawn from `METHOD_ACCESS_MAP`.
- * Picked one of each access flavour and a mix of cap families so the
- * test fails on real codegen drift (renamed cap, dropped method) not
- * just on the matcher's logic.
- */
-const VIEW_METHODS = [
-  '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
-] as const
-
-// ── Direct match — granted device, any cap method ──────────────────
-
-describe('checkScopeAccess — device scope, direct grant', () => {
-  it('admits every view-flavoured device cap on the granted deviceId', () => {
-    const scopes = [deviceScope(['5'], ['view'])]
-    for (const path of VIEW_METHODS) {
-      const result = checkScopeAccess(scopes, path, { deviceId: 5 }, lookupAncestors)
-      expect(result.ok, `${path} should be allowed for view-granted device`).toBe(true)
-    }
-  })
-
-  it('admits create-flavoured methods when the grant includes `create`', () => {
-    const scopes = [deviceScope(['5'], ['view', 'create'])]
-    for (const path of CREATE_METHODS) {
-      const result = checkScopeAccess(scopes, path, { deviceId: 5 }, lookupAncestors)
-      expect(result.ok, `${path} should be allowed for create-granted device`).toBe(true)
-    }
-  })
-
-  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,
-      )
-      expect(result.ok, `device ${id} should be allowed`).toBe(true)
-    }
-  })
-})
-
-// ── Accessory inheritance — children of granted parent ─────────────
-
-describe('checkScopeAccess — device scope, accessory inheritance', () => {
-  it('grant on parent 5 covers siren child 51', () => {
-    const scopes = [deviceScope(['5'], ['view', 'create'])]
-    const result = checkScopeAccess(scopes, 'switch.setState', { deviceId: 51 }, lookupAncestors)
-    expect(result.ok).toBe(true)
-  })
-
-  it('grant on parent 5 covers floodlight 52', () => {
-    const scopes = [deviceScope(['5'], ['view', 'create'])]
-    const result = checkScopeAccess(scopes, 'switch.setState', { deviceId: 52 }, lookupAncestors)
-    expect(result.ok).toBe(true)
-  })
-
-  it('grant on parent 5 covers PIR 53 (read-only)', () => {
-    const scopes = [deviceScope(['5'], ['view'])]
-    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,
-      )
-      expect(result.ok, `device ${orphanId} should NOT be allowed`).toBe(false)
-    }
-  })
-})
-
-// ── Negative paths — unscoped devices, missing access ──────────────
-
-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,
-    )
-    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,
-    )
-    expect(result.ok).toBe(false)
-  })
-
-  it('denies access on accessory whose parent is NOT in the grant', () => {
-    // grant on 7, but try to act on accessory 51 (whose parent is 5)
-    const scopes = [deviceScope(['7'], ['view', 'create'])]
-    const result = checkScopeAccess(scopes, 'switch.setState', { deviceId: 51 }, lookupAncestors)
-    expect(result.ok).toBe(false)
-  })
-
-  it('denies when the user has no scopes at all', () => {
-    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`", () => {
-    const scopes = [deviceScope(['5'], ['view', 'create', 'delete'])]
-    // `addons.list` is system-scope; device scope shouldn't help.
-    const result = checkScopeAccess(scopes, 'addons.list')
-    expect(result.ok).toBe(false)
-    if (!result.ok) expect(result.reason).toContain('system-scope cap')
-  })
-})
-
-// ── Composition with other scope types ─────────────────────────────
-
-describe('checkScopeAccess — device scope mixed with other types', () => {
-  it('a `category:device [view]` grant is open across all devices regardless of device scope', () => {
-    // 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,
-      )
-      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
-    ]
-    // Device 9 not in device grant, but capability grant lets streams through:
-    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,
-    )
-    expect(ptzMove.ok).toBe(false)
-  })
-})
-
-// ── Edge cases — input shape & malformed scopes ────────────────────
-
-describe('checkScopeAccess — device scope, edge cases', () => {
-  it('falls back to deny when the input has no deviceId (device-scope cap requires one)', () => {
-    const scopes = [deviceScope(['5'], ['view'])]
-    // No deviceId in input → matcher can't locate the target → reject.
-    const result = checkScopeAccess(scopes, 'webrtcSession.listStreams', {}, lookupAncestors)
-    expect(result.ok).toBe(false)
-  })
-
-  it('works without a registry — direct match only, no inheritance', () => {
-    // No `getDeviceAncestors` (e.g. in a tRPC context that didn't wire one).
-    // Direct device grant still works; child accessory does NOT inherit.
-    const scopes = [deviceScope(['5'], ['view'])]
-    const directHit = checkScopeAccess(scopes, 'webrtcSession.listStreams', { deviceId: 5 })
-    expect(directHit.ok).toBe(true)
-    const childMiss = checkScopeAccess(scopes, 'webrtcSession.listStreams', { deviceId: 51 })
-    expect(childMiss.ok).toBe(false)
-  })
-})