OAUTH_MOCK error codes

(no submodules)

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

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:

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.

2.7 KiB Raw Blame History