Initial Commit

packages/testkit/testing/testing-integration-oauth-mock/src/endpoints/authorize.md

@@ -0,0 +1,61 @@
+# /authorize endpoint
+
+## Purpose
+
+`handleAuthorize` implements the OAuth 2.0 authorization-code endpoint
+(RFC-6749 §4.1.1) for the mock IdP. It issues a fresh authorization
+code, persists the PKCE challenge for later verification by the token
+endpoint, and redirects the user-agent back to the caller's
+`redirect_uri` with `code` and `state` parameters echoed.
+
+If a test has primed an RFC-6749 error via `primeError`, the function
+short-circuits and redirects with `?error=<code>` instead — letting test
+authors drive the IdP's negative paths deterministically without
+swapping out implementations.
+
+## Features
+
+- 302 redirect with `code` + echoed `state`.
+- Captures PKCE `code_challenge` and `code_challenge_method`
+  (`plain` | `S256`), discarding unsupported methods.
+- Primed error redirect honours RFC-6749 error parameter format.
+- Pops the next primed user from the FIFO primer queue and stores it on
+  the auth-code record for later `/userinfo` retrieval.
+
+## Usage: Basic
+
+```ts
+const result = handleAuthorize(state, {
+    redirect_uri: "http://app/cb",
+    state: "csrf",
+    code_challenge: "abc",
+    code_challenge_method: "S256",
+});
+// → 302 Location: http://app/cb?code=…&state=csrf
+```
+
+## Usage: Advanced
+
+To force a primed error path:
+
+```ts
+state.primer.primeError("access_denied");
+handleAuthorize(state, { redirect_uri: "http://app/cb" });
+// → 302 Location: http://app/cb?error=access_denied
+```
+
+## API Reference
+
+- `handleAuthorize(state, query): AuthorizeResult`
+- `interface AuthorizeResult` — `{ status: 302, location: string,
+  code?: string, error?: string }`.
+
+## Implementation Notes
+
+`redirect_uri` is the only mandatory query parameter — when missing, the
+function returns a sentinel `error` string and an empty `location`
+because there is no safe URL to redirect to. Invalid PKCE methods are
+silently downgraded to "no PKCE captured"; the token endpoint then
+treats the exchange as PKCE-disabled. The primed user queue is consumed
+even when no PKCE challenge is provided so the test author's intent
+(prime then drive) is preserved in either flow.