# OAUTH_MOCK error codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module defines the closed registry of error codes raised by
`@suaveplan/testing-integration-oauth-mock`. The package is rule-8
testing-infrastructure and so cannot depend on `@suaveplan/error`; instead
it rolls a minimal `OauthMockError` class that carries the same shape
(`code`, `message`, optional `cause`, optional immutable `context`) and
satisfies tests that need to assert on stable code strings without coupling
the fixture to the runtime error library.

Every internal failure path — invalid PKCE verifier, unknown auth code,
exhausted primer queue, unrecognised user shape — surfaces a code in this
registry rather than a bare `Error`, giving test authors a stable string
contract to assert against when they want to drive negative-path
scenarios through the mock IdP.

## Features

- Closed registry constant `OAUTH_MOCK_CODES` with eleven canonical codes.
- Branded `OauthMockErrorCode` union type for compile-time exhaustiveness.
- `OauthMockError extends Error` with `code`, frozen `context`, and
  optional `cause` preserved via the standard ES2022 `Error.cause` slot.
- Zero `@suaveplan/*` runtime dependency (rule 8).

## Usage: Basic

```ts
import {
    OAUTH_MOCK_CODES,
    OauthMockError,
} from "@suaveplan/testing-integration-oauth-mock/error-codes";

throw new OauthMockError(
    OAUTH_MOCK_CODES.UNKNOWN_AUTH_CODE,
    "no such code",
);
```

## Usage: Advanced

Attach structured context and chain a cause when re-throwing across
endpoint boundaries:

```ts
try {
    verifyPkce(challenge, verifier);
} catch (cause) {
    throw new OauthMockError(
        OAUTH_MOCK_CODES.INVALID_PKCE_VERIFIER,
        "verifier hash mismatch",
        { cause, context: { method: "S256" } },
    );
}
```

## API Reference

- `OAUTH_MOCK_CODES` — frozen string-keyed map of canonical codes.
- `OauthMockErrorCode` — union type of the registry values.
- `class OauthMockError extends Error` — constructor
  `(code, message, options?: { cause?; context? })`. Exposes
  `code: OauthMockErrorCode`, `context: Readonly<Record<string, unknown>>`,
  and optional inherited `cause`.

## Implementation Notes

`context` is sealed with `Object.freeze` at construction time so callers
who pass a live reference cannot mutate the recorded context after the
error has propagated up the stack. The class extends the platform `Error`
so structured cloning, `instanceof`, and stack traces continue to behave
in the natural way. Codes use the dot-namespaced form
`OAUTH_MOCK.<CASE>` for grep-ability and to match the wider Suaveplan
code-namespace convention even though the package does not consume
`@suaveplan/error` directly.