feat(extensions): versioned public extension SDK

Promote the internal extension kernel to a stable public authoring SDK:
- public `litestar_auth.extensions` facade as the single author import path
- versioned boundary: EXTENSION_API_VERSION + optional requires_api, fail-closed
- enabled toggle and opt-in entry-point discovery (group "litestar_auth.extensions")
- AuthCliExtension and AuthEventSubscriberExtension contribution surfaces
- self-declaring internal extension descriptors; resolve_extensions memoized

Author: shepilov-vladislav

.github/workflows/1_test.yml

@@ -176,7 +176,7 @@ jobs:
 
       # Codecov flags: ^[\w.\-]{1,45}$ (alphanumeric, _, -, .); see https://docs.codecov.com/docs/flags
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           fail_ci_if_error: true
           files: coverage.xml

.pre-commit-config.yaml

@@ -87,7 +87,8 @@ repos:
         exclude: |
           (?x)^(
             tests/_helpers\.py|
-            tests/integration/_di_probes\.py
+            tests/integration/_di_probes\.py|
+            tests/support/extensions\.py
           )$
       - id: no-commit-to-branch
         args: [--branch, main]

CHANGELOG.md

@@ -1,3 +1,52 @@
+## Unreleased
+
+### Added
+
+- **Public extension SDK (`litestar_auth.extensions`).** The internal extension kernel is now a stable,
+  publicly documented authoring surface. `litestar_auth.extensions` is the only import path an external
+  extension needs — it re-exports the `AuthExtension` contract together with its
+  `AuthExtensionValidationContext` / `AuthExtensionRegistrationContext` typed contexts (all three are now
+  also exported from the root `litestar_auth` package), `EXTENSION_API_VERSION`,
+  `EXTENSION_ENTRY_POINT_GROUP`, and the public controller factories authors need (reaching into
+  `litestar_auth._plugin.*` is unsupported and guarded by an import-isolation regression test). Register
+  extensions explicitly via `LitestarAuthConfig.extensions=(...)`; an extension contributes controllers,
+  dependencies, middleware, OpenAPI security schemes, startup/shutdown hooks, and exception handlers
+  through the typed contexts. An optional `enabled` flag toggles an extension off without removing it from
+  configuration (omitting it is treated as enabled).
+
+- **Versioned extension boundary.** `EXTENSION_API_VERSION` (currently `(1, 0)`) versions the authoring
+  contract independently of the rest of the library. An extension may declare a `requires_api` minimum;
+  an incompatible requirement fails closed with `ConfigurationError` before any application wiring runs.
+
+- **Opt-in entry-point discovery.** New `LitestarAuthConfig.auto_discover_extensions` (default `False`)
+  loads external extensions published under the `litestar_auth.extensions` entry-point group, following
+  the `litestar_auth_ext_*` distribution-naming convention. Discovery is fail-closed: an entry point that
+  cannot load, cannot instantiate, or does not produce a valid `AuthExtension` raises `ConfigurationError`.
+
+- **CLI and manager-event contribution surfaces.** New optional `AuthCliExtension` lets an extension
+  contribute CLI commands; `on_cli_init` now routes through it (the built-in organization administration
+  CLI is its first internal consumer). New optional `AuthEventSubscriberExtension` lets an extension
+  observe manager lifecycle events through **redacted** payloads — token-bearing values and credential
+  fields (passwords, hashed passwords, invitation tokens, and similar) are stripped before delivery.
+
+- **`RoleAdminExtension` first-party extension.** The contrib role-administration controller is now also
+  available as a public `RoleAdminExtension` (import from `litestar_auth.contrib.role_admin`) for explicit
+  `extensions=(...)` registration — the canonical example of the user-facing authoring API. A runnable
+  reference is bundled at `examples/demo_external_extension/`.
+
+### Changed
+
+- **Built-in optional features now wire through the extension pipeline.** OAuth, TOTP, user-owned API
+  keys, and organization administration/invitations are auto-materialized into the same extension pipeline
+  from their existing configuration flags. Behavior for existing configurations is unchanged. As part of
+  this, `LitestarAuthConfig.resolve_extensions()` is memoized, so extension-relevant configuration must be
+  set before the plugin first resolves extensions during application init.
+
+- **Extension OpenAPI security scheme names must be globally unique and fail closed on collision.**
+  Extension-contributed OpenAPI security scheme names may not collide with each other or with core auth
+  scheme names (bearer/cookie backend names, `apiKeyAuth`, and `apiKeyHmacAuth` for signed API keys). A
+  collision raises `ConfigurationError` during application initialization, before the app is usable.
+
 ## 4.2.0 (2026-06-05)
 
 ### Added

docs/api/package.md

@@ -85,9 +85,16 @@ Treat the startup templates as plugin-assembly inventory only: they preserve bac
 Relational role storage changes persistence only. Public HTTP payloads, managers, and guard
 factories still use one normalized flat `roles` collection. The core plugin-owned auth/users route
 table does not auto-mount role catalog or user-assignment endpoints; use the opt-in
-`litestar_auth.contrib.role_admin` controller or the `litestar roles` CLI for admin operations.
+`litestar_auth.contrib.role_admin.RoleAdminExtension`, the manual contrib controller
+factory, or the `litestar roles` CLI for admin operations.
 The library does not ship permission matrices.
 
+Organization administration is also available through the extension kernel. Use
+`litestar_auth.contrib.organization_admin.OrganizationAdminExtension` for plugin-managed
+organization-admin HTTP routes, or keep using the public manual factories for custom route tables.
+The extension requires `OrganizationConfig(enabled=True, store_factory=...)` and an `id_parser`, and
+its invitee-facing accept/decline routes are mounted only with `include_invitations=True`.
+
 ## Public surface (high level)
 
 | Area | Types / functions |
@@ -101,7 +108,8 @@ The library does not ship permission matrices.
 | Errors | `ErrorCode`, `LitestarAuthError`; typed subclasses from `litestar_auth.exceptions` |
 | Protocols | `UserProtocol`, `GuardedUserProtocol`, `RoleCapableUserProtocol`, `TotpUserProtocol` — [Types](types.md) |
 | Controllers (advanced) | `create_*_controller` factories from `litestar_auth.controllers` — [Controllers API](controllers.md) |
-| Contrib role admin | `create_role_admin_controller` from `litestar_auth.contrib.role_admin` — [HTTP role administration](../guides/role_admin_http.md) |
+| Contrib role admin | `RoleAdminExtension`, `RoleAdminControllerConfig`, `create_role_admin_controller` from `litestar_auth.contrib.role_admin` — [HTTP role administration](../guides/role_admin_http.md) |
+| Contrib organization admin | `OrganizationAdminExtension`, `OrganizationAdminControllerConfig`, `OrganizationInvitationControllerConfig`, `create_organization_admin_controller`, `create_organization_invitation_controller` from `litestar_auth.contrib.organization_admin` — [Organizations](../configuration/organizations.md#administration) |
 | OAuth helpers | Plugin-managed route table via `OAuthConfig`; manual login helper and lazy client loader from `litestar_auth.oauth` |
 | TOTP | `generate_totp_secret`, `generate_totp_uri`, `verify_totp`, stores from `litestar_auth.totp` |
 | Rate limit | `AuthRateLimitConfig`, `EndpointRateLimit`, `InMemoryRateLimiter`, `RedisRateLimiter` from `litestar_auth.ratelimit` |

docs/configuration.md

@@ -24,6 +24,7 @@ from litestar_auth.models import User  # or your own model
 | `TotpConfig` fields, TOTP route behavior, and TOTP step-up policy | [TOTP](configuration/totp.md) |
 | `OAuthConfig`, provider inventory, redirect policy, and token encryption | [OAuth](configuration/oauth.md) |
 | `OrganizationConfig`, organization model imports, and organization store wiring | [Organizations](configuration/organizations.md) |
+| `extensions` config field, Step-1 `AuthExtension` contract, and extension context interfaces | [Extensions](configuration/extensions.md) |
 | CSRF, legacy-token policy, dependency keys, and shared helpers | [Security and DI](configuration/security.md) |
 | Operator-side proxy, cookie, and secrets-at-rest preconditions | [Deployment security contract](deployment.md#deployment-security-contract) |
 

docs/configuration/api_keys.md

@@ -2,7 +2,8 @@
 
 API-key authentication is opt-in. Set `LitestarAuthConfig.api_keys` with `ApiKeyConfig(enabled=True, ...)` to add the
 API-key backend, self-service routes under `/api-keys`, admin routes under `/users/{user_id}/api-keys`, and the
-`apiKeyAuth` OpenAPI security scheme.
+`apiKeyAuth` OpenAPI security scheme. The plugin mounts the management routes through an internal extension derived from
+`api_keys.enabled`; the API-key authentication backend remains configured by the normal backend registry.
 
 ```python
 from datetime import timedelta
@@ -69,6 +70,10 @@ Admin routes are guarded by `is_superuser` and use the path user id as authority
 `DELETE /users/{user_id}/api-keys/{key_id}`. Request bodies never choose the target user, and admin
 create requests do not require the target user's `current_password`.
 
+For advanced manual routing, `create_api_keys_controllers(...)` and `ApiKeysControllerConfig(...)` remain public. That
+factory builds the same self-service and admin controller classes used by the plugin-managed extension; leave
+`api_keys.enabled=False` when mounting those controllers yourself to avoid duplicate routes.
+
 When TOTP is enrolled, API-key create/update/revoke routes use the `api_keys.*` entries in
 `LitestarAuthConfig.totp_stepup_policy` and default to `required_when_enrolled`. `POST` and `PATCH`
 bodies accept `totp_code` as an inline proof; otherwise callers need a recent TOTP marker from the