# testing-integration-oauth-mock

## Purpose

Real-HTTP mock OAuth 2.0 Identity Provider fixture for integration tests. Boots a `node:http` listener on an ephemeral `127.0.0.1` port and implements OAuth 2.0 authorization-code + refresh-token grants with PKCE, an OIDC discovery + JWKS pair (opt-in), GitHub/Google/Generic user shapes (or a custom mapper), and FIFO test-control levers (`primeUser`, `primeError`) plus a frozen audit log of every served request. Rule-8 testing-infrastructure package — zero `@suaveplan/*` runtime dependencies; only `node:*` builtins.

## Requirements

### Requirement: Exposes a controllable mock OAuth 2.0 IdP

The package SHALL export `createMockOauthIdp(opts)` returning a handle `{ url, port, stop, primeUser, primeError, lastRequest, allRequests }` backed by a real HTTP listener (`node:http` `createServer`) — not a mock library — implementing OAuth 2.0 authorization-code flow with PKCE.

#### Scenario: factory boots a real HTTP server on an ephemeral port

- **WHEN** `createMockOauthIdp({})` is called
- **THEN** `handle.url` is a `http://127.0.0.1:<port>` origin AND a `GET` to `${url}/authorize?...&state=abc` responds with a 302 carrying the same `state` and a generated `code`

#### Scenario: stop releases the port

- **WHEN** `handle.stop()` is called and awaited
- **THEN** the port is free for subsequent binds AND a second `GET` to the URL fails with `ECONNREFUSED`

**Verified by:** `src/server/server.test.ts::"factory boots a real HTTP server on an ephemeral port"` AND `src/server/server.test.ts::"stop releases the port"`

---

### Requirement: Implements authorize → token → userinfo round-trip

The IdP SHALL accept `GET /authorize` (state + code_challenge), `POST /token` (code + code_verifier exchange OR refresh-token grant), and `GET /userinfo` (Bearer authentication). The full round-trip MUST succeed without external network calls.

#### Scenario: full happy-path round-trip

- **WHEN** a client primes a user, hits `/authorize`, exchanges the returned code at `/token`, and fetches `/userinfo` with the access token
- **THEN** `/userinfo` returns the primed user payload AND `lastRequest()` records every step

#### Scenario: PKCE S256 challenge enforced

- **WHEN** `/token` is called with a `code_verifier` whose `SHA-256` does not match the original `code_challenge`
- **THEN** the response is HTTP 400 with `{ error: "invalid_grant" }`

#### Scenario: refresh-token grant rotates the token pair

- **WHEN** `/token` is called with `grant_type=refresh_token` and a valid refresh token
- **THEN** a new access+refresh pair is returned AND the previous refresh token is invalidated

**Verified by:** `src/server/server.test.ts::"full happy-path round-trip"` AND `src/endpoints/token.test.ts::"PKCE S256 challenge enforced — mismatch returns invalid_grant"` AND `src/endpoints/token.test.ts::"refresh-token grant rotates the token pair"`

---

### Requirement: Test-control levers (`primeUser`, `primeError`)

Tests SHALL be able to control IdP behaviour without restarting the server.

#### Scenario: primeUser seeds the next callback's user payload

- **WHEN** `handle.primeUser({ id: "42", login: "alice" })` is called before `/authorize`
- **THEN** the following `/userinfo` response carries `{ id: "42", login: "alice", ... }`

#### Scenario: primeError forces a specific RFC-6749 error

- **WHEN** `handle.primeError("access_denied")` is called and the user hits `/authorize`
- **THEN** the redirect carries `?error=access_denied` (no `code`)

#### Scenario: queues are FIFO

- **WHEN** `primeUser(A)` then `primeUser(B)` is called and two round-trips run
- **THEN** the first returns A and the second returns B

**Verified by:** `src/control/primer.test.ts::"primeUser seeds the next callback (FIFO)"` AND `src/control/primer.test.ts::"primeError forces a specific RFC-6749 error"` AND `src/control/primer.test.ts::"queues are FIFO across both lanes independently"`

---

### Requirement: Audit surface (`lastRequest`, `allRequests`)

The handle SHALL record every HTTP request the IdP served as a frozen snapshot: `{ method, path, headers, query, body, at }`.

#### Scenario: lastRequest returns the most recent record

- **WHEN** two requests are served and `handle.lastRequest()` is called
- **THEN** the returned record matches the second request

#### Scenario: allRequests returns a frozen ordered array

- **WHEN** `handle.allRequests()` is called
- **THEN** the returned array is frozen AND iterating it yields requests in serve-order

**Verified by:** `src/control/audit.test.ts::"lastRequest returns the most recent record"` AND `src/control/audit.test.ts::"allRequests returns a frozen ordered array"`

---

### Requirement: Provider-shaped user payloads

The factory SHALL accept `userShape: "github" | "google" | "generic"` (default `"github"`) or a custom mapper, producing realistic provider-shaped userinfo responses.

#### Scenario: github shape includes GitHub-canonical fields

- **WHEN** `userShape: "github"` is set and `primeUser({ id: 42 })` is called
- **THEN** `/userinfo` returns `{ id: 42, login, email, avatar_url, name, ... }`

**Verified by:** `src/shapes/github.test.ts::"populates canonical GitHub claims by default"` AND `src/shapes/github.test.ts::"honours primed id + login"`

---

### Requirement: No mocks; rule 8 testing-infrastructure compliance

The package MUST NOT depend on any `@suaveplan/*` runtime package and MUST NOT use mocking libraries (no `vi.mock`, no `jest.mock`). The server is a real `node:http` listener. Test files import test-runner primitives from `@suaveplan/testing/runner` per rule 11.

#### Scenario: no @suaveplan/* runtime deps

- **WHEN** `package.json` is inspected
- **THEN** the `dependencies` block contains no `@suaveplan/*` entry; `peerDependencies` may declare `@suaveplan/types` types-only

#### Scenario: test-runner imports go through @suaveplan/testing/runner

- **WHEN** `bun scripts/lint/check-test-runner-imports.ts` is run
- **THEN** the exit code is 0 (no direct `vitest` or `bun:test` imports inside `src/`)

**Verified by:** `tests/package-shape.test.ts::"package.json declares no @suaveplan/* runtime deps"` AND `tests/package-shape.test.ts::"no direct vitest or bun:test imports in src/"`