@camstack/server 0.1.3

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

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