# `error-codes` — `AUTH_CODES` registry

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

## Purpose

Defines the stable, namespaced error-code registry for the `@suaveplan/api-auth`
package and the concrete `AuthError` class. Every code is reachable from a
production throw site somewhere in the package (chain construction, chain
execution, adapter registration, or principal-shape validation). The registry
is frozen via `defineCodes("AUTH", […])` so accidental drift between thrown
codes and the documented set is impossible.

Consumers — including downstream concrete resolvers in Stages 4/6/8 such as
`api-auth-jwt`, `api-auth-anonymous`, and `api-auth-bearer-static` — branch on
the string literal (`"AUTH.RESOLVER_THREW"` etc.) or compare to the constant
(`AUTH_CODES.RESOLVER_THREW`). The literal form is preferred at the API
boundary; the constant is preferred inside the package itself so the linter
flags typos as type errors.

## Features

- Frozen string-literal union of all four codes.
- `AuthError` extends `SuaveplanError<AuthErrorCode>` so `instanceof AuthError`
  narrows `code` correctly.
- Cause-chain propagation: the optional `options.cause` field is forwarded to
  the base class.
- Public constructor (the base class is `protected`).

## Usage: Basic

```ts
import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";

if (chain.length === 0) {
    throw new AuthError(AUTH_CODES.CHAIN_EMPTY, "at least one resolver required");
}
```

## Usage: Advanced

Re-throw a resolver error with a cause chain and inspect it downstream:

```ts
import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";

try {
    await resolver.resolve(req);
} catch (cause) {
    throw new AuthError(AUTH_CODES.RESOLVER_THREW, "resolver A threw", {
        cause,
        context: { resolverIndex: 0 },
    });
}
```

```ts
import { AuthError } from "@suaveplan/api-auth/error-codes";

if (err instanceof AuthError && err.code === "AUTH.RESOLVER_THREW") {
    logger.warn("upstream session resolver failed", { cause: err.cause });
}
```

## API Reference

| Symbol         | Kind   | Description                                                     |
|----------------|--------|-----------------------------------------------------------------|
| `AUTH_CODES`   | const  | Frozen lookup `{ RESOLVER_THREW, CHAIN_EMPTY, … }`.             |
| `AuthErrorCode`| type   | Literal union of the four code strings.                          |
| `AuthError`    | class  | Concrete `SuaveplanError` subclass narrowed to `AuthErrorCode`. |

## Implementation Notes

- `defineCodes("AUTH", [...] as const)` produces an object literal with
  string-literal value types, which is what gives `AuthErrorCode` its narrow
  union. Removing `as const` would widen the type to `string`.
- The class field `authCode` mirrors `code` for ergonomic narrowing on
  pre-instantiated error objects (some test runners obscure the inherited
  `code` field via Proxy wrappers).
- Code values follow the `AUTH.<UPPER_SNAKE>` template enforced by
  `@suaveplan/api-types`' `ErrorCode` template literal type.