@camstack/server 1.0.0 → 1.0.1

package/src/__tests__/oauth2-account-linking.spec.ts

@@ -1,867 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return, @typescript-eslint/consistent-type-assertions -- test file, mock typing */
-// server/backend/src/__tests__/oauth2-account-linking.spec.ts
-//
-// Integration test for the OAuth2 account-linking flow.
-//
-// Approach: in-process Fastify integration test using fastify.inject() —
-// no real network, no hub boot required.
-//
-// The sso-bridge stand-in is a real HMAC-JWT implementation backed by
-// Node's `crypto.createHmac` so access_token JWTs are genuine and their
-// payloads can be base64url-decoded and inspected (case 5).
-//
-import { describe, it, expect, beforeEach } from 'vitest'
-import Fastify from 'fastify'
-import cookie from '@fastify/cookie'
-import * as crypto from 'node:crypto'
-import { registerOauth2Routes } from '../api/oauth2/oauth2-routes.js'
-import { createOauthGrants } from '../../../../packages/core/src/builtins/local-auth/oauth-grants.js'
-import type { ISsoBridgeProvider } from '@camstack/types'
-import type {
-  IOauthIntegrationProvider,
-  IUserManagementProvider,
-  TokenScope,
-} from '@camstack/types'
-import type { OauthSession } from '../../../../packages/core/src/builtins/local-auth/oauth-session-manager.js'
-import { SESSION_COOKIE } from '../auth/session-cookie.js'
-
-// ─── HMAC-JWT sso-bridge stand-in ────────────────────────────────────────────
-//
-// Produces genuine JWTs (header.payload.signature) whose payload segment is
-// standard base64url-encoded JSON — so the test can decode the access token
-// claims without any special tooling.
-
-const JWT_SECRET = crypto.randomBytes(32).toString('hex')
-
-function base64url(buf: Buffer): string {
-  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
-}
-
-function makeHmacJwt(payload: Record<string, unknown>, ttlSec: number): string {
-  const header = base64url(Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })))
-  const body = base64url(
-    Buffer.from(
-      JSON.stringify({
-        ...payload,
-        iat: Math.floor(Date.now() / 1000),
-        exp: Math.floor(Date.now() / 1000) + ttlSec,
-      }),
-    ),
-  )
-  const sig = base64url(
-    crypto.createHmac('sha256', JWT_SECRET).update(`${header}.${body}`).digest(),
-  )
-  return `${header}.${body}.${sig}`
-}
-
-function verifyHmacJwt(token: string): Record<string, unknown> | null {
-  const parts = token.split('.')
-  if (parts.length !== 3) return null
-  const [header, body, sig] = parts as [string, string, string]
-  const expected = base64url(
-    crypto.createHmac('sha256', JWT_SECRET).update(`${header}.${body}`).digest(),
-  )
-  if (sig !== expected) return null
-  try {
-    const decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Record<
-      string,
-      unknown
-    >
-    if (typeof decoded['exp'] === 'number' && decoded['exp'] < Math.floor(Date.now() / 1000)) {
-      return null
-    }
-    return decoded
-  } catch {
-    return null
-  }
-}
-
-const realSsoBridge: ISsoBridgeProvider = {
-  signBridgeToken: async ({ claims, ttlSec }) => ({
-    token: makeHmacJwt(claims as Record<string, unknown>, ttlSec ?? 300),
-  }),
-  verifyBridgeToken: async ({ token }) => {
-    const decoded = verifyHmacJwt(token)
-    if (!decoded) return null
-    return decoded as any
-  },
-}
-
-// ─── In-memory fake OauthSessionManager ──────────────────────────────────────
-//
-// Mirrors the pattern in oauth-grants.spec.ts. The same instance is shared
-// between createOauthGrants and the fake user-management provider so sessions
-// created during token exchange are visible to listOauthSessions/revokeOauthSession.
-
-function fakeSessionManager() {
-  const store = new Map<string, OauthSession>()
-  let seq = 0
-
-  return {
-    store,
-    async create(input: {
-      userId: string
-      username: string
-      integrationId: string
-      scopes: TokenScope[]
-    }): Promise<OauthSession> {
-      const now = Date.now()
-      const session: OauthSession = {
-        id: `session-${++seq}`,
-        userId: input.userId,
-        username: input.username,
-        integrationId: input.integrationId,
-        scopes: input.scopes,
-        createdAt: now,
-        lastUsedAt: now,
-        revokedAt: null,
-      }
-      store.set(session.id, session)
-      return session
-    },
-    async list(): Promise<OauthSession[]> {
-      return Array.from(store.values())
-    },
-    async getById(id: string): Promise<OauthSession | null> {
-      return store.get(id) ?? null
-    },
-    async markRevoked(id: string): Promise<boolean> {
-      const existing = store.get(id)
-      if (!existing) return false
-      if (existing.revokedAt !== null) return true
-      store.set(id, { ...existing, revokedAt: Date.now() })
-      return true
-    },
-    async touch(id: string): Promise<void> {
-      const existing = store.get(id)
-      if (!existing) return
-      store.set(id, { ...existing, lastUsedAt: Date.now() })
-    },
-  }
-}
-
-// ─── Fixed operator credentials ───────────────────────────────────────────────
-
-const OPERATOR_USER_ID = 'user-1'
-const OPERATOR_USERNAME = 'operator'
-const VALID_SESSION_TOKEN = 'valid-session-token-abc123'
-
-// ─── Alexa integration descriptor ────────────────────────────────────────────
-
-const ALEXA_DESCRIPTOR = {
-  integrationId: 'export-alexa',
-  displayName: 'Alexa Smart Home',
-  requestedScopes: [
-    {
-      type: 'category' as const,
-      target: 'device' as const,
-      access: ['view', 'create'] as ('view' | 'create' | 'delete')[],
-    },
-  ],
-  allowedRedirectPrefixes: ['https://cb.example/'],
-}
-
-const REDIRECT_URI = 'https://cb.example/oauth/callback'
-const STATE = 'random-state-xyz'
-
-// ─── Fake registry ────────────────────────────────────────────────────────────
-//
-// Minimal CapabilityRegistry-shaped object. Only the methods called by
-// oauth2-routes are needed: getCollectionEntries and getSingleton.
-//
-// The sessionManager is shared between createOauthGrants and the fake
-// user-management provider so sessions created during exchange are visible
-// to listOauthSessions/revokeOauthSession.
-
-function buildFakeRegistry(
-  grants: ReturnType<typeof createOauthGrants>,
-  sessionManager: ReturnType<typeof fakeSessionManager>,
-): { getCollectionEntries: any; getSingleton: any } {
-  const alexaProvider: IOauthIntegrationProvider = {
-    getDescriptor: async () => ALEXA_DESCRIPTOR,
-  }
-
-  const userMgmt: IUserManagementProvider = {
-    ...({} as IUserManagementProvider),
-    oauthIssueCode: grants.oauthIssueCode.bind(grants),
-    oauthExchangeCode: grants.oauthExchangeCode.bind(grants),
-    oauthRefresh: grants.oauthRefresh.bind(grants),
-    oauthVerifyAccessToken: grants.oauthVerifyAccessToken.bind(grants),
-    listOauthSessions: async () => {
-      const sessions = await sessionManager.list()
-      return sessions.map((s) => ({
-        id: s.id,
-        userId: s.userId,
-        username: s.username,
-        integrationId: s.integrationId,
-        scopes: s.scopes,
-        createdAt: s.createdAt,
-        lastUsedAt: s.lastUsedAt,
-        revokedAt: s.revokedAt,
-      }))
-    },
-    revokeOauthSession: async (input: { id: string }) => {
-      const ok = await sessionManager.markRevoked(input.id)
-      return { success: ok }
-    },
-  }
-
-  return {
-    getCollectionEntries: (cap: string) => {
-      if (cap === 'oauth-integration') {
-        return [['export-alexa-addon', alexaProvider]] as [string, IOauthIntegrationProvider][]
-      }
-      return []
-    },
-    getSingleton: (cap: string) => {
-      if (cap === 'user-management') return userMgmt
-      return null
-    },
-  }
-}
-
-// ─── Test setup ───────────────────────────────────────────────────────────────
-
-function buildApp(
-  grants: ReturnType<typeof createOauthGrants>,
-  sessionManager: ReturnType<typeof fakeSessionManager>,
-) {
-  const fastify = Fastify({ logger: false })
-  void fastify.register(cookie)
-
-  const fakeRegistry = buildFakeRegistry(grants, sessionManager)
-
-  registerOauth2Routes(fastify, {
-    getRegistry: () => fakeRegistry as any,
-    verifyToken: (token: string) => {
-      if (token === VALID_SESSION_TOKEN) {
-        return { userId: OPERATOR_USER_ID, username: OPERATOR_USERNAME }
-      }
-      throw new Error('invalid token')
-    },
-    publicHubUrl: () => 'https://hub.example.com',
-  })
-
-  return fastify
-}
-
-// ─── Tests ────────────────────────────────────────────────────────────────────
-
-describe('OAuth2 account-linking flow', () => {
-  let grants: ReturnType<typeof createOauthGrants>
-  let sessionManager: ReturnType<typeof fakeSessionManager>
-  let app: ReturnType<typeof buildApp>
-
-  beforeEach(() => {
-    // Fresh session manager + grants instance per test so state is clean.
-    sessionManager = fakeSessionManager()
-    grants = createOauthGrants(realSsoBridge, sessionManager as any)
-    app = buildApp(grants, sessionManager)
-  })
-
-  // ── Case 1 ──────────────────────────────────────────────────────────────────
-  it('GET /api/oauth2/authorize with no session cookie and Accept: text/html → 302 to /login', async () => {
-    const url = `/api/oauth2/authorize?response_type=code&integration=export-alexa&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${STATE}`
-    const res = await app.inject({
-      method: 'GET',
-      url,
-      headers: { accept: 'text/html,application/xhtml+xml' },
-    })
-
-    expect(res.statusCode).toBe(302)
-    const location = res.headers['location'] as string
-    expect(location).toContain('/login?next=')
-  })
-
-  // ── Case 2 ──────────────────────────────────────────────────────────────────
-  it('GET /api/oauth2/authorize with valid session cookie → 200 consent HTML containing "Alexa Smart Home"', async () => {
-    const url = `/api/oauth2/authorize?response_type=code&integration=export-alexa&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${STATE}`
-    const res = await app.inject({
-      method: 'GET',
-      url,
-      headers: {
-        accept: 'text/html,application/xhtml+xml',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-    })
-
-    expect(res.statusCode).toBe(200)
-    expect(res.headers['content-type']).toContain('text/html')
-    expect(res.body).toContain('Alexa Smart Home')
-  })
-
-  // ── Case 3 ──────────────────────────────────────────────────────────────────
-  it('POST /api/oauth2/authorize consent=allow → 302 to redirect_uri with code and state', async () => {
-    const body = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const res = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body,
-    })
-
-    expect(res.statusCode).toBe(302)
-    const location = res.headers['location'] as string
-    expect(location).toMatch(
-      new RegExp(
-        `^${REDIRECT_URI.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\?code=.+&state=${STATE}`,
-      ),
-    )
-  })
-
-  // ── Case 4 ──────────────────────────────────────────────────────────────────
-  it('POST /api/oauth2/token authorization_code → access_token, refresh_token, expires_in: 3600, token_type: Bearer', async () => {
-    // First issue a code via the POST /api/oauth2/authorize step.
-    const authorizeBody = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const authorizeRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body: authorizeBody,
-    })
-
-    expect(authorizeRes.statusCode).toBe(302)
-    const location = authorizeRes.headers['location'] as string
-    const codeMatch = location.match(/[?&]code=([^&]+)/)
-    expect(codeMatch).not.toBeNull()
-    const code = decodeURIComponent(codeMatch![1]!)
-
-    // Now exchange the code for tokens.
-    const tokenBody = new URLSearchParams({
-      grant_type: 'authorization_code',
-      code,
-      redirect_uri: REDIRECT_URI,
-    }).toString()
-
-    const tokenRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/token',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: tokenBody,
-    })
-
-    expect(tokenRes.statusCode).toBe(200)
-    const json = tokenRes.json<{
-      access_token: string
-      refresh_token: string
-      expires_in: number
-      token_type: string
-    }>()
-    expect(json).toMatchObject({
-      expires_in: 3600,
-      token_type: 'Bearer',
-    })
-    expect(typeof json.access_token).toBe('string')
-    expect(json.access_token.length).toBeGreaterThan(0)
-    expect(typeof json.refresh_token).toBe('string')
-    expect(json.refresh_token.length).toBeGreaterThan(0)
-  })
-
-  // ── Case 5 ──────────────────────────────────────────────────────────────────
-  it('access_token payload contains isAdmin: false, scopes with device category, and correct username', async () => {
-    // Issue code.
-    const authorizeBody = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const authorizeRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body: authorizeBody,
-    })
-
-    const location = authorizeRes.headers['location'] as string
-    const codeMatch = location.match(/[?&]code=([^&]+)/)
-    const code = decodeURIComponent(codeMatch![1]!)
-
-    // Exchange code for tokens.
-    const tokenBody = new URLSearchParams({
-      grant_type: 'authorization_code',
-      code,
-      redirect_uri: REDIRECT_URI,
-    }).toString()
-
-    const tokenRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/token',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: tokenBody,
-    })
-
-    const json = tokenRes.json<{ access_token: string }>()
-    const accessToken = json.access_token
-
-    // Decode the JWT middle segment (payload) — base64url → JSON.
-    const parts = accessToken.split('.')
-    expect(parts).toHaveLength(3)
-    const payloadJson = Buffer.from(parts[1]!, 'base64url').toString('utf8')
-    const payload = JSON.parse(payloadJson) as Record<string, unknown>
-
-    expect(payload['isAdmin']).toBe(false)
-    expect(payload['username']).toBe(OPERATOR_USERNAME)
-
-    const scopes = payload['scopes'] as Array<Record<string, unknown>>
-    expect(Array.isArray(scopes)).toBe(true)
-    const deviceScope = scopes.find((s) => s['type'] === 'category' && s['target'] === 'device')
-    expect(deviceScope).toBeDefined()
-  })
-
-  // ── Case 6 ──────────────────────────────────────────────────────────────────
-  it('POST /api/oauth2/token with tampered code → 400 { error: "invalid_grant" }', async () => {
-    // Issue a real code first.
-    const authorizeBody = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const authorizeRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body: authorizeBody,
-    })
-
-    const location = authorizeRes.headers['location'] as string
-    const codeMatch = location.match(/[?&]code=([^&]+)/)
-    const code = decodeURIComponent(codeMatch![1]!)
-
-    // Tamper: mutate one character in the signature (last segment).
-    const parts = code.split('.')
-    const lastPart = parts[parts.length - 1]!
-    const firstChar = lastPart[0]!
-    const tamperedChar = firstChar === 'A' ? 'B' : 'A'
-    parts[parts.length - 1] = tamperedChar + lastPart.slice(1)
-    const tamperedCode = parts.join('.')
-
-    const tokenBody = new URLSearchParams({
-      grant_type: 'authorization_code',
-      code: tamperedCode,
-      redirect_uri: REDIRECT_URI,
-    }).toString()
-
-    const tokenRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/token',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: tokenBody,
-    })
-
-    expect(tokenRes.statusCode).toBe(400)
-    const json = tokenRes.json<{ error: string }>()
-    expect(json.error).toBe('invalid_grant')
-  })
-
-  // ── Case 7 ──────────────────────────────────────────────────────────────────
-  it('authenticated GET /api/oauth2/authorize with integration=bogus → 400', async () => {
-    const url = `/api/oauth2/authorize?response_type=code&integration=bogus&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${STATE}`
-    const res = await app.inject({
-      method: 'GET',
-      url,
-      headers: {
-        accept: 'text/html,application/xhtml+xml',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-    })
-
-    expect(res.statusCode).toBe(400)
-  })
-
-  // ── Case 8 ──────────────────────────────────────────────────────────────────
-  it('authenticated GET /api/oauth2/authorize with disallowed redirect_uri → 400, consent NOT rendered', async () => {
-    const disallowedUri = 'https://evil.example/grab'
-    const url = `/api/oauth2/authorize?response_type=code&integration=export-alexa&redirect_uri=${encodeURIComponent(disallowedUri)}&state=${STATE}`
-    const res = await app.inject({
-      method: 'GET',
-      url,
-      headers: {
-        accept: 'text/html,application/xhtml+xml',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-    })
-
-    expect(res.statusCode).toBe(400)
-    const json = res.json<{ error: string }>()
-    expect(json.error).toContain('redirect_uri not allowed')
-    expect(res.body).not.toContain('Alexa Smart Home')
-  })
-
-  // ── Case 8b ─────────────────────────────────────────────────────────────────
-  it('POST /api/oauth2/token refresh_token grant → 200 with new access_token, refresh_token, expires_in: 3600, token_type: Bearer', async () => {
-    // Step 1: Obtain an authorization code via POST /api/oauth2/authorize.
-    const authorizeBody = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const authorizeRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body: authorizeBody,
-    })
-
-    expect(authorizeRes.statusCode).toBe(302)
-    const location = authorizeRes.headers['location'] as string
-    const codeMatch = location.match(/[?&]code=([^&]+)/)
-    expect(codeMatch).not.toBeNull()
-    const code = decodeURIComponent(codeMatch![1]!)
-
-    // Step 2: Exchange the authorization code for an initial token pair.
-    const codeTokenBody = new URLSearchParams({
-      grant_type: 'authorization_code',
-      code,
-      redirect_uri: REDIRECT_URI,
-    }).toString()
-
-    const codeTokenRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/token',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: codeTokenBody,
-    })
-
-    expect(codeTokenRes.statusCode).toBe(200)
-    const initialJson = codeTokenRes.json<{ access_token: string; refresh_token: string }>()
-    const refreshToken = initialJson.refresh_token
-    expect(typeof refreshToken).toBe('string')
-    expect(refreshToken.length).toBeGreaterThan(0)
-
-    // Step 3: Use the refresh token to obtain a fresh token pair.
-    const refreshBody = new URLSearchParams({
-      grant_type: 'refresh_token',
-      refresh_token: refreshToken,
-    }).toString()
-
-    const refreshRes = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/token',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: refreshBody,
-    })
-
-    expect(refreshRes.statusCode).toBe(200)
-    const refreshJson = refreshRes.json<{
-      access_token: string
-      refresh_token: string
-      expires_in: number
-      token_type: string
-    }>()
-    expect(refreshJson).toMatchObject({ expires_in: 3600, token_type: 'Bearer' })
-    expect(typeof refreshJson.access_token).toBe('string')
-    expect(refreshJson.access_token.length).toBeGreaterThan(0)
-    expect(typeof refreshJson.refresh_token).toBe('string')
-    expect(refreshJson.refresh_token.length).toBeGreaterThan(0)
-
-    // Step 4: Decode the new access token payload and verify claims.
-    const parts = refreshJson.access_token.split('.')
-    expect(parts).toHaveLength(3)
-    const payloadJson = Buffer.from(parts[1]!, 'base64url').toString('utf8')
-    const payload = JSON.parse(payloadJson) as Record<string, unknown>
-
-    expect(payload['provider']).toBe('oauth-access')
-    expect(payload['isAdmin']).toBe(false)
-  })
-
-  // ── Case 9 ──────────────────────────────────────────────────────────────────
-  it('authenticated POST /api/oauth2/authorize consent=allow with disallowed redirect_uri → 400, no code issued', async () => {
-    const disallowedUri = 'https://evil.example/grab'
-    const body = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: disallowedUri,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-
-    const res = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body,
-    })
-
-    expect(res.statusCode).toBe(400)
-    const json = res.json<{ error: string }>()
-    expect(json.error).toContain('redirect_uri not allowed')
-    // Ensure no Location header with a code was issued
-    expect(res.headers['location']).toBeUndefined()
-  })
-
-  // ── Session registry lifecycle ───────────────────────────────────────────────
-  //
-  // These cases verify the end-to-end integration of OauthSessionManager with
-  // the OAuth2 routes: exchange creates a session, list/revoke work correctly,
-  // and revocation blocks subsequent refresh-token grants.
-
-  describe('session registry lifecycle', () => {
-    // Shared helper: run the full authorize → consent → exchange flow and
-    // return the issued token pair plus the raw location URL.
-    async function doFullFlow(): Promise<{
-      accessToken: string
-      refreshToken: string
-      location: string
-    }> {
-      const authorizeBody = new URLSearchParams({
-        consent: 'allow',
-        integration: 'export-alexa',
-        redirect_uri: REDIRECT_URI,
-        state: STATE,
-        response_type: 'code',
-      }).toString()
-
-      const authorizeRes = await app.inject({
-        method: 'POST',
-        url: '/api/oauth2/authorize',
-        headers: {
-          'content-type': 'application/x-www-form-urlencoded',
-          cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-        },
-        body: authorizeBody,
-      })
-
-      expect(authorizeRes.statusCode).toBe(302)
-      const location = authorizeRes.headers['location'] as string
-      const codeMatch = location.match(/[?&]code=([^&]+)/)
-      expect(codeMatch).not.toBeNull()
-      const code = decodeURIComponent(codeMatch![1]!)
-
-      const tokenBody = new URLSearchParams({
-        grant_type: 'authorization_code',
-        code,
-        redirect_uri: REDIRECT_URI,
-      }).toString()
-
-      const tokenRes = await app.inject({
-        method: 'POST',
-        url: '/api/oauth2/token',
-        headers: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: tokenBody,
-      })
-
-      expect(tokenRes.statusCode).toBe(200)
-      const json = tokenRes.json<{ access_token: string; refresh_token: string }>()
-      return { accessToken: json.access_token, refreshToken: json.refresh_token, location }
-    }
-
-    // ── Case a ────────────────────────────────────────────────────────────────
-    it('a) listOauthSessions() returns exactly 1 session after exchange, with correct fields', async () => {
-      await doFullFlow()
-
-      const sessions = await sessionManager.list()
-      expect(sessions).toHaveLength(1)
-
-      const session = sessions[0]!
-      expect(session.integrationId).toBe('export-alexa')
-      expect(session.username).toBe(OPERATOR_USERNAME)
-      expect(session.revokedAt).toBeNull()
-
-      // Scopes must contain the category/device entry declared in ALEXA_DESCRIPTOR.
-      expect(Array.isArray(session.scopes)).toBe(true)
-      const deviceScope = session.scopes.find((s) => s.type === 'category' && s.target === 'device')
-      expect(deviceScope).toBeDefined()
-    })
-
-    // ── Case b ────────────────────────────────────────────────────────────────
-    it('b) issued access_token payload carries sessionId matching the listed session', async () => {
-      const { accessToken } = await doFullFlow()
-
-      const sessions = await sessionManager.list()
-      expect(sessions).toHaveLength(1)
-      const listedSessionId = sessions[0]!.id
-
-      // Decode the JWT middle segment.
-      const parts = accessToken.split('.')
-      expect(parts).toHaveLength(3)
-      const payloadJson = Buffer.from(parts[1]!, 'base64url').toString('utf8')
-      const payload = JSON.parse(payloadJson) as Record<string, unknown>
-
-      expect(payload['sessionId']).toBe(listedSessionId)
-    })
-
-    // ── Case c ────────────────────────────────────────────────────────────────
-    it('c) revokeOauthSession({id}) returns {success:true} and session gains non-null revokedAt', async () => {
-      await doFullFlow()
-
-      const sessions = await sessionManager.list()
-      const sessionId = sessions[0]!.id
-
-      // Revoke via the fake user-management method (same as the real addon does).
-      const revokeResult = await sessionManager
-        .markRevoked(sessionId)
-        .then((ok) => ({ success: ok }))
-      expect(revokeResult).toEqual({ success: true })
-
-      // The session must now carry a non-null revokedAt.
-      const afterRevoke = await sessionManager.list()
-      expect(afterRevoke).toHaveLength(1)
-      expect(afterRevoke[0]!.revokedAt).not.toBeNull()
-    })
-
-    // ── Case d ────────────────────────────────────────────────────────────────
-    it('d) POST /api/oauth2/token refresh_token after session revocation → 400 invalid_grant', async () => {
-      const { refreshToken } = await doFullFlow()
-
-      // Revoke the session.
-      const sessions = await sessionManager.list()
-      await sessionManager.markRevoked(sessions[0]!.id)
-
-      // Attempt a refresh — must be rejected.
-      const refreshBody = new URLSearchParams({
-        grant_type: 'refresh_token',
-        refresh_token: refreshToken,
-      }).toString()
-
-      const refreshRes = await app.inject({
-        method: 'POST',
-        url: '/api/oauth2/token',
-        headers: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: refreshBody,
-      })
-
-      expect(refreshRes.statusCode).toBe(400)
-      const json = refreshRes.json<{ error: string }>()
-      expect(json.error).toBe('invalid_grant')
-    })
-
-    // ── Case e ────────────────────────────────────────────────────────────────
-    it('e) revokeOauthSession with unknown id → {success: false}', async () => {
-      const result = await sessionManager
-        .markRevoked('non-existent-session-id')
-        .then((ok) => ({ success: ok }))
-      expect(result).toEqual({ success: false })
-    })
-  })
-})
-
-// ─── Phase A: integration-driven hubUrl claim ───────────────────────────────
-//
-// The OAuth code/token JWT carries a `hubUrl` claim the cloud Lambda routes
-// back on. A forked exporter addon (which can't set the hub's env) declares its
-// operator-selected external-access endpoint on the oauth-integration
-// descriptor; the authorize route must prefer it over the hub-global
-// publicHubUrl() (which is localhost in dev — the cause of "linking fails after
-// consent").
-
-describe('integration-driven hubUrl claim (Phase A public-origin bridge)', () => {
-  const GLOBAL_FALLBACK = 'https://hub-global.example'
-
-  function buildAppWithDescriptor(descriptorHubUrl?: string) {
-    const sm = fakeSessionManager()
-    const g = createOauthGrants(realSsoBridge, sm as any)
-    const fastify = Fastify({ logger: false })
-    void fastify.register(cookie)
-
-    const descriptor = descriptorHubUrl
-      ? { ...ALEXA_DESCRIPTOR, hubUrl: descriptorHubUrl }
-      : { ...ALEXA_DESCRIPTOR }
-    const alexaProvider: IOauthIntegrationProvider = { getDescriptor: async () => descriptor }
-
-    const userMgmt: IUserManagementProvider = {
-      ...({} as IUserManagementProvider),
-      oauthIssueCode: g.oauthIssueCode.bind(g),
-      oauthExchangeCode: g.oauthExchangeCode.bind(g),
-      oauthRefresh: g.oauthRefresh.bind(g),
-      oauthVerifyAccessToken: g.oauthVerifyAccessToken.bind(g),
-      listOauthSessions: async () => [],
-      revokeOauthSession: async () => ({ success: true }),
-    }
-
-    const reg = {
-      getCollectionEntries: (cap: string) =>
-        cap === 'oauth-integration' ? [['export-alexa-addon', alexaProvider]] : [],
-      getSingleton: (cap: string) => (cap === 'user-management' ? userMgmt : null),
-    }
-
-    registerOauth2Routes(fastify, {
-      getRegistry: () => reg as any,
-      verifyToken: (token: string) => {
-        if (token === VALID_SESSION_TOKEN)
-          return { userId: OPERATOR_USER_ID, username: OPERATOR_USERNAME }
-        throw new Error('invalid token')
-      },
-      publicHubUrl: () => GLOBAL_FALLBACK,
-    })
-    return fastify
-  }
-
-  async function issuedCodeHubUrl(
-    app: ReturnType<typeof buildAppWithDescriptor>,
-  ): Promise<unknown> {
-    const body = new URLSearchParams({
-      consent: 'allow',
-      integration: 'export-alexa',
-      redirect_uri: REDIRECT_URI,
-      state: STATE,
-      response_type: 'code',
-    }).toString()
-    const res = await app.inject({
-      method: 'POST',
-      url: '/api/oauth2/authorize',
-      headers: {
-        'content-type': 'application/x-www-form-urlencoded',
-        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
-      },
-      body,
-    })
-    expect(res.statusCode).toBe(302)
-    const loc = res.headers['location'] as string
-    const code = decodeURIComponent(loc.match(/[?&]code=([^&]+)/)![1]!)
-    const payload = JSON.parse(
-      Buffer.from(code.split('.')[1]!, 'base64url').toString('utf8'),
-    ) as Record<string, unknown>
-    return payload['hubUrl']
-  }
-
-  it('bakes the integration descriptor hubUrl into the issued code', async () => {
-    const app = buildAppWithDescriptor('https://tunnel.example.test')
-    expect(await issuedCodeHubUrl(app)).toBe('https://tunnel.example.test')
-  })
-
-  it('falls back to publicHubUrl() when the descriptor has no hubUrl', async () => {
-    const app = buildAppWithDescriptor()
-    expect(await issuedCodeHubUrl(app)).toBe(GLOBAL_FALLBACK)
-  })
-})