suaveplan/packages/api-stack/api/api-auth-provider/README.md

@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.

Documentation tree

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

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
• route-surface
• path-ownership
• collision-detector
• capability-id
• error-codes
• testing/conformance

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.