@camstack/server 0.1.3

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

@@ -0,0 +1,248 @@
+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,
+      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__/scope-access-device.spec.ts

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

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

@@ -0,0 +1,107 @@
+/**
+ * Matrix tests for `checkScopeAccess`. Drives the scope-gate in
+ * `protectedProcedure`.
+ *
+ * The map (`METHOD_ACCESS_MAP`) is codegen-emitted; the test imports
+ * it indirectly via the helper so any drift between cap definitions
+ * and runtime would surface here as a test failure (e.g. a renamed
+ * method would no longer resolve to a known entry).
+ */
+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 {
+  return { type, target, access }
+}
+
+describe('checkScopeAccess', () => {
+  // ── Sanity: known paths resolve, unknown paths fail closed ──────
+
+  it('returns FORBIDDEN with codegen-drift reason for unknown paths', () => {
+    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'no-such.method')
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toContain('codegen drift')
+    }
+  })
+
+  // ── Capability-typed scopes ─────────────────────────────────────
+
+  it('accepts when capability scope matches target + access', () => {
+    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',
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      // Matcher's reason format: "No scope grants <access> on '<cap>' (<scope>-scope cap)"
+      expect(result.reason).toMatch(/No scope grants create on 'backup'/)
+    }
+  })
+
+  it('rejects when capability scope targets a different cap entirely', () => {
+    const result = checkScopeAccess(
+      [scope('capability', 'devices', ['view', 'create', 'delete'])],
+      'backup.list',
+    )
+    expect(result.ok).toBe(false)
+  })
+
+  it('accepts destructive method when scope includes delete', () => {
+    const result = checkScopeAccess(
+      [scope('capability', 'backup', ['view', 'delete'])],
+      'backup.delete',
+    )
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.access).toBe('delete')
+  })
+
+  // ── Scope unions ────────────────────────────────────────────────
+
+  it('union of access flavours satisfies any single requirement', () => {
+    const scopes: TokenScope[] = [
+      scope('capability', 'backup', ['view']),
+      scope('capability', 'backup', ['create']),
+    ]
+    // view request → first scope matches
+    expect(checkScopeAccess(scopes, 'backup.list').ok).toBe(true)
+    // create request → second scope matches
+    expect(checkScopeAccess(scopes, 'backup.trigger').ok).toBe(true)
+  })
+
+  // ── Empty scope set ─────────────────────────────────────────────
+
+  it('rejects when no scopes are granted at all', () => {
+    const result = checkScopeAccess([], 'backup.list')
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toContain('Have: (none)')
+    }
+  })
+
+  // ── Reason string contains debug-friendly diff ──────────────────
+
+  it('reason string surfaces what the caller actually has', () => {
+    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]"
+      expect(result.reason).toMatch(/No scope grants create on 'backup'/)
+      expect(result.reason).toContain('capability:devices[view]')
+    }
+  })
+})