# @suaveplan/api-auth-provider - Abstract auth-provider contract for the Suaveplan API plugin system. Defines AuthProviderAdapter, the canonical provider route surface, path-ownership registry, collision detector, the auth.provider CapabilityId, the AUTH_PROVIDER error-code registry, and the provider conformance harness. $2; concrete providers (better-auth, rolled) ship in Stages 6 and 8.

Abstract account-lifecycle contract for the Suaveplan API plugin system
(contracts). This package is OPTIONAL: hosted-IdP deployments
(Clerk, Auth0, Cognito) install only the session resolver from
`@suaveplan/api-auth`; self-hosted deployments install exactly one provider
implementation (`api-auth-better-auth` , `api-auth-rolled` in
Stage 8) which structurally implements `AuthProviderAdapter` from this
package.

<!-- begin:auto-docs -->
## Documentation tree

- [capability-id](./src/capability-id/capability-id.md) — The `capability-id` module pins the runtime literal for the `"auth.provider"` capability this package contributes to th…
  - [capability-id](./src/capability-id/capability-id.md) — The `capability-id` module pins the runtime literal for the `"auth.provider"` capability this package contributes to th…
- [collision-detector](./src/collision-detector/collision-detector.md) — `collision-detector` is the install-time guard that prevents a plugin from accidentally squatting on the auth-provider'…
  - [collision-detector](./src/collision-detector/collision-detector.md) — `collision-detector` is the install-time guard that prevents a plugin from accidentally squatting on the auth-provider'…
- [error-codes](./src/error-codes/error-codes.md) — This module centralises the four stable error codes the auth-provider contract emits — `PATH_COLLISION`, `MULTIPLE_PROV…
  - [error-codes](./src/error-codes/error-codes.md) — This module centralises the four stable error codes the auth-provider contract emits — `PATH_COLLISION`, `MULTIPLE_PROV…
- [path-ownership](./src/path-ownership/path-ownership.md) — `path-ownership` is the runtime registry the host consults to enforce the "exactly one auth provider per deployment" in…
  - [path-ownership](./src/path-ownership/path-ownership.md) — `path-ownership` is the runtime registry the host consults to enforce the "exactly one auth provider per deployment" in…
- [provider](./src/provider/provider.md) — The `provider` module is the type-level + thin-runtime heart of `@suaveplan/api-auth-provider`. It declares the abstrac…
  - [provider](./src/provider/provider.md) — The `provider` module is the type-level + thin-runtime heart of `@suaveplan/api-auth-provider`. It declares the abstrac…
- [route-surface](./src/route-surface/route-surface.md) — `route-surface` declares the closed set of paths an auth provider OWNS relative to its `pathPrefix`. The set is the uni…
  - [route-surface](./src/route-surface/route-surface.md) — `route-surface` declares the closed set of paths an auth provider OWNS relative to its `pathPrefix`. The set is the uni…
- [testing](./src/testing/conformance.md) — `runAuthProviderConformance` is the runner-agnostic harness every concrete `AuthProviderAdapter` MUST clear. It exercis…
  - [conformance](./src/testing/conformance.md) — `runAuthProviderConformance` is the runner-agnostic harness every concrete `AuthProviderAdapter` MUST clear. It exercis…
<!-- end:auto-docs -->

## What ships here

- `AuthProviderAdapter` contract — `id`, `pathPrefix`,
    `routes(router, ctx)`, four-hook lifecycle.
- `AuthPathPrefix` brand + Zod-validated `authPathPrefix` constructor.
- `PROVIDER_ROUTE_SURFACE` — the canonical 9-entry route table providers
    project from.
- `PathOwnership` runtime registry — enforces "exactly one provider"
    install-time invariant.
- `detectAuthPathCollisions` — install-time guard that plugin routes do not
    squat on the provider's owned prefix.
- `AUTH_PROVIDER_CAPABILITY_ID` constant — `"auth.provider"`.
- `AUTH_PROVIDER_CODES` — the four-code error registry plus
    `AuthProviderError` and the `authProviderError` factory.
- `runAuthProviderConformance` — runner-agnostic harness every concrete
    provider clears.

## Module index

- [provider](src/provider/provider.md)
- [route-surface](src/route-surface/route-surface.md)
- [path-ownership](src/path-ownership/path-ownership.md)
- [collision-detector](src/collision-detector/collision-detector.md)
- [capability-id](src/capability-id/capability-id.md)
- [error-codes](src/error-codes/error-codes.md)
- [testing/conformance](src/testing/conformance.md)

## Dependencies

- `@suaveplan/api-types` (workspace) — `AuthProviderAdapter` consumes
    `Router`, `PluginContext`, `CapabilityId`, `CapabilityRequirements`.
- `@suaveplan/error` (workspace) — `SuaveplanError` + `defineCodes`.
- `zod` (catalog) — `AuthPathPrefixSchema`.
- `tslib` (catalog) — emitter helpers.

## Stage / status

Concrete providers ship in Stages 6 / 8.