69 lines
4.9 KiB
Markdown
69 lines
4.9 KiB
Markdown
# @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.
|
|
|