# /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.