first commit

docs/testkit/testing/testing-integration-oauth-mock/src/error-codes/error-codes.md

@@ -0,0 +1,80 @@
+# 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.