diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..d7d6684
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git commit -m ' *)",
+      "Bash(go work *)",
+      "Bash(make build *)",
+      "Bash(make test *)",
+      "Bash(make lint *)",
+      "Bash(git add *)",
+      "Bash(git rm *)",
+      "Bash(git mv *)",
+      "Bash(sed *)",
+      "Bash(awk *)",
+      "Read(//Users/euskadi31/Projects/Github/hyperscale-stack/**)"
+    ]
+  }
+}
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index 89b550b..610b222 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -8,35 +8,43 @@ on:
 
 jobs:
   build:
-    name: Build
+    name: Build & test (workspace)
     runs-on: ubuntu-latest
     steps:
-      - name: Check out code into the Go module directory
+      - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up Go 1.x
+      - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.x"
-          check-latest: true
+          go-version-file: go.work
         id: go
 
-      - name: Build
-        run: make build
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.12.2
+          install-only: true
 
-      - name: Generate
-        run: make generate
+      - name: Workspace sync
+        run: make sync
 
-      - name: Test
+      # NOTE: `make generate` is intentionally NOT run in CI yet — the
+      # .mockery.yaml is being migrated to v3 syntax while the tool pin
+      # (vektra/mockery v2.53.5) is still v2. Re-enable once the config /
+      # tool are aligned (tracked in LIMITATIONS.md, slated for Phase 4).
+      - name: Build all modules
+        run: make build
+
+      - name: Test all modules (race + coverage)
         run: make test
 
-      - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v9
-        with:
-          version: latest
-          skip-cache: true
+      # Lint runs in a dedicated step so that gosec/golangci output is easy to
+      # read. The Makefile iterates over every module with the shared config.
+      - name: Lint all modules
+        run: make lint
 
-      - name: Coveralls
+      - name: Upload aggregated coverage to Coveralls
         uses: shogo82148/actions-goveralls@v1
         with:
           path-to-profile: build/coverage.out
@@ -45,7 +53,7 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - name: Coveralls Finished
+      - name: Coveralls finished
         uses: coverallsapp/github-action@master
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..9cee314
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,64 @@
+name: Release
+
+# Each module of the workspace is released independently. Go's multi-module
+# convention puts the module path in the tag:
+#
+#   v1.2.3            -> the root module (github.com/hyperscale-stack/security)
+#   http/v1.2.3       -> the github.com/hyperscale-stack/security/http module
+#   oauth2/v1.2.3     -> the github.com/hyperscale-stack/security/oauth2 module
+#
+# Pushing such a tag validates the tagged state and publishes a GitHub
+# release. Nothing is force-pushed and no tag is created by this workflow.
+on:
+  push:
+    tags:
+      - "v*"
+      - "*/v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release ${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.x"
+          check-latest: true
+
+      - name: Resolve the released module
+        id: mod
+        run: |
+          tag='${{ github.ref_name }}'
+          case "$tag" in
+            */v*) echo "dir=${tag%/v*}" >> "$GITHUB_OUTPUT" ;;
+            *)    echo "dir=." >> "$GITHUB_OUTPUT" ;;
+          esac
+
+      - name: Workspace sync
+        run: make sync
+
+      # The whole workspace is built and tested so a tag can never publish a
+      # module whose dependencies (sibling modules) are in a broken state.
+      - name: Build all modules
+        run: make build
+
+      - name: Test all modules (race + coverage)
+        run: make test
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          body: |
+            Release of the `${{ steps.mod.outputs.dir }}` module.
+
+            See [CHANGELOG.md](https://github.com/hyperscale-stack/security/blob/master/CHANGELOG.md)
+            for the consolidated history.
diff --git a/.golangci.yml b/.golangci.yml
index 8596999..5299ccc 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -3,6 +3,11 @@ formatters:
     - gofmt
   exclusions:
     paths:
+      - .github/.*
+      - .claude/.*
+      - .vscode/.*
+      - build/.*
+      - docs/.*
       - .*_mock\.go
       - mock_.*\.go
       - .*/pkg/mod/.*$
diff --git a/.mockery.yaml b/.mockery.yaml
index 118814d..97a955a 100644
--- a/.mockery.yaml
+++ b/.mockery.yaml
@@ -1,15 +1,13 @@
-inpackage: True
-with-expecter: True
-all: True
+all: true
 dir: '{{.InterfaceDir}}'
-mockname: 'Mock{{.InterfaceName}}'
-outpkg: '{{.PackageName}}'
-filename: 'mock_{{ .InterfaceName | snakecase }}.go'
+filename: 'mock_{{.InterfaceName | snakecase}}.go'
+structname: Mock{{.InterfaceName}}
+pkgname: '{{.SrcPackageName}}'
+inpackage: true
+template: testify
+template-data:
+  unroll-variadic: true
 packages:
   github.com/hyperscale-stack/security:
     config:
-      recursive: True
-
-issue-845-fix: True
-resolve-type-alias: False
-disable-version-string: True
+      recursive: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..4ee446a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The library is a multi-module workspace; modules are tagged independently
+(`module/vX.Y.Z`). The entries below describe the ground-up rewrite that
+replaced the v0 stack.
+
+## [Unreleased]
+
+The whole `v0.x` series is superseded by a transport-agnostic rewrite. The
+legacy packages (`authentication/`, `authorization/`, the in-tree
+`password` package, `authentication/provider/oauth2`) were removed.
+
+### Added
+
+- **Transport-agnostic core** (`github.com/hyperscale-stack/security`):
+  immutable `Authentication`/`Principal`, `Carrier`, `Extractor`,
+  `Authenticator`, first-success-wins `Manager`, `Engine`, typed
+  `SecurityError` sentinels, and a `Clock` abstraction.
+- **Authorization v2**: `Voter`/`Decision`/`Attribute`, an
+  `AccessDecisionManager` with Affirmative/Consensus/Unanimous strategies,
+  and a `voter/` catalog (`HasRole`, `HasAnyRole`, `HasScope`,
+  `HasAuthority`, `HasPermission`, `Authenticated`, `Anonymous`,
+  `FullyAuthenticated`, `And`/`Or`/`Not`).
+- **HTTP adapter** (`httpsec`): `Middleware`, `Authorize`, a request/response
+  `Carrier`, and a configurable `ErrorMapper`.
+- **gRPC adapter** (`grpcsec`): unary and stream server interceptors,
+  `UnaryAuthorize`/`StreamAuthorize`, a `metadata.MD` carrier, and an
+  `ErrorMapper` to `codes.Code`.
+- **Schemes**: `basic` (HTTP Basic extractor + authenticator) and `bearer`
+  (Bearer extractor + pluggable `TokenVerifier`).
+- **Password hashing** (`password`): `Hasher` interface with bcrypt and
+  Argon2id implementations, context support, and `NeedsRehash`.
+- **JWT** (`jwtsec`): `Signer`/`Verifier`, static and cached-remote JWKS,
+  key rotation, `alg=none` and algorithm-confusion defenses, and a
+  `bearer.TokenVerifier` adapter.
+- **OAuth2 server** (`oauth2`): `Profile` (2.0 / 2.0-BCP / 2.1-draft),
+  enforced at runtime on the grants (PKCE required, `plain` PKCE refused
+  under BCP / 2.1). Grants: `authorization_code` (PKCE), `client_credentials`,
+  `refresh_token` (rotation + reuse detection), and the opt-in legacy
+  `password` grant (`grant.NewLegacyPassword`, refused outside `Profile20`).
+  `client_secret_basic`/`_post`/`none` client authentication. Endpoints:
+  `/authorize` (authorization_code + opt-in legacy implicit flow, with an
+  application-supplied consent hook), `/token`, `/revoke`, `/introspect`,
+  and metadata — the metadata endpoint paths are configurable through
+  `ServerConfig.RoutePrefix`. A `Storage` interface with explicit atomicity
+  contracts.
+- **OAuth2 storage backends**: in-memory (`oauth2/storage/memory`), SQL
+  (`oauth2/store/sql`, Postgres/MySQL/SQLite), and Redis
+  (`oauth2/store/redis`, Lua-script atomicity), all validated by the shared
+  `oauth2/storetest` conformance suite.
+- **Sessions** (`session`): stateless AES-256-GCM encrypted cookies with key
+  rotation, a `Manager` (Login/Get/Touch/Rotate/Logout), and a
+  synchronizer-token CSRF helper.
+- **Observability**: OpenTelemetry spans emitted directly by the core,
+  `httpsec`, `grpcsec`, `jwtsec`, and `session`. See
+  [docs/observability.md](docs/observability.md).
+- **Documentation**: `docs/architecture.md`, `docs/observability.md`,
+  `docs/security-considerations.md`, `docs/migration-from-v0.md`, and a
+  refreshed `README.md`.
+
+### Changed
+
+- The repository is now a Go workspace (`go.work`) of independent modules,
+  so consumers import only the pieces they need and the core stays free of
+  heavy transitive dependencies.
+- `Authentication` is immutable — authenticators return new values instead
+  of mutating their input.
+- `context.Context` is the first argument of every runtime operation
+  (`Extract`, `Authenticate`, `Hasher.Hash`/`Verify`, `TokenVerifier.Verify`).
+- Password `Verify` returns `(bool, error)`, distinguishing a mismatch from
+  a malformed hash; v0 returned a bare `bool`.
+- The JWT verifier (`jwtsec`) now rejects tokens without an `exp` claim by
+  default (`ErrMissingExpiry`), aligning with RFC 9068 §2.2 and the
+  fail-closed doctrine. Opt out with `jwtsec.WithOptionalExpiry()` to verify
+  deliberately non-expiring assertions.
+
+### Fixed
+
+- The v0 authentication `Handler` no longer iterates past a successful
+  authentication and no longer swallows provider errors — the `Manager`
+  short-circuits on first success and aggregates failures.
+- The OAuth2 client-secret mismatch is now a typed error
+  (`ErrClientSecretMismatch`) instead of a silent failure.
+
+### Removed
+
+- The legacy v0 packages: `authentication/`, `authentication/credential/`,
+  `authentication/provider/{dao,oauth2}/`, `authorization/`, and the
+  in-tree `password` package.
+
+### Security
+
+- The HTTP `DefaultErrorMapper` no longer reflects the wrapped error chain
+  into the `WWW-Authenticate` header. The RFC 6750 `error_description` is now
+  a fixed, generic string per error code, so internal context (timestamps,
+  package and authenticator names, consumer-supplied `TokenVerifier`/store
+  errors) can no longer leak to clients.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..63b525d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,205 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`github.com/hyperscale-stack/security` is a transport-agnostic authentication
+and authorization framework for Go — conceptually Spring Security / Symfony
+Security for the Go ecosystem. It is a **Go workspace (`go.work`) split into
+several independently-releasable modules**, so consumers import only the
+pieces they need and the core stays free of heavy transitive dependencies.
+
+The whole `v0.x` series was replaced by a ground-up transport-agnostic
+rewrite (the "v2 stack"); the legacy `authentication/` / `authorization/`
+packages were removed. The rewrite is functionally complete and currently
+`[Unreleased]` — remaining gaps are tracked as GitHub issues, not refactor
+phases. Source-of-truth docs:
+
+- `CHANGELOG.md` — what the v2 stack ships.
+- `MIGRATION.md` — workspace layout and dependency policy.
+- `LIMITATIONS.md` — known gaps and explicitly out-of-scope items.
+- `docs/` — `architecture.md`, `observability.md`,
+  `security-considerations.md`, `migration-from-v0.md`.
+
+## Working rules
+
+These rules are mandatory when working in this repository:
+
+- **Clean code:** write clean, SOLID, testable code. **No overengineering** —
+  build for the current requirement, not a hypothetical one.
+- **Language:** all code, commit messages, and documentation are in **English**.
+  Talk to the user (Axel) in **French**.
+- **Tests are mandatory:** always write tests. Target **100% coverage** where
+  practical, **never below 80%**.
+- **RFC compliance:** anything based on an RFC (OAuth2, JWT, PKCE, ...) MUST
+  follow the RFC to the letter.
+- **Security:** write secure code with no known vulnerabilities. `gosec` is
+  part of the lint gate — keep it clean.
+- **Per-step gate:** at the end of every feature/step, **run the tests and the
+  linter** (`make test` + `make lint`, or the per-module equivalent). They
+  MUST pass.
+- **Commit per step:** once tests and lint pass, **commit** the step before
+  moving on. Use Conventional Commits with a module scope, as in the git
+  history (`feat(oauth2): ...`, `fix(jwt): ...`, `docs(...): ...`).
+- **Godoc:** document every public API with godoc. Keep it concise and
+  relevant so a developer can pick up the module quickly.
+
+## Commands
+
+All targets operate on **every module in the workspace** (discovered via
+`find . -name go.mod`). Run from the repo root:
+
+```sh
+make build      # go build ./... in every module
+make test       # go test -race -cover in every module, aggregated -> build/coverage.out
+make lint       # golangci-lint (shared .golangci.yml) on every module
+make tidy       # go mod tidy per module + go work sync
+make sync       # go work sync
+make bench      # benchmarks across all modules
+make coverage   # go tool cover -func on the aggregated profile
+make generate   # mockery — currently BROKEN, see "Tooling caveats" below
+```
+
+To run a **single test** or work on one module, `cd` into that module first
+(each module is its own `go.mod` with `replace` directives back to the core):
+
+```sh
+cd oauth2 && go test -race -run TestServer_Token ./...
+cd jwt    && go test ./...
+```
+
+`make test` aggregates coverage but **excludes example `main()` programs**
+(they bind a socket and block); examples are still built, tested, and linted.
+
+CI: `.github/workflows/go.yml` runs `make sync build test lint` against the
+whole workspace in one job. `.github/workflows/release.yml` validates the
+workspace and cuts a GitHub release on a `module/vX.Y.Z` tag. `make generate`
+is intentionally skipped in CI.
+
+## Module layout & dependency policy
+
+| Path                      | Import / pkg name                          | Purpose                                              |
+| ------------------------- | ------------------------------------------ | ---------------------------------------------------- |
+| `.`                       | `security`                                 | Core transport-agnostic primitives                   |
+| `./http`                  | `.../http` → `httpsec`                     | `net/http` adapter (middleware, `Authorize`, carrier) |
+| `./grpc`                  | `.../grpc` → `grpcsec`                      | gRPC unary/stream interceptors + `Authorize`         |
+| `./basic`                 | `.../basic`                                | HTTP Basic extractor + authenticator                 |
+| `./bearer`                | `.../bearer`                               | Bearer extractor + `TokenVerifier` authenticator     |
+| `./password`              | `.../password`                             | BCrypt + Argon2id hashers (`NeedsRehash`)            |
+| `./jwt`                   | `.../jwt` → `jwtsec`                        | JWT signer/verifier + JWKS + key rotation            |
+| `./session`               | `.../session`                              | Stateless AES-256-GCM cookie sessions + CSRF         |
+| `./oauth2`                | `.../oauth2`                               | OAuth2 authorization server                          |
+| `./oauth2/storage/memory` | `.../oauth2/storage/memory`                | In-memory `oauth2.Storage` — **package of `oauth2`** |
+| `./oauth2/store/sql`      | `.../oauth2/store/sql`                      | Production storage on `database/sql` (PG/MySQL/SQLite) |
+| `./oauth2/store/redis`    | `.../oauth2/store/redis`                    | Production storage on Redis (Lua atomicity)          |
+| `./examples`              | `.../examples`                             | Runnable demos: basic-http, bearer-jwt, grpc-bearer, session-web, oauth2 |
+| `./internal/integrations` | (private)                                  | Cross-module end-to-end tests                        |
+
+`oauth2/storage/memory` is **not** a standalone module — it is a sub-package
+of `oauth2`. The other rows are independent modules (own `go.mod`).
+
+**The dependency direction is a hard rule** (enforced by review, see
+`MIGRATION.md`): the **core (`.`) must depend only on stdlib +
+`go.opentelemetry.io/otel`** (+ `testify` in its own tests). It MUST NOT
+import gRPC, JOSE/JWT libs, OAuth2, Redis, SQL drivers, HTTP routers, or
+concrete loggers. Adapters depend on the core, never the reverse. The
+`oauth2` module has **no hard dependency on `jwt`** — JWT access tokens are
+wired via an adapter (`jwt` depends on `oauth2`, not the other way). When
+adding code, check the allowed-dependency list in `MIGRATION.md` before
+adding an import.
+
+Every sub-module declares `replace github.com/hyperscale-stack/security => ../`
+(`=> ../../../` for the SQL/Redis stores) so local dev works without
+published versions.
+
+## Core architecture
+
+A request flows through this pipeline (all of it transport-agnostic — HTTP
+and gRPC are just adapters):
+
+```
+Carrier ──> Extractor ──> Authentication ──> Manager/Authenticator ──> Engine
+                                                                         │
+                                          AccessDecisionManager/Voter <──┘
+```
+
+- **`Carrier`** — abstracts a transport message (HTTP request, gRPC metadata)
+  with `http.Header`-like Get/Set/Add/Values. Adapters wrap it.
+- **`Extractor`** — pulls raw credentials from a `Carrier` into an
+  *unauthenticated* `Authentication`. Returns `(nil, nil)` when its scheme is
+  absent (engine tries the next); `(nil, err)` when present-but-malformed.
+- **`Authentication`** — **immutable snapshot** of a security context
+  (Principal, Credentials, Authorities, IsAuthenticated, Name). Every state
+  change produces a *new value*; implementations MUST NOT be mutated. Safe
+  for concurrent reads with no synchronization.
+- **`Authenticator`** — two-step: `Supports()` (cheap type switch, no I/O)
+  then `Authenticate()` returns a *new* authenticated value or a wrapped
+  sentinel error.
+- **`Manager`** — chains authenticators, **first-success-wins** in
+  registration order; joins errors; returns `ErrUnsupportedCredential` when
+  none support the credential.
+- **`Engine`** — top-level entry point: runs extractors, hands the result to
+  the Manager, returns a context enriched via `WithAuthentication`.
+- **Authorization** — `Voter` returns `Decision` (Grant/Deny/Abstain) over a
+  set of `Attribute`s; `AccessDecisionManager` combines votes with an
+  `affirmative` / `consensus` / `unanimous` strategy (mirrors Spring
+  Security). Stock voters live in `voter/` (`HasRole`, `HasAnyRole`,
+  `HasScope`, `HasAuthority`, `HasPermission`, `Authenticated`, `Anonymous`,
+  `FullyAuthenticated`); compose them with `And`/`Or`/`Not`.
+
+Conventions baked into the core:
+- **Fail closed by default.** No credentials → `Anonymous()`; voters deny
+  unless one explicitly grants. The HTTP middleware rejects with 401 unless
+  `WithAnonymousFallback` is set.
+- **Errors are sentinels** (`errors.go`) implementing the unexported
+  `SecurityError` marker. Always wrap with `fmt.Errorf("...: %w", ErrXxx)`;
+  callers match with `errors.Is`/`errors.As`, never string matching.
+- **Context first.** `context.Context` is the first argument of every
+  runtime operation (`Extract`, `Authenticate`, `Hasher.Hash`/`Verify`,
+  `TokenVerifier.Verify`). It also carries the `Authentication` under an
+  unexported key — `WithAuthentication` / `FromContext` (returns
+  `Anonymous()` when absent).
+- **OTel spans live directly in each module** — there is intentionally no
+  `EventSink` abstraction and no separate `otel/` module. The core uses
+  scope `github.com/hyperscale-stack/security`; each instrumented module
+  (`httpsec`, `grpcsec`, `jwtsec`, `session`) uses its own. See
+  `docs/observability.md` for the span catalog.
+
+## OAuth2 server (`oauth2/`)
+
+`oauth2.NewServer(ServerConfig{...})` aggregates `Profile`, `Storage`,
+`ClientStore`, `IssuerResolver`, `Grants`, and `ClientAuth`, and exposes one
+`http.Handler` per RFC endpoint: `AuthorizeHandler`, `TokenHandler`,
+`RevokeHandler`, `IntrospectHandler`, `MetadataHandler` (endpoint paths
+configurable via `ServerConfig.RoutePrefix`).
+
+- `Profile` (2.0 / 2.0-BCP / 2.1-draft) is enforced at runtime on the grants
+  — PKCE required and `plain` PKCE refused under BCP/2.1; legacy `password`
+  and `implicit` flows refused outside `Profile20`.
+- Sub-packages: `grant/` (`authorization_code`, `client_credentials`,
+  `refresh_token` with rotation + reuse detection, opt-in legacy `password`),
+  `clientauth/` (`client_secret_basic` / `_post` / `none`), `token/` (opaque +
+  JWT generators), `pkce/`.
+- Access/refresh tokens and authz codes are stored **hashed** (`HashToken`).
+- `Storage` implementations: `oauth2/storage/memory` (dev/tests),
+  `oauth2/store/sql`, `oauth2/store/redis`. Every implementation must pass
+  the shared `oauth2/storetest` conformance suite.
+
+`examples/oauth2/main.go` is the canonical wiring example for the v2 stack;
+`examples/` also has `basic-http`, `bearer-jwt`, `grpc-bearer`, and
+`session-web` demos.
+
+## Tooling caveats
+
+- **`make generate` is broken**: `.mockery.yaml` uses mockery v3 syntax but
+  `go.mod` pins the v2 tool (`vektra/mockery v2.53.5`). No module depends on
+  generated mocks — **all tests use hand-written fakes**. Don't rely on
+  `make generate`; write a fake.
+- **Lint**: `golangci-lint v2`, `default: none` + ~30 explicitly-enabled
+  linters including `gosec`, `wrapcheck`, `errorlint`, `wsl_v5`,
+  `forcetypeassert`. `gocyclo` max complexity 18. Tests are excluded from
+  lint (`run.tests: false`). All wrapped errors must keep `%w`.
+- Go 1.26. Indentation: tabs in `.go` and `Makefile`, 4 spaces elsewhere,
+  2 spaces in YAML (see `.editorconfig`). All source files carry the MIT
+  copyright header.
diff --git a/LIMITATIONS.md b/LIMITATIONS.md
new file mode 100644
index 0000000..750c223
--- /dev/null
+++ b/LIMITATIONS.md
@@ -0,0 +1,44 @@
+# Known limitations
+
+The v2 stack covers HTTP and gRPC transports, HTTP Basic / Bearer schemes,
+password hashing, JWT, OAuth2 (issuer + resource server), production
+storage backends, and stateless cookie sessions. This document tracks what
+is **not** yet covered. Remaining items are tracked as GitHub issues rather
+than future refactor phases.
+
+## OAuth2 server
+
+- **`private_key_jwt` client authentication (RFC 7523)** — not implemented.
+  `client_secret_basic`, `client_secret_post`, and `none` are.
+- **`/.well-known/jwks.json` endpoint** — not exposed. JWKS publication
+  depends on a server-side public-key store; the `jwtsec` module already
+  provides the building blocks (`NewStaticJWKS`).
+
+## Transports
+
+- Only `net/http` and gRPC adapters are shipped. Other transports can be
+  added downstream by implementing `security.Carrier`.
+
+## Sessions
+
+- The session module is stateless: the whole session lives in an encrypted
+  cookie, there is no server-side session store. This covers the common
+  case without server state, but a session cannot be revoked server-side
+  before its cookie expires. A server-side store (Redis/SQL) is not shipped.
+
+## Tooling
+
+- `.mockery.yaml` targets mockery v3 syntax while the tool pinned in the
+  module is still v2. `make generate` therefore fails until the config and
+  the tool pin are reconciled; CI skips `make generate`. No module relies on
+  generated mocks — every test uses hand-written fakes — so this is not on
+  the critical path.
+
+## Not planned
+
+- **`HTTPDigestFilter` (RFC 7616)** — Digest auth is effectively dead; it
+  will not be implemented unless a concrete need surfaces.
+- **LDAP / API-key authenticators** — easy to add downstream as
+  `security.Authenticator` implementations; not shipped in the core library.
+- **DPoP (RFC 9449)** and **JWE** — out of scope for the initial release;
+  candidates for a later minor version.
diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..ad696a6
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,89 @@
+# Migration & workspace layout
+
+The repository hosts **one** Go workspace (`go.work`) and **several** Go modules.
+This layout lets consumers import only the pieces they need, keeps the core
+free of heavy transitive dependencies, and lets each module be tagged and
+released on its own cadence.
+
+## Modules
+
+| Path                      | Module                                                          | Purpose                                                              |
+| ------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `.`                       | `github.com/hyperscale-stack/security`                          | Core: transport-agnostic primitives (Authentication, Engine, Voter…) |
+| `./http`                  | `github.com/hyperscale-stack/security/http`                     | `httpsec` — `net/http` adapter                                       |
+| `./grpc`                  | `github.com/hyperscale-stack/security/grpc`                     | `grpcsec` — gRPC unary/stream interceptors                           |
+| `./basic`                 | `github.com/hyperscale-stack/security/basic`                    | HTTP Basic extractor + authenticator                                 |
+| `./bearer`                | `github.com/hyperscale-stack/security/bearer`                   | Bearer extractor + `TokenVerifier`-based authenticator               |
+| `./password`              | `github.com/hyperscale-stack/security/password`                 | BCrypt + Argon2id hashers                                            |
+| `./jwt`                   | `github.com/hyperscale-stack/security/jwt`                      | `jwtsec` — JWT signer/verifier + JWKS                                |
+| `./session`               | `github.com/hyperscale-stack/security/session`                  | Stateless encrypted cookie sessions + CSRF                           |
+| `./oauth2`                | `github.com/hyperscale-stack/security/oauth2`                   | OAuth2 server (profiles, grants, endpoints)                          |
+| `./oauth2/store/sql`      | `github.com/hyperscale-stack/security/oauth2/store/sql`         | Production storage on `database/sql`                                 |
+| `./oauth2/store/redis`    | `github.com/hyperscale-stack/security/oauth2/store/redis`       | Production storage on Redis (Lua atomicity)                          |
+| `./examples`              | `github.com/hyperscale-stack/security/examples`                 | Runnable use-case demos (one sub-package per scenario)               |
+| `./internal/integrations` | `github.com/hyperscale-stack/security/internal/integrations`    | Cross-module end-to-end tests (private)                              |
+
+`oauth2/storage/memory` is a sub-package of the `oauth2` module (not a
+standalone module): it ships the in-memory `oauth2.Storage` used for dev
+and tests.
+
+The legacy v0 packages (`authentication/`, `authentication/credential/`,
+`authentication/provider/{dao,oauth2}/`, `authorization/`, and the old
+in-tree `password`) were removed during the rewrite. The core module now
+depends only on stdlib + `go.opentelemetry.io/otel` (+ `testify` for its
+own tests).
+
+## Dependency policy
+
+```
+core (.)                ← stdlib + go.opentelemetry.io/otel
+http/                   ← core + otel
+grpc/                   ← core + otel + google.golang.org/grpc
+basic/                  ← core + password
+bearer/                 ← core
+password/               ← golang.org/x/crypto
+jwt/                    ← core + bearer + oauth2 + go-jose/v4 + otel
+session/                ← core + golang.org/x/crypto + otel
+oauth2/                 ← core + stdlib
+oauth2/store/sql/       ← oauth2 + database/sql
+oauth2/store/redis/     ← oauth2 + github.com/redis/go-redis/v9
+examples/               ← may depend on every module above
+
+(`oauth2/storage/memory` is a sub-package of the `oauth2` module.)
+```
+
+The core MUST NOT depend on: gRPC, JWT/JOSE libs, OAuth2, Redis, SQL drivers,
+HTTP routers, or concrete loggers. Its direct dependency set is exactly
+stdlib + `go.opentelemetry.io/otel` (+ `stretchr/testify` scoped to its own
+tests). The policy is enforced by review.
+
+## Local development
+
+```sh
+make sync         # go work sync
+make build        # build all modules
+make test         # race + coverage, aggregated into build/coverage.out
+make lint         # golangci-lint on every module with the shared config
+make tidy         # go mod tidy on every module + go work sync
+```
+
+The `Makefile` discovers modules dynamically via `find . -name go.mod`, so a
+new sub-module is picked up automatically as soon as its `go.mod` lands.
+Example program lines are excluded from the aggregated coverage profile
+(their `main()` is not unit-testable); the examples are still built, tested,
+and linted.
+
+## CI
+
+`.github/workflows/go.yml` runs `make sync`, `make build`, `make test`, and
+`make lint` against every module in one job, then publishes the aggregated
+coverage to Coveralls. `.github/workflows/release.yml` validates the whole
+workspace and publishes a GitHub release when a `module/vX.Y.Z` tag is
+pushed.
+
+## Replace directives
+
+Every sub-module declares `replace github.com/hyperscale-stack/security => ../`
+(or `=> ../../` for the SQL/Redis sub-modules) so local development and CI
+work without published versions. Releases are cut per module with
+`module/vX.Y.Z` tags.
diff --git a/Makefile b/Makefile
index 3884b3c..65e4ac4 100644
--- a/Makefile
+++ b/Makefile
@@ -1,37 +1,61 @@
-GO_FILES := $(shell find . -type f -name '*.go' -not -path "./vendor/*")
 BUILD_DIR := build
+LINT_CONFIG := $(CURDIR)/.golangci.yml
+
+# All Go modules in the workspace, derived from go.work to stay in sync.
+# Note: the leading "./" is required for find -execdir / cd targets.
+MODULES := $(shell find . -name go.mod -not -path '*/vendor/*' -not -path '*/node_modules/*' -not -path '*/build/*' | sort | sed 's|/go.mod||')
 
 .PHONY: all
 all: test
 
 .PHONY: clean
 clean:
-	@go clean -i ./...
+	@rm -rf $(BUILD_DIR)
+	@for mod in $(MODULES); do (cd "$$mod" && go clean -i ./...); done
 
 _build:
-	@mkdir -p ${BUILD_DIR}
+	@mkdir -p $(BUILD_DIR)
+
+.PHONY: sync
+sync:
+	@echo "Syncing workspace..."
+	@go work sync
 
 .PHONY: build
 build:
-	@echo "Building..."
-	@go build -race -v ./...
+	@for mod in $(MODULES); do \
+		echo "==> build $$mod"; \
+		(cd "$$mod" && go build -v ./...) || exit 1; \
+	done
 
 .PHONY: generate
 generate:
-	@echo "Generating code..."
+	@echo "Generating mocks..."
 	@go generate ./...
 
-$(BUILD_DIR)/coverage.out: _build $(GO_FILES)
-	@go test -cover -race -coverprofile $(BUILD_DIR)/coverage.out.tmp -timeout 300s ./...
-	@cat $(BUILD_DIR)/coverage.out.tmp | grep -v '.pb.go' | grep -v 'mock_' > $(BUILD_DIR)/coverage.out
-	@rm $(BUILD_DIR)/coverage.out.tmp
-
 .PHONY: test
-test: $(BUILD_DIR)/coverage.out
+test: _build
+	@: > $(BUILD_DIR)/coverage.out
+	@for mod in $(MODULES); do \
+		echo "==> test $$mod"; \
+		mod_safe=$$(echo "$$mod" | sed 's|/|_|g; s|^\._||; s|^\.$$|root|'); \
+		(cd "$$mod" && go test -cover -race \
+			-coverprofile="$(CURDIR)/$(BUILD_DIR)/$$mod_safe.cover" \
+			-timeout 300s ./...) || exit 1; \
+	done
+	@# Aggregate coverage excludes generated mocks, protobuf, and the
+	@# example programs: their main() binds a socket and blocks, so it is
+	@# not unit-testable and would skew the library coverage figure. The
+	@# examples are still built, tested, and linted above.
+	@grep -h -v '^mode:' $(BUILD_DIR)/*.cover 2>/dev/null \
+		| grep -v 'mock_' | grep -v '.pb.go' | grep -v '/example' \
+		> $(BUILD_DIR)/coverage.body || true
+	@echo 'mode: atomic' > $(BUILD_DIR)/coverage.out
+	@cat $(BUILD_DIR)/coverage.body >> $(BUILD_DIR)/coverage.out
+	@rm -f $(BUILD_DIR)/*.cover $(BUILD_DIR)/coverage.body
 
 .PHONY: coverage
 coverage: $(BUILD_DIR)/coverage.out
-	@echo ""
 	@go tool cover -func ./$(BUILD_DIR)/coverage.out
 
 .PHONY: coverage-html
@@ -40,19 +64,27 @@ coverage-html: $(BUILD_DIR)/coverage.out
 
 .PHONY: bench
 bench:
-	@echo "Running benchmarks..."
-	@go test -bench=. -benchmem -benchtime=5s -timeout 300s ./...
-
+	@for mod in $(MODULES); do \
+		echo "==> bench $$mod"; \
+		(cd "$$mod" && go test -bench=. -benchmem -benchtime=5s -timeout 300s ./...) || exit 1; \
+	done
 
 .PHONY: lint
 lint:
 ifeq (, $(shell which golangci-lint))
 	@echo "Install golangci-lint..."
-	@curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.6.2
+	@curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh \
+		| sh -s -- -b $$(go env GOPATH)/bin v2.12.2
 endif
-	@echo "lint..."
-	@golangci-lint run --timeout=300s ./...
+	@go list -f '{{.Dir}}/...' -m | xargs golangci-lint run --timeout=300s --config="$(LINT_CONFIG)"
 
+.PHONY: tidy
+tidy:
+	@for mod in $(MODULES); do \
+		echo "==> tidy $$mod"; \
+		(cd "$$mod" && go mod tidy) || exit 1; \
+	done
+	@go work sync
 
 .PHONY: release
 release:
diff --git a/README.md b/README.md
index ba10910..0bceb39 100644
--- a/README.md
+++ b/README.md
@@ -7,23 +7,91 @@ Hyperscale security [![Last release](https://img.shields.io/github/release/hyper
 |---------|--------|----------|
 | master  | [![Build Status](https://github.com/hyperscale-stack/security/workflows/Go/badge.svg?branch=master)](https://github.com/hyperscale-stack/security/actions?query=workflow%3AGo) | [![Coveralls](https://img.shields.io/coveralls/hyperscale-stack/security/master.svg)](https://coveralls.io/github/hyperscale-stack/security?branch=master) |
 
-The Hyperscale security is a powerful and highly customizable authentication and access-control framework.
+A transport-agnostic authentication and authorization toolkit for Go —
+HTTP and gRPC, OAuth2, JWT, sessions, and a composable Voter-based access
+model. It is shipped as a multi-module workspace so you import only what
+you need.
 
-## Example
+## Modules
+
+| Module                                              | Purpose                                                         |
+| --------------------------------------------------- | --------------------------------------------------------------- |
+| `github.com/hyperscale-stack/security`              | Core: `Authentication`, `Engine`, `Manager`, `Voter`, ADM       |
+| `…/security/http`                                   | `httpsec` — `net/http` middleware + authorization               |
+| `…/security/grpc`                                   | `grpcsec` — unary/stream interceptors                           |
+| `…/security/basic`                                  | HTTP Basic extractor + authenticator                            |
+| `…/security/bearer`                                 | Bearer extractor + `TokenVerifier` authenticator                |
+| `…/security/password`                               | BCrypt + Argon2id hashers (`NeedsRehash`)                       |
+| `…/security/jwt`                                    | `jwtsec` — JWT signer/verifier, JWKS                            |
+| `…/security/session`                                | Stateless encrypted cookie sessions + CSRF                      |
+| `…/security/oauth2`                                 | OAuth2 server: profiles, grants, endpoints                      |
+| `…/security/oauth2/store/sql`                       | Production OAuth2 storage on `database/sql`                     |
+| `…/security/oauth2/store/redis`                     | Production OAuth2 storage on Redis                              |
+
+## Install
+
+```sh
+go get github.com/hyperscale-stack/security
+go get github.com/hyperscale-stack/security/http   # and any other module you need
+```
+
+## Quick start — HTTP Basic
 
 ```go
 package main
 
 import (
-    "fmt"
-    "github.com/hyperscale-stack/security"
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/basic"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/hyperscale-stack/security/password"
 )
 
 func main() {
+	// loader is your UserLoader implementation (DB-backed, etc.).
+	authenticator := basic.NewAuthenticator(loader, password.NewBCryptHasher(12))
+
+	engine := security.NewEngine(
+		security.NewManager(authenticator),
+		basic.NewExtractor(),
+	)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		auth, _ := security.FromContext(r.Context())
+		w.Write([]byte("hello " + auth.Name()))
+	})
 
-    
+	http.ListenAndServe(":8080", httpsec.Middleware(engine)(mux))
 }
+```
+
+Add authorization with a Voter and an `AccessDecisionManager`:
+
+```go
+adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+mux.Handle("/admin", httpsec.Authorize(adm, security.Role("ADMIN"))(adminHandler))
+```
+
+## Documentation
+
+- [docs/architecture.md](docs/architecture.md) — modules, pipelines, design.
+- [docs/observability.md](docs/observability.md) — OpenTelemetry span catalog.
+- [docs/security-considerations.md](docs/security-considerations.md) — defaults and threat model.
+- [docs/migration-from-v0.md](docs/migration-from-v0.md) — upgrading from the v0 stack.
+- [MIGRATION.md](MIGRATION.md) — workspace layout and dependency policy.
+- [LIMITATIONS.md](LIMITATIONS.md) — known gaps.
+- [examples/](examples) — runnable per-scenario demos.
+
+## Development
 
+```sh
+make sync     # go work sync
+make build    # build every module
+make test     # race + coverage
+make lint     # golangci-lint with the shared config
 ```
 
 ## License
diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index a84a4e4..0000000
--- a/TODO.md
+++ /dev/null
@@ -1,17 +0,0 @@
-* faire un `AuthenticationManager` ou un `ProviderManager` qui liste les providers à utilisé et vérifie si un `Filter` match via `Provider.IsSupported()` et appel `Provider.Authenticate()` si c'est supporté
-* Faire le systeme de filter ex: `BearerAuthenticationFilter`, `OAuth2AuthenticationFilter`, `HTTPBasicAuthenticationFilter`, `HTTPDigestAuthenticationFilter`, etc...
-* faire un autre module `security-service-provider` pour utilisé ça via go-application
-* faire un middleware `Authentication()` pour detecter via les Filters le type d'auth
-* faire un middleware `Authorize()` qui sera utilisé sur une route pour vérifier que l'auth trouvé via un filter est authenticated et validate
-* * faire un system d'options pour `Authorize()`, ex: `Authorize(HasRole("ADMIN"))` ???
-
-
-TODO
-====
-
-
-- [ ] Filters 
- - [x] AccessTokenFilter
- - [x] BearerFilter
- - [x] HTTPBasicFilter
- - [ ] HTTPDigestFilter
diff --git a/access_decision_manager.go b/access_decision_manager.go
new file mode 100644
index 0000000..eb45a42
--- /dev/null
+++ b/access_decision_manager.go
@@ -0,0 +1,240 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import (
+	"context"
+	"strings"
+
+	"go.opentelemetry.io/otel/codes"
+)
+
+// AccessDecisionManager combines the verdicts of multiple [Voter]s into a
+// single decision. Three strategies are provided, mirroring Spring Security:
+//
+//   - Affirmative — a single [DecisionGrant] grants access; everything else
+//     denies. Abstentions are ignored. The strictest "fail closed
+//     by default" policy.
+//   - Consensus   — the majority wins. Ties default to deny; pass
+//     [WithTieBreak](DecisionGrant) to flip the policy.
+//   - Unanimous   — every voter that does not abstain MUST grant. A single
+//     deny refuses; if every voter abstains, the result depends on
+//     [WithAbstainFallback].
+//
+// Implementations are safe for concurrent use.
+type AccessDecisionManager interface {
+	// Decide returns nil on grant, [ErrAccessDenied] on deny.
+	// Wrapping callers add a short message indicating the strategy used.
+	Decide(ctx context.Context, auth Authentication, attrs []Attribute) error
+}
+
+// admOption configures NewAffirmative/NewConsensus/NewUnanimous.
+type admOption func(*admConfig)
+
+type admConfig struct {
+	tieBreak        Decision // for consensus
+	abstainFallback Decision // for unanimous
+}
+
+// WithTieBreak controls the consensus strategy when grant and deny votes
+// are equal in number. Default: DecisionDeny.
+func WithTieBreak(d Decision) admOption { //nolint:revive // exported via constructors
+	return func(c *admConfig) { c.tieBreak = d }
+}
+
+// WithAbstainFallback controls the verdict when every unanimous voter
+// abstains. Default: DecisionDeny.
+func WithAbstainFallback(d Decision) admOption { //nolint:revive // exported via constructors
+	return func(c *admConfig) { c.abstainFallback = d }
+}
+
+// NewAffirmativeDecisionManager returns an [AccessDecisionManager] that
+// grants access as soon as one voter does, and denies otherwise.
+func NewAffirmativeDecisionManager(voters ...Voter) AccessDecisionManager {
+	return &accessDecisionManager{
+		strategy: "affirmative",
+		voters:   cloneVoters(voters),
+		decide:   affirmative,
+	}
+}
+
+// NewConsensusDecisionManager returns an [AccessDecisionManager] that
+// follows majority rule. Pass [WithTieBreak] to override the default
+// (deny-on-tie) behavior.
+func NewConsensusDecisionManager(voters []Voter, opts ...admOption) AccessDecisionManager {
+	cfg := admConfig{tieBreak: DecisionDeny}
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	return &accessDecisionManager{
+		strategy: "consensus",
+		voters:   cloneVoters(voters),
+		decide:   consensus(cfg.tieBreak),
+	}
+}
+
+// NewUnanimousDecisionManager returns an [AccessDecisionManager] that
+// refuses on a single deny and otherwise grants when at least one voter
+// grants. Pass [WithAbstainFallback] to control the all-abstain case.
+func NewUnanimousDecisionManager(voters []Voter, opts ...admOption) AccessDecisionManager {
+	cfg := admConfig{abstainFallback: DecisionDeny}
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	return &accessDecisionManager{
+		strategy: "unanimous",
+		voters:   cloneVoters(voters),
+		decide:   unanimous(cfg.abstainFallback),
+	}
+}
+
+type accessDecisionManager struct {
+	strategy string
+	voters   []Voter
+	decide   func(votes []Decision) Decision
+}
+
+// Decide implements [AccessDecisionManager].
+func (m *accessDecisionManager) Decide(ctx context.Context, auth Authentication, attrs []Attribute) error {
+	ctx, span := tracer().Start(ctx, "security.AccessDecisionManager.Decide")
+	defer span.End()
+
+	span.SetAttributes(
+		AttrStrategy.String(m.strategy),
+		AttrAttributes.String(joinAttributes(attrs)),
+	)
+
+	votes := make([]Decision, 0, len(m.voters))
+
+	for _, v := range m.voters {
+		if !anySupported(v, attrs) {
+			votes = append(votes, DecisionAbstain)
+
+			continue
+		}
+
+		votes = append(votes, v.Vote(ctx, auth, attrs))
+	}
+
+	final := m.decide(votes)
+	span.SetAttributes(AttrDecision.String(final.String()))
+
+	if final == DecisionGrant {
+		return nil
+	}
+
+	span.SetStatus(codes.Error, ErrAccessDenied.Error())
+
+	return ErrAccessDenied
+}
+
+// affirmative returns Grant on first grant, Deny otherwise. Abstentions are
+// ignored.
+func affirmative(votes []Decision) Decision {
+	denySeen := false
+
+	for _, v := range votes {
+		switch v {
+		case DecisionGrant:
+			return DecisionGrant
+		case DecisionDeny:
+			denySeen = true
+		case DecisionAbstain:
+			// ignore
+		}
+	}
+
+	if denySeen {
+		return DecisionDeny
+	}
+
+	return DecisionDeny // all abstain -> deny by default
+}
+
+// consensus returns Grant if grants > denies, Deny if denies > grants, and
+// the configured tie-break otherwise. All abstentions -> deny by default.
+func consensus(tieBreak Decision) func([]Decision) Decision {
+	return func(votes []Decision) Decision {
+		grants, denies := 0, 0
+
+		for _, v := range votes {
+			switch v {
+			case DecisionGrant:
+				grants++
+			case DecisionDeny:
+				denies++
+			case DecisionAbstain:
+				// ignore
+			}
+		}
+
+		switch {
+		case grants == 0 && denies == 0:
+			return DecisionDeny
+		case grants > denies:
+			return DecisionGrant
+		case denies > grants:
+			return DecisionDeny
+		default:
+			return tieBreak
+		}
+	}
+}
+
+// unanimous returns Deny on any deny; otherwise Grant if at least one voter
+// granted; otherwise the configured all-abstain fallback.
+func unanimous(allAbstainFallback Decision) func([]Decision) Decision {
+	return func(votes []Decision) Decision {
+		grantSeen := false
+
+		for _, v := range votes {
+			if v == DecisionDeny {
+				return DecisionDeny
+			}
+
+			if v == DecisionGrant {
+				grantSeen = true
+			}
+		}
+
+		if grantSeen {
+			return DecisionGrant
+		}
+
+		return allAbstainFallback
+	}
+}
+
+func anySupported(v Voter, attrs []Attribute) bool {
+	for _, a := range attrs {
+		if v.Supports(a) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func joinAttributes(attrs []Attribute) string {
+	if len(attrs) == 0 {
+		return ""
+	}
+
+	parts := make([]string, len(attrs))
+	for i, a := range attrs {
+		parts[i] = a.String()
+	}
+
+	return strings.Join(parts, ",")
+}
+
+func cloneVoters(in []Voter) []Voter {
+	cp := make([]Voter, len(in))
+	copy(cp, in)
+
+	return cp
+}
diff --git a/access_decision_manager_test.go b/access_decision_manager_test.go
new file mode 100644
index 0000000..7d8f23a
--- /dev/null
+++ b/access_decision_manager_test.go
@@ -0,0 +1,203 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAffirmativeGrantsOnAnyGrant(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+	)
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	require.NoError(t, err)
+}
+
+func TestAffirmativeDeniesWhenNoGrant(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionAbstain},
+	)
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	assert.ErrorIs(t, err, security.ErrAccessDenied)
+}
+
+func TestAffirmativeDeniesWhenAllAbstain(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(
+		&scriptedVoter{prefix: "role:", vote: security.DecisionGrant}, // does not support scope:
+	)
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	assert.ErrorIs(t, err, security.ErrAccessDenied,
+		"unsupported attributes cause abstention, not silent grant")
+}
+
+func TestConsensusFollowsMajority(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewConsensusDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+	})
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	require.NoError(t, err)
+}
+
+func TestConsensusTieBreakDefaultsToDeny(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewConsensusDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+	})
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	assert.ErrorIs(t, err, security.ErrAccessDenied)
+}
+
+func TestConsensusTieBreakOverride(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewConsensusDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+	}, security.WithTieBreak(security.DecisionGrant))
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	require.NoError(t, err)
+}
+
+func TestUnanimousDeniesOnAnyDeny(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewUnanimousDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+	})
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	assert.ErrorIs(t, err, security.ErrAccessDenied)
+}
+
+func TestUnanimousGrantsWhenAtLeastOneGrantsAndNoneDeny(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewUnanimousDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+		&scriptedVoter{prefix: "role:", vote: security.DecisionGrant}, // abstains on scope:
+	})
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	require.NoError(t, err)
+}
+
+func TestUnanimousAbstainFallbackDefaultsToDeny(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewUnanimousDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "role:", vote: security.DecisionGrant}, // abstains on scope:
+	})
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	assert.ErrorIs(t, err, security.ErrAccessDenied)
+}
+
+func TestUnanimousAbstainFallbackOverride(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewUnanimousDecisionManager([]security.Voter{
+		&scriptedVoter{prefix: "role:", vote: security.DecisionGrant},
+	}, security.WithAbstainFallback(security.DecisionGrant))
+
+	err := adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+		[]security.Attribute{stringAttr("scope:read")})
+
+	require.NoError(t, err)
+}
+
+func TestADMSpanCarriesStrategyAndDecision(t *testing.T) {
+	adm := security.NewAffirmativeDecisionManager(
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionGrant},
+	)
+
+	spans := spanRecorder(func() {
+		_ = adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+			[]security.Attribute{stringAttr("scope:read")})
+	})
+
+	require.Len(t, spans, 1)
+	span := spans[0]
+	assert.Equal(t, "security.AccessDecisionManager.Decide", span.Name())
+	assert.Equal(t, "affirmative", findAttr(span.Attributes(), security.AttrStrategy))
+	assert.Equal(t, "permit", findAttr(span.Attributes(), security.AttrDecision))
+	assert.Equal(t, "scope:read", findAttr(span.Attributes(), security.AttrAttributes))
+}
+
+func TestADMSpanRecordsErrorOnDeny(t *testing.T) {
+	adm := security.NewAffirmativeDecisionManager(
+		&scriptedVoter{prefix: "scope:", vote: security.DecisionDeny},
+	)
+
+	spans := spanRecorder(func() {
+		_ = adm.Decide(context.Background(), newFakeAuth("alice").withAuthenticated(),
+			[]security.Attribute{stringAttr("scope:read")})
+	})
+
+	require.Len(t, spans, 1)
+	assert.Equal(t, "Error", spans[0].Status().Code.String())
+}
+
+func TestDecisionString(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		d    security.Decision
+		want string
+	}{
+		{security.DecisionGrant, "permit"},
+		{security.DecisionDeny, "deny"},
+		{security.DecisionAbstain, "abstain"},
+		{security.Decision(42), "unknown"},
+	}
+	for _, c := range cases {
+		assert.Equal(t, c.want, c.d.String())
+	}
+}
diff --git a/anonymous.go b/anonymous.go
new file mode 100644
index 0000000..daf5f65
--- /dev/null
+++ b/anonymous.go
@@ -0,0 +1,33 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+// Anonymous returns the singleton [Authentication] used when no credential
+// could be extracted from a [Carrier]. It is safe to call from any goroutine;
+// the returned value is shared and immutable.
+//
+// Voters that opt-in to anonymous access (see the voter package's
+// Anonymous) match this value; the default policy of [AccessDecisionManager]
+// is to deny when no voter grants, so anonymous calls fail closed by default.
+func Anonymous() Authentication { return anonymousAuth }
+
+// anonymousAuth is the package-wide singleton returned by Anonymous().
+var anonymousAuth Authentication = anonymousAuthentication{}
+
+type anonymousAuthentication struct{}
+
+func (anonymousAuthentication) Principal() Principal { return AnonymousPrincipal }
+func (anonymousAuthentication) Credentials() any     { return nil }
+func (anonymousAuthentication) Authorities() []string {
+	// Returning nil rather than a shared zero-length slice prevents
+	// accidental mutation by misbehaving callers.
+	return nil
+}
+func (anonymousAuthentication) IsAuthenticated() bool { return false }
+func (anonymousAuthentication) Name() string          { return anonymousSubject }
+
+// anonymousSubject is the stable subject string used by both
+// [AnonymousPrincipal] and the anonymous [Authentication.Name].
+const anonymousSubject = "anonymous"
diff --git a/anonymous_test.go b/anonymous_test.go
new file mode 100644
index 0000000..cc5db15
--- /dev/null
+++ b/anonymous_test.go
@@ -0,0 +1,32 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAnonymousIsStableSingleton(t *testing.T) {
+	t.Parallel()
+
+	a := security.Anonymous()
+	b := security.Anonymous()
+
+	assert.Equal(t, a, b, "Anonymous() must return the same value every call")
+	assert.False(t, a.IsAuthenticated())
+	assert.Nil(t, a.Credentials())
+	assert.Nil(t, a.Authorities())
+	assert.Equal(t, "anonymous", a.Name())
+	assert.Equal(t, security.AnonymousPrincipal, a.Principal())
+}
+
+func TestAnonymousPrincipalSubject(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "anonymous", security.AnonymousPrincipal.Subject())
+}
diff --git a/attribute.go b/attribute.go
new file mode 100644
index 0000000..573e662
--- /dev/null
+++ b/attribute.go
@@ -0,0 +1,82 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "context"
+
+// Attribute is an opaque authorization predicate carried alongside a request.
+// Voters opt-in via [Voter.Supports] and inspect the concrete type through
+// type switches. Four concrete attributes are shipped below; applications
+// can define their own (they just need to implement String()).
+type Attribute interface {
+	// String returns a stable, log-friendly form of the attribute. It is used
+	// by [AccessDecisionManager] for OTel attributes; it MUST NOT include
+	// any secret or PII.
+	String() string
+}
+
+// RoleAttribute names a role expected on the authenticated principal. Roles
+// use the Spring Security "ROLE_" prefix at the wire level (in OTel
+// attributes and in custom Authorities() slices) but the constructor
+// accepts the bare name to keep usage idiomatic.
+type RoleAttribute string
+
+// String implements [Attribute]. Output is "ROLE_<name>" — Spring-compatible
+// for ops tooling that already keys off that convention.
+func (r RoleAttribute) String() string { return rolePrefix + string(r) }
+
+// Name returns the bare role name (without the ROLE_ prefix).
+func (r RoleAttribute) Name() string { return string(r) }
+
+// Role constructs a [RoleAttribute] from a bare role name.
+func Role(name string) Attribute { return RoleAttribute(name) }
+
+const rolePrefix = "ROLE_"
+
+// ScopeAttribute names an OAuth2 scope expected on the authenticated
+// principal. Scope names follow the RFC 6749 §3.3 grammar but this type
+// stays format-agnostic.
+type ScopeAttribute string
+
+// String implements [Attribute]. Output is "scope:<name>".
+func (s ScopeAttribute) String() string { return "scope:" + string(s) }
+
+// Name returns the bare scope name.
+func (s ScopeAttribute) Name() string { return string(s) }
+
+// Scope constructs a [ScopeAttribute].
+func Scope(name string) Attribute { return ScopeAttribute(name) }
+
+// AuthorityAttribute names a free-form authority string. Unlike
+// [RoleAttribute] it carries no convention — the configured voter compares
+// the value verbatim against [Authentication.Authorities].
+type AuthorityAttribute string
+
+// String implements [Attribute]. Output is the bare authority name.
+func (a AuthorityAttribute) String() string { return string(a) }
+
+// Authority constructs an [AuthorityAttribute].
+func Authority(name string) Attribute { return AuthorityAttribute(name) }
+
+// PermissionAttribute carries an arbitrary predicate evaluated by the
+// permission voter. It is the escape hatch for application-specific
+// authorization (ABAC, ownership checks, time-of-day windows, ...).
+// The predicate MUST be pure (no I/O) and safe for concurrent use.
+type PermissionAttribute struct {
+	// Name is the human-readable label of the permission. It populates the
+	// OTel attributes; keep it stable across deployments.
+	Name string
+	// Predicate is invoked by the permission voter with the live
+	// authentication. A nil predicate is treated as DecisionDeny.
+	Predicate func(ctx context.Context, auth Authentication) bool
+}
+
+// String implements [Attribute]. Output is "permission:<Name>".
+func (p PermissionAttribute) String() string { return "permission:" + p.Name }
+
+// Permission constructs a [PermissionAttribute] in one call.
+func Permission(name string, predicate func(ctx context.Context, auth Authentication) bool) Attribute {
+	return PermissionAttribute{Name: name, Predicate: predicate}
+}
diff --git a/attribute_test.go b/attribute_test.go
new file mode 100644
index 0000000..a022d28
--- /dev/null
+++ b/attribute_test.go
@@ -0,0 +1,75 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRoleAttribute(t *testing.T) {
+	t.Parallel()
+
+	attr := security.Role("ADMIN")
+
+	role, ok := attr.(security.RoleAttribute)
+	require.True(t, ok)
+
+	// String() carries the Spring-style ROLE_ prefix.
+	assert.Equal(t, "ROLE_ADMIN", attr.String())
+	// Name() returns the bare role.
+	assert.Equal(t, "ADMIN", role.Name())
+}
+
+func TestScopeAttribute(t *testing.T) {
+	t.Parallel()
+
+	attr := security.Scope("read:mail")
+
+	scope, ok := attr.(security.ScopeAttribute)
+	require.True(t, ok)
+
+	assert.Equal(t, "scope:read:mail", attr.String())
+	assert.Equal(t, "read:mail", scope.Name())
+}
+
+func TestAuthorityAttribute(t *testing.T) {
+	t.Parallel()
+
+	attr := security.Authority("billing:export")
+
+	_, ok := attr.(security.AuthorityAttribute)
+	require.True(t, ok)
+
+	// Authority carries no convention — String() is the bare value.
+	assert.Equal(t, "billing:export", attr.String())
+}
+
+func TestPermissionAttribute(t *testing.T) {
+	t.Parallel()
+
+	called := false
+	predicate := func(context.Context, security.Authentication) bool {
+		called = true
+
+		return true
+	}
+
+	attr := security.Permission("owns-document", predicate)
+
+	perm, ok := attr.(security.PermissionAttribute)
+	require.True(t, ok)
+
+	assert.Equal(t, "permission:owns-document", attr.String())
+	assert.Equal(t, "owns-document", perm.Name)
+
+	require.NotNil(t, perm.Predicate)
+	assert.True(t, perm.Predicate(context.Background(), security.Anonymous()))
+	assert.True(t, called, "the constructed predicate must be the one supplied")
+}
diff --git a/authentication.go b/authentication.go
new file mode 100644
index 0000000..066ee52
--- /dev/null
+++ b/authentication.go
@@ -0,0 +1,55 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+// Authentication is an immutable snapshot of a security context: who is acting
+// (the [Principal]), what proof was presented (the credentials), what
+// authorities the system has granted them, and whether the proof has been
+// verified.
+//
+// Authentication values flow through three logical stages during a request:
+//
+//  1. An [Extractor] reads raw credentials from a [Carrier] and constructs an
+//     unauthenticated value (IsAuthenticated() == false).
+//  2. A matching [Authenticator] validates the credentials and returns a NEW
+//     authenticated value (IsAuthenticated() == true). The original value
+//     MUST NOT be mutated.
+//  3. Authorisation [Voter]s inspect the value to grant or deny access.
+//
+// Implementations MUST be safe for concurrent reads. Because every state
+// change goes through a fresh value, no synchronization is required for
+// callers.
+type Authentication interface {
+	// Principal returns the identity carried by this authentication.
+	// MUST return [AnonymousPrincipal] for unauthenticated values and
+	// MUST NOT return nil.
+	Principal() Principal
+
+	// Credentials returns the raw credentials presented by the principal.
+	// For a token-based authentication this is typically the token string;
+	// for username/password it is the cleartext password. Implementations
+	// SHOULD zero or omit secret material once authentication has succeeded
+	// to limit accidental leakage through logging or panics.
+	//
+	// The return type is intentionally any: typed accessors are provided by
+	// each scheme module (basic.Password(), bearer.Token(), ...).
+	Credentials() any
+
+	// Authorities returns the authorities (roles, scopes, permissions) the
+	// system has granted to this principal. The slice is read-only;
+	// implementations SHOULD return the same backing slice across calls.
+	Authorities() []string
+
+	// IsAuthenticated reports whether the credentials have been validated by
+	// an [Authenticator]. Voters use this to short-circuit denials before
+	// inspecting authorities.
+	IsAuthenticated() bool
+
+	// Name returns a stable, log-friendly identifier for this authentication.
+	// It is typically the principal subject; for client_credentials flows it
+	// can be the client ID. It MUST be safe to include in structured logs
+	// (no secrets, no high-cardinality values that are not the subject).
+	Name() string
+}
diff --git a/authentication/access_token_filter.go b/authentication/access_token_filter.go
deleted file mode 100644
index c5f13df..0000000
--- a/authentication/access_token_filter.go
+++ /dev/null
@@ -1,36 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-)
-
-var _ Filter = (*AccessTokenFilter)(nil)
-
-// AccessTokenFilter struct.
-type AccessTokenFilter struct {
-}
-
-// NewAccessTokenFilter constructor.
-func NewAccessTokenFilter() Filter {
-	return &AccessTokenFilter{}
-}
-
-// OnFilter implements Filter.
-func (f *AccessTokenFilter) OnFilter(r *http.Request) *http.Request {
-	ctx := r.Context()
-
-	creds := r.URL.Query().Get("access_token")
-	if creds == "" {
-		return r
-	}
-
-	token := credential.NewTokenCredential(creds)
-
-	return r.WithContext(credential.ToContext(ctx, token))
-}
diff --git a/authentication/access_token_filter_test.go b/authentication/access_token_filter_test.go
deleted file mode 100644
index 847641c..0000000
--- a/authentication/access_token_filter_test.go
+++ /dev/null
@@ -1,61 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestAccessTokenFilter(t *testing.T) {
-	f := NewAccessTokenFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path?access_token=foo", nil)
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-
-	assert.IsType(t, &credential.TokenCredential{}, auth)
-	assert.Equal(t, "foo", auth.GetPrincipal())
-}
-
-func TestAccessTokenFilterWithoutAccessTokenInQueryString(t *testing.T) {
-	f := NewAccessTokenFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func TestAccessTokenFilterWithEmptyAccessTokenInQueryString(t *testing.T) {
-	f := NewAccessTokenFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path?access_token=", nil)
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func BenchmarkAccessTokenFilter(b *testing.B) {
-	f := NewAccessTokenFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path?access_token=foo", nil)
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		r = f.OnFilter(r)
-	}
-}
diff --git a/authentication/bearer_filter.go b/authentication/bearer_filter.go
deleted file mode 100644
index 33743e5..0000000
--- a/authentication/bearer_filter.go
+++ /dev/null
@@ -1,42 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/http/header"
-)
-
-var _ Filter = (*BearerFilter)(nil)
-
-// BearerFilter struct.
-type BearerFilter struct {
-}
-
-// NewBearerFilter constructor.
-func NewBearerFilter() Filter {
-	return &BearerFilter{}
-}
-
-// OnFilter implements Filter.
-func (f *BearerFilter) OnFilter(r *http.Request) *http.Request {
-	ctx := r.Context()
-
-	auth := r.Header.Get("Authorization")
-	if auth == "" {
-		return r
-	}
-
-	creds, ok := header.ExtractAuthorizationValue("Bearer", auth)
-	if !ok {
-		return r
-	}
-
-	token := credential.NewTokenCredential(creds)
-
-	return r.WithContext(credential.ToContext(ctx, token))
-}
diff --git a/authentication/bearer_filter_test.go b/authentication/bearer_filter_test.go
deleted file mode 100644
index 933a4be..0000000
--- a/authentication/bearer_filter_test.go
+++ /dev/null
@@ -1,63 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestBearerFilter(t *testing.T) {
-	f := NewBearerFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Bearer foo")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-
-	assert.IsType(t, &credential.TokenCredential{}, auth)
-}
-
-func TestBearerFilterWithoutAuthorizationHeader(t *testing.T) {
-	f := NewBearerFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func TestBearerFilterWithBadAuthorizationType(t *testing.T) {
-	f := NewBearerFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Basic Zm9vOnBhc3M=")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func BenchmarkBearerFilter(b *testing.B) {
-	f := NewBearerFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Bearer foo")
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		r = f.OnFilter(r)
-	}
-}
diff --git a/authentication/credential/context.go b/authentication/credential/context.go
deleted file mode 100644
index c5fad8e..0000000
--- a/authentication/credential/context.go
+++ /dev/null
@@ -1,23 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import "context"
-
-type credentialCtxKey struct{}
-
-// FromContext returns the Credential associated with the ctx.
-func FromContext(ctx context.Context) Credential {
-	if c, ok := ctx.Value(credentialCtxKey{}).(Credential); ok {
-		return c
-	}
-
-	return nil
-}
-
-// ToContext returns new context with Credential.
-func ToContext(ctx context.Context, creds Credential) context.Context {
-	return context.WithValue(ctx, credentialCtxKey{}, creds)
-}
diff --git a/authentication/credential/context_test.go b/authentication/credential/context_test.go
deleted file mode 100644
index 80c498d..0000000
--- a/authentication/credential/context_test.go
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestContext(t *testing.T) {
-	ctx := context.Background()
-
-	creds1 := NewTokenCredential("foo")
-
-	ctx = ToContext(ctx, creds1)
-
-	creds2 := FromContext(ctx)
-
-	assert.Equal(t, creds1, creds2)
-}
-
-func TestFromContextWithEmptyContext(t *testing.T) {
-	ctx := context.Background()
-
-	creds := FromContext(ctx)
-
-	assert.Nil(t, creds)
-}
diff --git a/authentication/credential/credential.go b/authentication/credential/credential.go
deleted file mode 100644
index 70465b8..0000000
--- a/authentication/credential/credential.go
+++ /dev/null
@@ -1,17 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import "github.com/hyperscale-stack/security/user"
-
-// Credential interface.
-type Credential interface {
-	GetPrincipal() interface{}
-	GetCredentials() interface{}
-	IsAuthenticated() bool
-	SetAuthenticated(isAuthenticated bool)
-	SetUser(user user.User)
-	GetUser() user.User
-}
diff --git a/authentication/credential/token_authentication_test.go b/authentication/credential/token_authentication_test.go
deleted file mode 100644
index a2f1790..0000000
--- a/authentication/credential/token_authentication_test.go
+++ /dev/null
@@ -1,30 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import (
-	"testing"
-
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestNewTokenCredential(t *testing.T) {
-	a := NewTokenCredential("my-token")
-
-	assert.Equal(t, "my-token", a.GetPrincipal())
-
-	assert.Nil(t, a.GetCredentials())
-
-	assert.False(t, a.IsAuthenticated())
-
-	userMock := &user.MockUser{}
-
-	a.SetAuthenticated(true)
-	a.SetUser(userMock)
-
-	assert.True(t, a.IsAuthenticated())
-	assert.Equal(t, userMock, a.GetUser())
-}
diff --git a/authentication/credential/token_credential.go b/authentication/credential/token_credential.go
deleted file mode 100644
index 045cf17..0000000
--- a/authentication/credential/token_credential.go
+++ /dev/null
@@ -1,55 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import "github.com/hyperscale-stack/security/user"
-
-// TokenCredential struct.
-type TokenCredential struct {
-	isAuthenticated bool
-	principal       interface{}
-	user            user.User
-}
-
-var _ Credential = (*TokenCredential)(nil)
-
-// NewTokenCredential constructor.
-func NewTokenCredential(t string) Credential {
-	return &TokenCredential{
-		principal: t,
-	}
-}
-
-// GetCredentials that prove the principal is correct, this is usually a password.
-func (a *TokenCredential) GetCredentials() interface{} {
-	return nil
-}
-
-// GetPrincipal The identity of the principal being authenticated.
-// In the case of an authentication request with username and password,
-// this would be the username.
-func (a *TokenCredential) GetPrincipal() interface{} {
-	return a.principal
-}
-
-// IsAuthenticated returns true if token is authenticated.
-func (a *TokenCredential) IsAuthenticated() bool {
-	return a.isAuthenticated
-}
-
-// SetAuthenticated change token to authenticated.
-func (a *TokenCredential) SetAuthenticated(isAuthenticated bool) {
-	a.isAuthenticated = isAuthenticated
-}
-
-// SetUser set user authenticated.
-func (a *TokenCredential) SetUser(user user.User) {
-	a.user = user
-}
-
-// GetUser return authenticated.
-func (a *TokenCredential) GetUser() user.User {
-	return a.user
-}
diff --git a/authentication/credential/username_password_credential.go b/authentication/credential/username_password_credential.go
deleted file mode 100644
index 712fdbb..0000000
--- a/authentication/credential/username_password_credential.go
+++ /dev/null
@@ -1,57 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import "github.com/hyperscale-stack/security/user"
-
-// UsernamePasswordCredential struct.
-type UsernamePasswordCredential struct {
-	isAuthenticated bool
-	credentials     interface{}
-	principal       interface{}
-	user            user.User
-}
-
-var _ Credential = (*UsernamePasswordCredential)(nil)
-
-// NewUsernamePasswordCredential constructor.
-func NewUsernamePasswordCredential(principal string, credentials string) Credential {
-	return &UsernamePasswordCredential{
-		credentials: credentials,
-		principal:   principal,
-	}
-}
-
-// GetCredentials that prove the principal is correct, this is usually a password.
-func (a *UsernamePasswordCredential) GetCredentials() interface{} {
-	return a.credentials
-}
-
-// GetPrincipal The identity of the principal being authenticated.
-// In the case of an authentication request with username and password,
-// this would be the username.
-func (a *UsernamePasswordCredential) GetPrincipal() interface{} {
-	return a.principal
-}
-
-// IsAuthenticated returns true if token is authenticated.
-func (a *UsernamePasswordCredential) IsAuthenticated() bool {
-	return a.isAuthenticated
-}
-
-// SetAuthenticated change token to authenticated.
-func (a *UsernamePasswordCredential) SetAuthenticated(isAuthenticated bool) {
-	a.isAuthenticated = isAuthenticated
-}
-
-// SetUser set user authenticated.
-func (a *UsernamePasswordCredential) SetUser(user user.User) {
-	a.user = user
-}
-
-// GetUser return authenticated.
-func (a *UsernamePasswordCredential) GetUser() user.User {
-	return a.user
-}
diff --git a/authentication/credential/username_password_credential_test.go b/authentication/credential/username_password_credential_test.go
deleted file mode 100644
index a84183c..0000000
--- a/authentication/credential/username_password_credential_test.go
+++ /dev/null
@@ -1,30 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package credential
-
-import (
-	"testing"
-
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestNewUsernamePasswordCredential(t *testing.T) {
-	a := NewUsernamePasswordCredential("my-login", "my-password")
-
-	assert.Equal(t, "my-login", a.GetPrincipal())
-
-	assert.Equal(t, "my-password", a.GetCredentials())
-
-	assert.False(t, a.IsAuthenticated())
-
-	userMock := &user.MockUser{}
-
-	a.SetAuthenticated(true)
-	a.SetUser(userMock)
-
-	assert.True(t, a.IsAuthenticated())
-	assert.Equal(t, userMock, a.GetUser())
-}
diff --git a/authentication/filter.go b/authentication/filter.go
deleted file mode 100644
index d9bb8df..0000000
--- a/authentication/filter.go
+++ /dev/null
@@ -1,12 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import "net/http"
-
-// Filter interface.
-type Filter interface {
-	OnFilter(r *http.Request) *http.Request
-}
diff --git a/authentication/filter_handler.go b/authentication/filter_handler.go
deleted file mode 100644
index 3f57ea3..0000000
--- a/authentication/filter_handler.go
+++ /dev/null
@@ -1,30 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-)
-
-// FilterHandler apply filters to http requests.
-func FilterHandler(filters ...Filter) func(next http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			for _, filter := range filters {
-				r = filter.OnFilter(r)
-
-				if token := credential.FromContext(r.Context()); token != nil {
-					next.ServeHTTP(w, r)
-
-					return
-				}
-			}
-
-			next.ServeHTTP(w, r)
-		})
-	}
-}
diff --git a/authentication/filter_handler_test.go b/authentication/filter_handler_test.go
deleted file mode 100644
index b1633d4..0000000
--- a/authentication/filter_handler_test.go
+++ /dev/null
@@ -1,118 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"io"
-	"io/ioutil"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/gilcrest/alice"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestFilterHandlerWithAuthorizationBasic(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-
-		assert.IsType(t, &credential.UsernamePasswordCredential{}, auth)
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-}
-
-func TestFilterHandlerWithAuthorizationBearer(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-
-		assert.IsType(t, &credential.TokenCredential{}, auth)
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Bearer foo")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-}
-
-func TestFilterHandlerWithoutAuthorizationHeader(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-
-		assert.Nil(t, auth)
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-}
-
-func BenchmarkFilterHandler(b *testing.B) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Bearer foo")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-	)
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		middleware.ThenFunc(handler).ServeHTTP(w, req)
-	}
-}
diff --git a/authentication/handler.go b/authentication/handler.go
deleted file mode 100644
index c14c8f8..0000000
--- a/authentication/handler.go
+++ /dev/null
@@ -1,43 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-)
-
-// Handler authenticate from credential.Credential.
-func Handler(providers ...Provider) func(next http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			var err error
-
-			creds := credential.FromContext(r.Context())
-			if creds == nil {
-				next.ServeHTTP(w, r)
-
-				return
-			}
-
-			for _, provider := range providers {
-				if !provider.IsSupported(creds) {
-					continue
-				}
-
-				r, err = provider.Authenticate(r, creds)
-				if err != nil {
-					//TODO: bad creds
-					http.Error(w, "Access denied", http.StatusUnauthorized)
-
-					return
-				}
-			}
-
-			next.ServeHTTP(w, r)
-		})
-	}
-}
diff --git a/authentication/handler_test.go b/authentication/handler_test.go
deleted file mode 100644
index edb00b3..0000000
--- a/authentication/handler_test.go
+++ /dev/null
@@ -1,225 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"errors"
-	"io"
-	"io/ioutil"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/gilcrest/alice"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/mock"
-)
-
-func TestHandlerWithoutCredential(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-		assert.Nil(t, auth)
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-
-	w := httptest.NewRecorder()
-
-	authenticationProviderMock := &MockProvider{}
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-		Handler(authenticationProviderMock),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	authenticationProviderMock.AssertNotCalled(t, "IsSupported")
-	authenticationProviderMock.AssertNotCalled(t, "Authenticate")
-}
-
-func TestHandlerWithNotSupportedCredential(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-
-		assert.IsType(t, &credential.UsernamePasswordCredential{}, auth)
-
-		assert.False(t, auth.IsAuthenticated())
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	authenticationProviderMock := &MockProvider{}
-
-	authenticationProviderMock.On("IsSupported", mock.AnythingOfType("*credential.UsernamePasswordCredential")).Return(false).Once()
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-		Handler(authenticationProviderMock),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	authenticationProviderMock.AssertExpectations(t)
-	authenticationProviderMock.AssertNotCalled(t, "Authenticate")
-}
-
-func TestHandlerWithBadAuthorizationBasic(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	authenticationProviderMock := &MockProvider{}
-
-	authenticationProviderMock.On("Authenticate", mock.AnythingOfType("*http.Request"), mock.MatchedBy(func(c credential.Credential) bool {
-		if c.GetPrincipal().(string) != "foo" {
-			return false
-		}
-
-		if c.GetCredentials().(string) != "bar" {
-			return false
-		}
-
-		c.SetAuthenticated(false)
-
-		return true
-	})).Return(req, errors.New("fail"))
-
-	authenticationProviderMock.On("IsSupported", mock.AnythingOfType("*credential.UsernamePasswordCredential")).Return(true)
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-		Handler(authenticationProviderMock),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("Access denied\n"), body)
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-
-	authenticationProviderMock.AssertExpectations(t)
-}
-
-func TestHandlerWithAuthorizationBasic(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		auth := credential.FromContext(r.Context())
-
-		assert.IsType(t, &credential.UsernamePasswordCredential{}, auth)
-
-		assert.True(t, auth.IsAuthenticated())
-
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	ctx := req.Context()
-
-	creds := credential.NewUsernamePasswordCredential("foo", "bar")
-
-	creds.SetAuthenticated(true)
-
-	ctx = credential.ToContext(ctx, creds)
-
-	req = req.WithContext(ctx)
-
-	w := httptest.NewRecorder()
-
-	authenticationProviderMock := &MockProvider{}
-
-	authenticationProviderMock.On("Authenticate", mock.AnythingOfType("*http.Request"), mock.MatchedBy(func(c credential.Credential) bool {
-		if c.GetPrincipal().(string) != "foo" {
-			return false
-		}
-
-		if c.GetCredentials().(string) != "bar" {
-			return false
-		}
-
-		c.SetAuthenticated(true)
-
-		return true
-	})).Return(req, nil)
-
-	authenticationProviderMock.On("IsSupported", mock.AnythingOfType("*credential.UsernamePasswordCredential")).Return(true)
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-		Handler(authenticationProviderMock),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	authenticationProviderMock.AssertExpectations(t)
-}
-
-type TestAuthenticationProvider struct{}
-
-func (p *TestAuthenticationProvider) Authenticate(r *http.Request, creds credential.Credential) (*http.Request, error) {
-	return r, nil
-}
-
-func (p *TestAuthenticationProvider) IsSupported(creds credential.Credential) bool {
-	return true
-}
-
-func BenchmarkHandler(b *testing.B) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Bearer foo")
-
-	w := httptest.NewRecorder()
-
-	authenticationProviderMock := &TestAuthenticationProvider{}
-
-	middleware := alice.New(
-		FilterHandler(NewHTTPBasicFilter(), NewBearerFilter()),
-		Handler(authenticationProviderMock),
-	)
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		middleware.ThenFunc(handler).ServeHTTP(w, req)
-	}
-}
diff --git a/authentication/http_basic_filter.go b/authentication/http_basic_filter.go
deleted file mode 100644
index 36f2a3c..0000000
--- a/authentication/http_basic_filter.go
+++ /dev/null
@@ -1,74 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"encoding/base64"
-	"errors"
-	"fmt"
-	"net/http"
-	"strings"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/http/header"
-	"github.com/rs/zerolog"
-)
-
-var ErrBadUsernamePasswordFormat = errors.New("bad username/password format")
-
-var _ Filter = (*HTTPBasicFilter)(nil)
-
-// HTTPBasicFilter struct.
-type HTTPBasicFilter struct {
-}
-
-// NewHTTPBasicFilter constructor.
-func NewHTTPBasicFilter() Filter {
-	return &HTTPBasicFilter{}
-}
-
-func (f HTTPBasicFilter) decodeCreds(creds string) (string, string, error) {
-	c, err := base64.StdEncoding.DecodeString(creds)
-	if err != nil {
-		return "", "", fmt.Errorf("base64 decode failed: %w", err)
-	}
-
-	cs := string(c)
-	s := strings.IndexByte(cs, ':')
-
-	if s < 0 {
-		return "", "", ErrBadUsernamePasswordFormat
-	}
-
-	return cs[:s], cs[s+1:], nil
-}
-
-// OnFilter implements Filter.
-func (f *HTTPBasicFilter) OnFilter(r *http.Request) *http.Request {
-	ctx := r.Context()
-
-	log := zerolog.Ctx(ctx)
-
-	auth := r.Header.Get("Authorization")
-	if auth == "" {
-		return r
-	}
-
-	creds, ok := header.ExtractAuthorizationValue("Basic", auth)
-	if !ok {
-		return r
-	}
-
-	username, password, err := f.decodeCreds(creds)
-	if err != nil {
-		log.Error().Err(err).Msg("deocde http basic auth failed")
-
-		return r
-	}
-
-	token := credential.NewUsernamePasswordCredential(username, password)
-
-	return r.WithContext(credential.ToContext(ctx, token))
-}
diff --git a/authentication/http_basic_filter_test.go b/authentication/http_basic_filter_test.go
deleted file mode 100644
index 186a412..0000000
--- a/authentication/http_basic_filter_test.go
+++ /dev/null
@@ -1,87 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestHTTPBasicFilter(t *testing.T) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-
-	assert.IsType(t, &credential.UsernamePasswordCredential{}, auth)
-}
-
-func TestHTTPBasicFilterWithoutAuthorizationHeader(t *testing.T) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func TestHTTPBasicFilterWithBadAuthorizationType(t *testing.T) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Digest Zm9vOnBhc3M=")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func TestHTTPBasicFilterWithBadBase64(t *testing.T) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Basic YWJjZA=====")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func TestHTTPBasicFilterWithBadFormat(t *testing.T) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Basic Zm9v")
-
-	r = f.OnFilter(r)
-
-	auth := credential.FromContext(r.Context())
-	assert.Nil(t, auth)
-}
-
-func BenchmarkHTTPBasicFilter(b *testing.B) {
-	f := NewHTTPBasicFilter()
-
-	r := httptest.NewRequest(http.MethodGet, "/path", nil)
-	r.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		r = f.OnFilter(r)
-	}
-}
diff --git a/authentication/provider.go b/authentication/provider.go
deleted file mode 100644
index 60d7dc1..0000000
--- a/authentication/provider.go
+++ /dev/null
@@ -1,17 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authentication
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-)
-
-// Provider Service interface for encoding passwords.
-type Provider interface {
-	Authenticate(r *http.Request, creds credential.Credential) (*http.Request, error)
-	IsSupported(creds credential.Credential) bool
-}
diff --git a/authentication/provider/dao/dao_authentication_provider.go b/authentication/provider/dao/dao_authentication_provider.go
deleted file mode 100644
index ebe57f5..0000000
--- a/authentication/provider/dao/dao_authentication_provider.go
+++ /dev/null
@@ -1,74 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package dao
-
-import (
-	"errors"
-	"fmt"
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/password"
-	"github.com/hyperscale-stack/security/user"
-)
-
-var (
-	ErrBadAuthenticationFormat   = errors.New("bad authentication format")
-	ErrBadPassword               = errors.New("bad password")
-	ErrCredentialsMustStringType = errors.New("credentials type must string type")
-)
-
-// DaoAuthenticationProvider struct.
-type DaoAuthenticationProvider struct {
-	passwordHasher password.Hasher
-	userProvider   UserProvider
-}
-
-var _ authentication.Provider = (*DaoAuthenticationProvider)(nil)
-
-// NewDaoAuthenticationProvider constructor.
-func NewDaoAuthenticationProvider(passwordHasher password.Hasher, userProvider UserProvider) *DaoAuthenticationProvider {
-	return &DaoAuthenticationProvider{
-		passwordHasher: passwordHasher,
-		userProvider:   userProvider,
-	}
-}
-
-// IsSupported returns true if credential.Credential is supported.
-func (p *DaoAuthenticationProvider) IsSupported(creds credential.Credential) bool {
-	_, ok := creds.(*credential.UsernamePasswordCredential)
-
-	return ok
-}
-
-// Authenticate implements Provider.
-func (p *DaoAuthenticationProvider) Authenticate(r *http.Request, creds credential.Credential) (*http.Request, error) {
-	auth, ok := creds.(*credential.UsernamePasswordCredential)
-	if !ok {
-		return r, ErrBadAuthenticationFormat
-	}
-
-	u, err := p.userProvider.LoadUserByUsername(auth.GetPrincipal().(string)) // nolint:forcetypeassert
-	if err != nil {
-		return r, fmt.Errorf("user provider failed: %w", err)
-	}
-
-	//nolint:forcetypeassert
-	userPassword := auth.GetCredentials().(string)
-
-	if us, ok := interface{}(u).(user.PasswordSalt); ok {
-		userPassword = us.SaltPassword(userPassword, us.GetSalt())
-	}
-
-	if !p.passwordHasher.Verify(u.GetPassword(), userPassword) {
-		return r, ErrBadPassword
-	}
-
-	creds.SetAuthenticated(true)
-	creds.SetUser(u)
-
-	return r, nil
-}
diff --git a/authentication/provider/dao/dao_authentication_provider_test.go b/authentication/provider/dao/dao_authentication_provider_test.go
deleted file mode 100644
index 90fa8ad..0000000
--- a/authentication/provider/dao/dao_authentication_provider_test.go
+++ /dev/null
@@ -1,186 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package dao
-
-import (
-	"errors"
-	"net/http"
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/password"
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestDaoAuthenticationProvider(t *testing.T) {
-	ph := password.NewBCryptHasher(5)
-
-	hash, err := ph.Hash("bar")
-	assert.NoError(t, err)
-
-	u := &user.MockUser{}
-
-	u.On("GetPassword").Return(hash).Once()
-
-	up := &MockUserProvider{}
-
-	up.On("LoadUserByUsername", "foo").Return(u, nil).Once()
-
-	p := NewDaoAuthenticationProvider(ph, up)
-
-	c := credential.NewUsernamePasswordCredential("foo", "bar")
-
-	assert.True(t, p.IsSupported(c))
-
-	r, err := http.NewRequest(http.MethodGet, "", nil)
-	assert.NoError(t, err)
-
-	r2, err := p.Authenticate(r, c)
-	assert.NoError(t, err)
-
-	assert.Same(t, r, r2)
-
-	assert.True(t, c.IsAuthenticated())
-
-	u.AssertExpectations(t)
-
-	up.AssertExpectations(t)
-}
-
-func TestDaoAuthenticationProviderWithBadAuthentication(t *testing.T) {
-	ph := password.NewBCryptHasher(5)
-
-	hash, err := ph.Hash("bar")
-	assert.NoError(t, err)
-
-	u := &user.MockUser{}
-
-	u.On("GetPassword").Return(hash)
-
-	up := &MockUserProvider{}
-
-	up.On("LoadUserByUsername", "foo").Return(u, nil)
-
-	p := NewDaoAuthenticationProvider(ph, up)
-
-	c := credential.NewTokenCredential("foo")
-
-	assert.False(t, p.IsSupported(c))
-
-	r, err := http.NewRequest(http.MethodGet, "", nil)
-	assert.NoError(t, err)
-
-	r2, err := p.Authenticate(r, c)
-	assert.EqualError(t, err, "bad authentication format")
-
-	assert.Same(t, r, r2)
-
-	assert.False(t, c.IsAuthenticated())
-
-	u.AssertNotCalled(t, "GetPassword")
-
-	up.AssertNotCalled(t, "LoadUserByUsername")
-}
-
-func TestDaoAuthenticationProviderWithUserNotFound(t *testing.T) {
-	ph := password.NewBCryptHasher(5)
-
-	up := &MockUserProvider{}
-
-	up.On("LoadUserByUsername", "foo").Return(nil, errors.New("user not found")).Once()
-
-	p := NewDaoAuthenticationProvider(ph, up)
-
-	c := credential.NewUsernamePasswordCredential("foo", "bar")
-
-	assert.True(t, p.IsSupported(c))
-
-	r, err := http.NewRequest(http.MethodGet, "", nil)
-	assert.NoError(t, err)
-
-	r2, err := p.Authenticate(r, c)
-	assert.EqualError(t, err, "user provider failed: user not found")
-
-	assert.Same(t, r, r2)
-
-	assert.False(t, c.IsAuthenticated())
-
-	up.AssertExpectations(t)
-}
-
-func TestDaoAuthenticationProviderWithBadPassword(t *testing.T) {
-	ph := password.NewBCryptHasher(5)
-
-	hash, err := ph.Hash("bar")
-	assert.NoError(t, err)
-
-	u := &user.MockUser{}
-
-	u.On("GetPassword").Return(hash).Once()
-
-	up := &MockUserProvider{}
-
-	up.On("LoadUserByUsername", "foo").Return(u, nil).Once()
-
-	p := NewDaoAuthenticationProvider(ph, up)
-
-	c := credential.NewUsernamePasswordCredential("foo", "bad")
-
-	assert.True(t, p.IsSupported(c))
-
-	r, err := http.NewRequest(http.MethodGet, "", nil)
-	assert.NoError(t, err)
-
-	r2, err := p.Authenticate(r, c)
-	assert.EqualError(t, err, "bad password")
-
-	assert.Same(t, r, r2)
-
-	assert.False(t, c.IsAuthenticated())
-
-	u.AssertExpectations(t)
-
-	up.AssertExpectations(t)
-}
-
-func TestDaoAuthenticationProviderWithUserPasswordSalt(t *testing.T) {
-	ph := password.NewBCryptHasher(5)
-
-	hash, err := ph.Hash("bar:$Oo$")
-	assert.NoError(t, err)
-
-	u := &user.MockUserPasswordSalt{}
-
-	u.On("GetPassword").Return(hash).Once()
-
-	u.On("GetSalt").Return("$Oo$").Once()
-
-	u.On("SaltPassword", "bar", "$Oo$").Return("bar:$Oo$").Once()
-
-	up := &MockUserProvider{}
-
-	up.On("LoadUserByUsername", "foo").Return(u, nil)
-
-	p := NewDaoAuthenticationProvider(ph, up)
-
-	c := credential.NewUsernamePasswordCredential("foo", "bar")
-
-	assert.True(t, p.IsSupported(c))
-
-	r, err := http.NewRequest(http.MethodGet, "", nil)
-	assert.NoError(t, err)
-
-	r2, err := p.Authenticate(r, c)
-	assert.NoError(t, err)
-
-	assert.Same(t, r, r2)
-
-	assert.True(t, c.IsAuthenticated())
-
-	u.AssertExpectations(t)
-
-	up.AssertExpectations(t)
-}
diff --git a/authentication/provider/dao/user_provider.go b/authentication/provider/dao/user_provider.go
deleted file mode 100644
index ccd8cd6..0000000
--- a/authentication/provider/dao/user_provider.go
+++ /dev/null
@@ -1,12 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package dao
-
-import "github.com/hyperscale-stack/security/user"
-
-// UserProvider interface which loads user-specific data.
-type UserProvider interface {
-	LoadUserByUsername(username string) (user.User, error)
-}
diff --git a/authentication/provider/oauth2/access.go b/authentication/provider/oauth2/access.go
deleted file mode 100644
index 864b017..0000000
--- a/authentication/provider/oauth2/access.go
+++ /dev/null
@@ -1,81 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"context"
-	"time"
-)
-
-type AccessToken interface {
-	GetClient() Client
-	GetToken() string
-	IsExpired() bool
-	GetUserID() string
-}
-
-type accessCtxKey struct{}
-
-// AccessTokenFromContext returns the Access Token info associated with the ctx.
-func AccessTokenFromContext(ctx context.Context) *AccessInfo {
-	if a, ok := ctx.Value(accessCtxKey{}).(*AccessInfo); ok {
-		return a
-	}
-
-	return nil
-}
-
-// AccessTokenToContext returns new context with Access Token info.
-func AccessTokenToContext(ctx context.Context, access *AccessInfo) context.Context {
-	return context.WithValue(ctx, accessCtxKey{}, access)
-}
-
-// AccessInfo represents an access grant (tokens, expiration, client, etc).
-type AccessInfo struct {
-	// Client information
-	Client Client
-
-	// Authorize data, for authorization code
-	AuthorizeData *AuthorizeInfo
-
-	// Previous access data, for refresh token
-	AccessInfo *AccessInfo
-
-	// Access token
-	AccessToken string
-
-	// Refresh Token. Can be blank
-	RefreshToken string
-
-	// Token expiration in seconds
-	ExpiresIn int32
-
-	// Requested scope
-	Scope string
-
-	// Redirect URI from request
-	RedirectURI string
-
-	// Date created
-	CreatedAt time.Time
-
-	// Data to be passed to storage. Not used by the library.
-	UserData interface{}
-}
-
-// IsExpired returns true if access expired.
-func (i *AccessInfo) IsExpired() bool {
-	return i.IsExpiredAt(time.Now())
-}
-
-// IsExpiredAt returns true if access expires at time 't'.
-func (i *AccessInfo) IsExpiredAt(t time.Time) bool {
-	return i.ExpireAt().Before(t)
-}
-
-// ExpireAt returns the expiration date.
-func (i *AccessInfo) ExpireAt() time.Time {
-	return i.CreatedAt.Add(time.Duration(i.ExpiresIn) * time.Second)
-}
diff --git a/authentication/provider/oauth2/access_test.go b/authentication/provider/oauth2/access_test.go
deleted file mode 100644
index 2b2e584..0000000
--- a/authentication/provider/oauth2/access_test.go
+++ /dev/null
@@ -1,48 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestAccessInfo(t *testing.T) {
-	cat, err := time.Parse("2006-01-02T15:04:05.000Z", "2014-11-12T11:45:26.371Z")
-	assert.NoError(t, err)
-
-	ai := &AccessInfo{
-		CreatedAt: cat,
-		ExpiresIn: 10,
-	}
-
-	assert.True(t, ai.IsExpired())
-}
-
-func TestAccessTokenContext(t *testing.T) {
-	ctx := context.Background()
-
-	ai := &AccessInfo{
-		CreatedAt: time.Now(),
-		ExpiresIn: 10,
-	}
-
-	ctx = AccessTokenToContext(ctx, ai)
-
-	ai2 := AccessTokenFromContext(ctx)
-
-	assert.Equal(t, ai, ai2)
-}
-
-func TestFromContextWithEmptyContext(t *testing.T) {
-	ctx := context.Background()
-
-	ai := AccessTokenFromContext(ctx)
-
-	assert.Nil(t, ai)
-}
diff --git a/authentication/provider/oauth2/authorize.go b/authentication/provider/oauth2/authorize.go
deleted file mode 100644
index 4da0dad..0000000
--- a/authentication/provider/oauth2/authorize.go
+++ /dev/null
@@ -1,55 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import "time"
-
-// AuthorizeInfo info.
-type AuthorizeInfo struct {
-	// Client information
-	Client Client
-
-	// Authorization code
-	Code string
-
-	// Token expiration in seconds
-	ExpiresIn int32
-
-	// Requested scope
-	Scope string
-
-	// Redirect Uri from request
-	RedirectURI string
-
-	// State data from request
-	State string
-
-	// Date created
-	CreatedAt time.Time
-
-	// Data to be passed to storage. Not used by the library.
-	UserData interface{}
-
-	// Optional code_challenge as described in rfc7636
-	CodeChallenge string
-
-	// Optional code_challenge_method as described in rfc7636
-	CodeChallengeMethod string
-}
-
-// IsExpired is true if authorization expired.
-func (i *AuthorizeInfo) IsExpired() bool {
-	return i.IsExpiredAt(time.Now())
-}
-
-// IsExpired is true if authorization expires at time 't'.
-func (i *AuthorizeInfo) IsExpiredAt(t time.Time) bool {
-	return i.ExpireAt().Before(t)
-}
-
-// ExpireAt returns the expiration date.
-func (i *AuthorizeInfo) ExpireAt() time.Time {
-	return i.CreatedAt.Add(time.Duration(i.ExpiresIn) * time.Second)
-}
diff --git a/authentication/provider/oauth2/authorize_test.go b/authentication/provider/oauth2/authorize_test.go
deleted file mode 100644
index 8a15920..0000000
--- a/authentication/provider/oauth2/authorize_test.go
+++ /dev/null
@@ -1,24 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestAuthorizeInfo(t *testing.T) {
-	cat, err := time.Parse("2006-01-02T15:04:05.000Z", "2014-11-12T11:45:26.371Z")
-	assert.NoError(t, err)
-
-	ai := &AuthorizeInfo{
-		CreatedAt: cat,
-		ExpiresIn: 10,
-	}
-
-	assert.True(t, ai.IsExpired())
-}
diff --git a/authentication/provider/oauth2/client.go b/authentication/provider/oauth2/client.go
deleted file mode 100644
index 89ab235..0000000
--- a/authentication/provider/oauth2/client.go
+++ /dev/null
@@ -1,87 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"context"
-	"crypto/subtle"
-)
-
-type clientCtxKey struct{}
-
-// ClientFromContext returns the Client associated with the ctx.
-func ClientFromContext(ctx context.Context) Client {
-	if c, ok := ctx.Value(clientCtxKey{}).(Client); ok {
-		return c
-	}
-
-	return nil
-}
-
-// ClientToContext returns new context with Client.
-func ClientToContext(ctx context.Context, client Client) context.Context {
-	return context.WithValue(ctx, clientCtxKey{}, client)
-}
-
-// Client information.
-type Client interface {
-	// Client ID
-	GetID() string
-
-	// Client secret
-	GetSecret() string
-
-	// Base client URI
-	GetRedirectURI() string
-
-	// Data to be passed to storage. Not used by the library.
-	GetUserData() interface{}
-}
-
-// ClientSecretMatcher is an optional interface clients can implement
-// which allows them to be the one to determine if a secret matches.
-// If a Client implements ClientSecretMatcher, the framework will never call GetSecret.
-type ClientSecretMatcher interface {
-	// SecretMatches returns true if the given secret matches
-	SecretMatches(secret string) bool
-}
-
-var _ ClientSecretMatcher = (*DefaultClient)(nil)
-
-// DefaultClient stores all data in struct variables.
-type DefaultClient struct {
-	ID          string
-	Secret      string
-	RedirectURI string
-	UserData    interface{}
-}
-
-func (d *DefaultClient) GetID() string {
-	return d.ID
-}
-
-func (d *DefaultClient) GetSecret() string {
-	return d.Secret
-}
-
-func (d *DefaultClient) GetRedirectURI() string {
-	return d.RedirectURI
-}
-
-func (d *DefaultClient) GetUserData() interface{} {
-	return d.UserData
-}
-
-// Implement the ClientSecretMatcher interface.
-func (d *DefaultClient) SecretMatches(secret string) bool {
-	return subtle.ConstantTimeCompare([]byte(d.Secret), []byte(secret)) == 1
-}
-
-func (d *DefaultClient) CopyFrom(client Client) {
-	d.ID = client.GetID()
-	d.Secret = client.GetSecret()
-	d.RedirectURI = client.GetRedirectURI()
-	d.UserData = client.GetUserData()
-}
diff --git a/authentication/provider/oauth2/client_test.go b/authentication/provider/oauth2/client_test.go
deleted file mode 100644
index fe4d935..0000000
--- a/authentication/provider/oauth2/client_test.go
+++ /dev/null
@@ -1,63 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestDefaultClient(t *testing.T) {
-	dc := &DefaultClient{
-		ID:          "01c1c799-81a8-4bd0-9998-c6abae3cc473",
-		Secret:      "MfpCIRnFcwA5GiKPtAMZdXb2ayehhEj9",
-		RedirectURI: "https://connect.myservice.tld/",
-		UserData:    "foo",
-	}
-
-	assert.Equal(t, "01c1c799-81a8-4bd0-9998-c6abae3cc473", dc.GetID())
-	assert.Equal(t, "MfpCIRnFcwA5GiKPtAMZdXb2ayehhEj9", dc.GetSecret())
-	assert.Equal(t, "https://connect.myservice.tld/", dc.GetRedirectURI())
-	assert.Equal(t, "foo", dc.GetUserData())
-	assert.True(t, dc.SecretMatches("MfpCIRnFcwA5GiKPtAMZdXb2ayehhEj9"))
-
-	dc1 := &DefaultClient{}
-
-	dc1.CopyFrom(dc)
-
-	assert.Equal(t, dc.GetID(), dc1.GetID())
-	assert.Equal(t, dc.GetSecret(), dc1.GetSecret())
-	assert.Equal(t, dc.GetRedirectURI(), dc1.GetRedirectURI())
-	assert.Equal(t, dc.GetUserData(), dc1.GetUserData())
-	assert.True(t, dc1.SecretMatches(dc.GetSecret()))
-
-}
-
-func TestClientContext(t *testing.T) {
-	ctx := context.Background()
-
-	dc := &DefaultClient{
-		ID:          "01c1c799-81a8-4bd0-9998-c6abae3cc473",
-		Secret:      "MfpCIRnFcwA5GiKPtAMZdXb2ayehhEj9",
-		RedirectURI: "https://connect.myservice.tld/",
-		UserData:    "foo",
-	}
-
-	ctx = ClientToContext(ctx, dc)
-
-	dc2 := ClientFromContext(ctx)
-
-	assert.Equal(t, dc, dc2)
-}
-
-func TestClientFromContextWithEmptyContext(t *testing.T) {
-	ctx := context.Background()
-
-	dc := ClientFromContext(ctx)
-
-	assert.Nil(t, dc)
-}
diff --git a/authentication/provider/oauth2/oauth2_authentication_provider.go b/authentication/provider/oauth2/oauth2_authentication_provider.go
deleted file mode 100644
index f8ba1e4..0000000
--- a/authentication/provider/oauth2/oauth2_authentication_provider.go
+++ /dev/null
@@ -1,126 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"errors"
-	"fmt"
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token"
-)
-
-var (
-	ErrBadAuthenticationFormat = errors.New("bad authentication format")
-	ErrTokenExpired            = errors.New("token expired")
-	ErrBadTypeForUserData      = errors.New("bad type for user data")
-)
-
-// OAuth2AuthenticationProvider struct.
-type OAuth2AuthenticationProvider struct {
-	tokenGenerator   token.Generator
-	userStorage      UserProvider
-	clientStorage    ClientProvider
-	accessStorage    AccessProvider
-	refreshStorage   RefreshProvider
-	authorizeStorage AuthorizeProvider
-}
-
-var _ authentication.Provider = (*OAuth2AuthenticationProvider)(nil)
-
-// NewOAuth2AuthenticationProvider constructor.
-func NewOAuth2AuthenticationProvider(
-	tokenGenerator token.Generator,
-	userStorage UserProvider,
-	clientStorage ClientProvider,
-	accessStorage AccessProvider,
-	refreshStorage RefreshProvider,
-	authorizeStorage AuthorizeProvider,
-) *OAuth2AuthenticationProvider {
-	return &OAuth2AuthenticationProvider{
-		userStorage:      userStorage,
-		tokenGenerator:   tokenGenerator,
-		clientStorage:    clientStorage,
-		accessStorage:    accessStorage,
-		refreshStorage:   refreshStorage,
-		authorizeStorage: authorizeStorage,
-	}
-}
-
-// IsSupported returns true if credential.Credential is supported.
-func (p *OAuth2AuthenticationProvider) IsSupported(creds credential.Credential) bool {
-	// TODO multiple support (ClientCreds, etc...)
-	switch creds.(type) {
-	case *credential.TokenCredential, *credential.UsernamePasswordCredential:
-		return true
-	default:
-		return false
-	}
-}
-
-func (p *OAuth2AuthenticationProvider) authenticateByToken(r *http.Request, creds *credential.TokenCredential) (*http.Request, error) {
-	ctx := r.Context()
-
-	token, err := p.accessStorage.LoadAccess(creds.GetPrincipal().(string)) // nolint:forcetypeassert
-	if err != nil {
-		return r, fmt.Errorf("load access token failed: %w", err)
-	}
-
-	if token.IsExpired() {
-		return r, ErrTokenExpired
-	}
-
-	userID, ok := token.UserData.(string)
-	if !ok {
-		return r, ErrBadTypeForUserData
-	}
-
-	u, err := p.userStorage.LoadUser(userID)
-	if err != nil {
-		return r, fmt.Errorf("load user failed: %w", err)
-	}
-
-	creds.SetAuthenticated(true)
-	creds.SetUser(u)
-
-	ctx = AccessTokenToContext(ctx, token)
-	ctx = ClientToContext(ctx, token.Client)
-
-	return r.WithContext(ctx), nil
-}
-
-func (p *OAuth2AuthenticationProvider) authenticateByClient(r *http.Request, creds *credential.UsernamePasswordCredential) (*http.Request, error) {
-	ctx := r.Context()
-
-	client, err := p.clientStorage.LoadClient(creds.GetPrincipal().(string)) // nolint:forcetypeassert
-	if err != nil {
-		return r, fmt.Errorf("load client info failed: %w", err)
-	}
-
-	if c, ok := client.(ClientSecretMatcher); ok {
-		// nolint:forcetypeassert
-		if c.SecretMatches(creds.GetCredentials().(string)) {
-			creds.SetAuthenticated(true)
-		}
-	}
-
-	ctx = ClientToContext(ctx, client)
-
-	return r.WithContext(ctx), nil
-}
-
-// Authenticate implements Provider.
-func (p *OAuth2AuthenticationProvider) Authenticate(r *http.Request, creds credential.Credential) (*http.Request, error) {
-	switch auth := creds.(type) {
-	case *credential.TokenCredential:
-		return p.authenticateByToken(r, auth)
-	case *credential.UsernamePasswordCredential: // @TODO: use ClientCredential
-		return p.authenticateByClient(r, auth)
-	default:
-		return r, ErrBadAuthenticationFormat
-	}
-}
diff --git a/authentication/provider/oauth2/oauth2_authentication_provider_test.go b/authentication/provider/oauth2/oauth2_authentication_provider_test.go
deleted file mode 100644
index 34c99d3..0000000
--- a/authentication/provider/oauth2/oauth2_authentication_provider_test.go
+++ /dev/null
@@ -1,308 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"net/http/httptest"
-	"testing"
-	"time"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token/random"
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-// BadCredential struct.
-type BadCredential struct {
-	isAuthenticated bool
-	credentials     interface{}
-	principal       interface{}
-	user            user.User
-}
-
-var _ credential.Credential = (*BadCredential)(nil)
-
-// GetCredentials that prove the principal is correct, this is usually a password.
-func (a *BadCredential) GetCredentials() interface{} {
-	return a.credentials
-}
-
-// GetPrincipal The identity of the principal being authenticated.
-// In the case of an authentication request with username and password,
-// this would be the username.
-func (a *BadCredential) GetPrincipal() interface{} {
-	return a.principal
-}
-
-// IsAuthenticated returns true if token is authenticated.
-func (a *BadCredential) IsAuthenticated() bool {
-	return a.isAuthenticated
-}
-
-// SetAuthenticated change token to authenticated.
-func (a *BadCredential) SetAuthenticated(isAuthenticated bool) {
-	a.isAuthenticated = isAuthenticated
-}
-
-// SetUser set user authenticated.
-func (a *BadCredential) SetUser(user user.User) {
-	a.user = user
-}
-
-// GetUser return authenticated.
-func (a *BadCredential) GetUser() user.User {
-	return a.user
-}
-
-func TestOAuth2AuthenticationProviderIsSupported(t *testing.T) {
-	p := &OAuth2AuthenticationProvider{}
-
-	{
-		creds := &credential.TokenCredential{}
-
-		assert.True(t, p.IsSupported(creds))
-	}
-
-	{
-		creds := &credential.UsernamePasswordCredential{}
-
-		assert.True(t, p.IsSupported(creds))
-	}
-
-	{
-		creds := &BadCredential{}
-
-		assert.False(t, p.IsSupported(creds))
-	}
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByClient(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	clientStorageMock := &MockClientProvider{}
-
-	client := &DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	clientStorageMock.On("LoadClient", "5cc06c3b-5755-4229-958c-a515a245aaeb").Return(client, nil)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, nil, clientStorageMock, nil, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewUsernamePasswordCredential("5cc06c3b-5755-4229-958c-a515a245aaeb", "WTvuAztPD2XBauomleRzGFYuZawS07Ym")
-
-	r, err := p.Authenticate(req, creds)
-	assert.NoError(t, err)
-
-	assert.NotNil(t, r.Context())
-
-	clientStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByClientWithClientNotFound(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	clientStorageMock := &MockClientProvider{}
-
-	clientStorageMock.On("LoadClient", "bad").Return(nil, ErrClientNotFound)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, nil, clientStorageMock, nil, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewUsernamePasswordCredential("bad", "bad")
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "load client info failed: oauth2 client not found")
-
-	assert.Same(t, req, r)
-
-	clientStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByAccessTokenWithTokenNotFound(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	accessStorageMock := &MockAccessProvider{}
-
-	accessStorageMock.On("LoadAccess", "bad").Return(nil, ErrAccessNotFound)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, nil, nil, accessStorageMock, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewTokenCredential("bad")
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "load access token failed: oauth2 access token not found")
-
-	assert.Same(t, req, r)
-
-	accessStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByAccessTokenWithTokenExpired(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userMock := &user.MockUser{}
-
-	accessStorageMock := &MockAccessProvider{}
-
-	access := &AccessInfo{
-		AccessToken: "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR",
-		ExpiresIn:   60,
-		UserData:    userMock,
-	}
-
-	accessStorageMock.On("LoadAccess", "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR").Return(access, nil)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, nil, nil, accessStorageMock, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewTokenCredential("wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR")
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "token expired")
-
-	assert.Same(t, req, r)
-
-	accessStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByAccessTokenWithUserNotFound(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userStorageMock := &MockUserProvider{}
-
-	userStorageMock.On("LoadUser", "8c87a032-755d-42f6-be96-0421948f6e94").Return(nil, ErrUserNotFound)
-
-	accessStorageMock := &MockAccessProvider{}
-
-	access := &AccessInfo{
-		AccessToken: "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR",
-		ExpiresIn:   60,
-		CreatedAt:   time.Now(),
-		UserData:    "8c87a032-755d-42f6-be96-0421948f6e94",
-	}
-
-	accessStorageMock.On("LoadAccess", "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR").Return(access, nil)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, userStorageMock, nil, accessStorageMock, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewTokenCredential("wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR")
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "load user failed: oauth2 user not found")
-
-	assert.Same(t, req, r)
-
-	accessStorageMock.AssertExpectations(t)
-	userStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByAccessTokenWithToken(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userMock := &user.MockUser{}
-
-	userStorageMock := &MockUserProvider{}
-
-	userStorageMock.On("LoadUser", "8c87a032-755d-42f6-be96-0421948f6e94").Return(userMock, nil)
-
-	accessStorageMock := &MockAccessProvider{}
-
-	client := &DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	access := &AccessInfo{
-		Client:      client,
-		AccessToken: "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR",
-		ExpiresIn:   60,
-		CreatedAt:   time.Now(),
-		UserData:    "8c87a032-755d-42f6-be96-0421948f6e94",
-	}
-
-	accessStorageMock.On("LoadAccess", "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR").Return(access, nil)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, userStorageMock, nil, accessStorageMock, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewTokenCredential("wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR")
-
-	r, err := p.Authenticate(req, creds)
-	assert.NoError(t, err)
-
-	assert.NotNil(t, r.Context())
-
-	accessStorageMock.AssertExpectations(t)
-	userStorageMock.AssertExpectations(t)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateWithBadCredentialType(t *testing.T) {
-	creds := &BadCredential{}
-
-	p := NewOAuth2AuthenticationProvider(nil, nil, nil, nil, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "bad authentication format")
-
-	assert.Same(t, req, r)
-}
-
-func TestOAuth2AuthenticationProviderAuthenticateByAccessTokenWithBadUserDataType(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userMock := &user.MockUser{}
-
-	userStorageMock := &MockUserProvider{}
-
-	userStorageMock.On("LoadUser", "8c87a032-755d-42f6-be96-0421948f6e94").Return(userMock, nil)
-
-	accessStorageMock := &MockAccessProvider{}
-
-	client := &DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	access := &AccessInfo{
-		Client:      client,
-		AccessToken: "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR",
-		ExpiresIn:   60,
-		CreatedAt:   time.Now(),
-		UserData:    12345,
-	}
-
-	accessStorageMock.On("LoadAccess", "wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR").Return(access, nil)
-
-	p := NewOAuth2AuthenticationProvider(tokenGenerator, userStorageMock, nil, accessStorageMock, nil, nil)
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-
-	creds := credential.NewTokenCredential("wSxJOjDWo7qQ7kF5Tlg2l9XZYat6gq6GssF5D5I9aKtcEipJzoTba77vRhfscn1vNr0gBM9rSj5sZ3R6252FTlJpxWPUM1c8w2KkvaAAcyrWqNPVNNFX2qAxhpcatdbR")
-
-	r, err := p.Authenticate(req, creds)
-	assert.EqualError(t, err, "bad type for user data")
-
-	assert.NotNil(t, r.Context())
-
-	accessStorageMock.AssertExpectations(t)
-	userStorageMock.AssertNotCalled(t, "LoadUser")
-}
diff --git a/authentication/provider/oauth2/storage.go b/authentication/provider/oauth2/storage.go
deleted file mode 100644
index f28302e..0000000
--- a/authentication/provider/oauth2/storage.go
+++ /dev/null
@@ -1,54 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package oauth2
-
-import (
-	"errors"
-
-	"github.com/hyperscale-stack/security/user"
-)
-
-var (
-	ErrClientNotFound    = errors.New("oauth2 client not found")
-	ErrAccessNotFound    = errors.New("oauth2 access token not found")
-	ErrRefreshNotFound   = errors.New("oauth2 refresh token not found")
-	ErrAuthorizeNotFound = errors.New("oauth2 authorize code not found")
-	ErrUserNotFound      = errors.New("oauth2 user not found")
-)
-
-type ClientProvider interface {
-	SaveClient(Client) error
-	LoadClient(id string) (Client, error)
-	RemoveClient(id string) error
-}
-
-type AccessProvider interface {
-	SaveAccess(*AccessInfo) error
-	LoadAccess(token string) (*AccessInfo, error)
-	RemoveAccess(token string) error
-}
-
-type RefreshProvider interface {
-	SaveRefresh(*AccessInfo) error
-	LoadRefresh(token string) (*AccessInfo, error)
-	RemoveRefresh(token string) error
-}
-
-type AuthorizeProvider interface {
-	SaveAuthorize(*AuthorizeInfo) error
-	LoadAuthorize(code string) (*AuthorizeInfo, error)
-	RemoveAuthorize(code string) error
-}
-
-type UserProvider interface {
-	LoadUser(id string) (user.User, error)
-}
-
-type StorageProvider interface {
-	ClientProvider
-	AccessProvider
-	RefreshProvider
-	AuthorizeProvider
-}
diff --git a/authentication/provider/oauth2/storage/in_memory_storage.go b/authentication/provider/oauth2/storage/in_memory_storage.go
deleted file mode 100644
index 6f81a72..0000000
--- a/authentication/provider/oauth2/storage/in_memory_storage.go
+++ /dev/null
@@ -1,104 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package storage
-
-import (
-	"sync"
-
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2"
-)
-
-var _ oauth2.StorageProvider = (*InMemoryStorage)(nil)
-
-type InMemoryStorage struct {
-	clients    sync.Map
-	accesses   sync.Map
-	refreshs   sync.Map
-	authorizes sync.Map
-}
-
-func NewInMemoryStorage() *InMemoryStorage {
-	return &InMemoryStorage{}
-}
-
-func (s *InMemoryStorage) SaveClient(client oauth2.Client) error {
-	s.clients.Store(client.GetID(), client)
-
-	return nil
-}
-
-func (s *InMemoryStorage) LoadClient(id string) (oauth2.Client, error) {
-	if client, ok := s.clients.Load(id); ok {
-		return client.(oauth2.Client), nil // nolint:forcetypeassert
-	}
-
-	return nil, oauth2.ErrClientNotFound
-}
-
-func (s *InMemoryStorage) RemoveClient(id string) error {
-	s.clients.Delete(id)
-
-	return nil
-}
-
-func (s *InMemoryStorage) SaveAccess(access *oauth2.AccessInfo) error {
-	s.accesses.Store(access.AccessToken, access)
-
-	return nil
-}
-
-func (s *InMemoryStorage) LoadAccess(token string) (*oauth2.AccessInfo, error) {
-	if access, ok := s.accesses.Load(token); ok {
-		return access.(*oauth2.AccessInfo), nil // nolint:forcetypeassert
-	}
-
-	return nil, oauth2.ErrAccessNotFound
-}
-
-func (s *InMemoryStorage) RemoveAccess(token string) error {
-	s.accesses.Delete(token)
-
-	return nil
-}
-
-func (s *InMemoryStorage) SaveRefresh(access *oauth2.AccessInfo) error {
-	s.refreshs.Store(access.RefreshToken, access)
-
-	return nil
-}
-
-func (s *InMemoryStorage) LoadRefresh(token string) (*oauth2.AccessInfo, error) {
-	if access, ok := s.refreshs.Load(token); ok {
-		return access.(*oauth2.AccessInfo), nil // nolint:forcetypeassert
-	}
-
-	return nil, oauth2.ErrRefreshNotFound
-}
-
-func (s *InMemoryStorage) RemoveRefresh(token string) error {
-	s.refreshs.Delete(token)
-
-	return nil
-}
-
-func (s *InMemoryStorage) SaveAuthorize(authorize *oauth2.AuthorizeInfo) error {
-	s.authorizes.Store(authorize.Code, authorize)
-
-	return nil
-}
-
-func (s *InMemoryStorage) LoadAuthorize(code string) (*oauth2.AuthorizeInfo, error) {
-	if authorize, ok := s.authorizes.Load(code); ok {
-		return authorize.(*oauth2.AuthorizeInfo), nil // nolint:forcetypeassert
-	}
-
-	return nil, oauth2.ErrAuthorizeNotFound
-}
-
-func (s *InMemoryStorage) RemoveAuthorize(code string) error {
-	s.authorizes.Delete(code)
-
-	return nil
-}
diff --git a/authentication/provider/oauth2/storage/in_memory_storage_test.go b/authentication/provider/oauth2/storage/in_memory_storage_test.go
deleted file mode 100644
index 97cdd7e..0000000
--- a/authentication/provider/oauth2/storage/in_memory_storage_test.go
+++ /dev/null
@@ -1,110 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package storage
-
-import (
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestInMemoryStorage(t *testing.T) {
-	s := NewInMemoryStorage()
-
-	client := &oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	// Client
-	client2, err := s.LoadClient(client.ID)
-	assert.EqualError(t, err, oauth2.ErrClientNotFound.Error())
-	assert.Nil(t, client2)
-
-	err = s.SaveClient(client)
-	assert.NoError(t, err)
-
-	client2, err = s.LoadClient(client.ID)
-	assert.NoError(t, err)
-	assert.Same(t, client, client2)
-
-	err = s.RemoveClient(client.ID)
-	assert.NoError(t, err)
-
-	client2, err = s.LoadClient(client.ID)
-	assert.EqualError(t, err, oauth2.ErrClientNotFound.Error())
-	assert.Nil(t, client2)
-
-	// Access Token
-	access := &oauth2.AccessInfo{
-		AccessToken: "OKjQ0VjYmJxP8N0TzXH5lxvIOZj4bCM0DlsCvuiL96HCQEhJ8A9ozY8jJ5Ep38vaVvn082fgApThX7NZ7pktKn57A667kEeWLPW0KVA3x1flYdBvkIvHOAZYyvUeKK9q",
-	}
-
-	access2, err := s.LoadAccess(access.AccessToken)
-	assert.EqualError(t, err, oauth2.ErrAccessNotFound.Error())
-	assert.Nil(t, access2)
-
-	err = s.SaveAccess(access)
-	assert.NoError(t, err)
-
-	access2, err = s.LoadAccess(access.AccessToken)
-	assert.NoError(t, err)
-	assert.Same(t, access, access2)
-
-	err = s.RemoveAccess(access.AccessToken)
-	assert.NoError(t, err)
-
-	access2, err = s.LoadAccess(access.AccessToken)
-	assert.EqualError(t, err, oauth2.ErrAccessNotFound.Error())
-	assert.Nil(t, access2)
-
-	// Refresh Token
-	access = &oauth2.AccessInfo{
-		RefreshToken: "2oQDkOWnbqtJoEs24MkVEB4WNJnqyoAIErvSJRhjg562K8GznWLbLZuStQodKvReSedAqufswaSZduhlgOuCNcQj9aGbCKPAnXUVvmX7Vmgvryp9PaZVbuqj0HfzN9tD",
-	}
-
-	access2, err = s.LoadRefresh(access.RefreshToken)
-	assert.EqualError(t, err, oauth2.ErrRefreshNotFound.Error())
-	assert.Nil(t, access2)
-
-	err = s.SaveRefresh(access)
-	assert.NoError(t, err)
-
-	access2, err = s.LoadRefresh(access.RefreshToken)
-	assert.NoError(t, err)
-	assert.Same(t, access, access2)
-
-	err = s.RemoveRefresh(access.RefreshToken)
-	assert.NoError(t, err)
-
-	access2, err = s.LoadRefresh(access.RefreshToken)
-	assert.EqualError(t, err, oauth2.ErrRefreshNotFound.Error())
-	assert.Nil(t, access2)
-
-	// Authorize Code
-	authorize := &oauth2.AuthorizeInfo{
-		Code: "Je4dJ5RFPRJwuSmuitSo8tX7s3uFOP84sEufxjdqJhiiPABdbxeGofGvvX7LBdvy2ZrwDZy3a6cOF8vgquUlr8yAvA9VpDz4Kv2bZxm0WEl4y3SJSvYPnwBOxRHI5pxK",
-	}
-
-	authorize2, err := s.LoadAuthorize(authorize.Code)
-	assert.EqualError(t, err, oauth2.ErrAuthorizeNotFound.Error())
-	assert.Nil(t, authorize2)
-
-	err = s.SaveAuthorize(authorize)
-	assert.NoError(t, err)
-
-	authorize2, err = s.LoadAuthorize(authorize.Code)
-	assert.NoError(t, err)
-	assert.Same(t, authorize, authorize2)
-
-	err = s.RemoveAuthorize(authorize.Code)
-	assert.NoError(t, err)
-
-	authorize2, err = s.LoadAuthorize(authorize.Code)
-	assert.EqualError(t, err, oauth2.ErrAuthorizeNotFound.Error())
-	assert.Nil(t, authorize2)
-}
diff --git a/authentication/provider/oauth2/token/generator.go b/authentication/provider/oauth2/token/generator.go
deleted file mode 100644
index cd39ec9..0000000
--- a/authentication/provider/oauth2/token/generator.go
+++ /dev/null
@@ -1,9 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package token
-
-type Generator interface {
-	GenerateAccessToken(generateRefresh bool) (accessToken string, refreshToken string, err error)
-}
diff --git a/authentication/provider/oauth2/token/random/configuration.go b/authentication/provider/oauth2/token/random/configuration.go
deleted file mode 100644
index d26987f..0000000
--- a/authentication/provider/oauth2/token/random/configuration.go
+++ /dev/null
@@ -1,11 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package random
-
-// Configuration struct.
-type Configuration struct {
-	AccessTokenSize  int `mapstructure:"access_token_size"`
-	RefreshTokenSize int `mapstructure:"refresh_token_size"`
-}
diff --git a/authentication/provider/oauth2/token/random/token_generator.go b/authentication/provider/oauth2/token/random/token_generator.go
deleted file mode 100644
index f0de492..0000000
--- a/authentication/provider/oauth2/token/random/token_generator.go
+++ /dev/null
@@ -1,40 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package random
-
-import (
-	"github.com/hyperscale-stack/secure"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token"
-)
-
-var _ token.Generator = (*TokenGenerator)(nil)
-
-type TokenGenerator struct {
-	cfg *Configuration
-}
-
-func NewTokenGenerator(cfg *Configuration) token.Generator {
-	if cfg.AccessTokenSize == 0 {
-		cfg.AccessTokenSize = 128
-	}
-
-	if cfg.RefreshTokenSize == 0 {
-		cfg.RefreshTokenSize = 128
-	}
-
-	return &TokenGenerator{
-		cfg: cfg,
-	}
-}
-
-func (g *TokenGenerator) GenerateAccessToken(generateRefresh bool) (accessToken string, refreshToken string, err error) {
-	accessToken, err = secure.GenerateRandomString(g.cfg.AccessTokenSize)
-
-	if generateRefresh {
-		refreshToken, err = secure.GenerateRandomString(g.cfg.RefreshTokenSize)
-	}
-
-	return
-}
diff --git a/authentication/provider/oauth2/token/random/token_generator_test.go b/authentication/provider/oauth2/token/random/token_generator_test.go
deleted file mode 100644
index f605837..0000000
--- a/authentication/provider/oauth2/token/random/token_generator_test.go
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package random
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestGenerateAccessToken(t *testing.T) {
-	g := NewTokenGenerator(&Configuration{
-		AccessTokenSize:  128,
-		RefreshTokenSize: 127,
-	})
-
-	accessToken, refreshToken, err := g.GenerateAccessToken(true)
-	assert.NoError(t, err)
-	assert.Equal(t, 128, len(accessToken))
-	assert.Equal(t, 127, len(refreshToken))
-	assert.NotEqual(t, accessToken, refreshToken)
-}
-
-func TestGenerateAccessTokenWithoutConfig(t *testing.T) {
-	g := NewTokenGenerator(&Configuration{})
-
-	accessToken, refreshToken, err := g.GenerateAccessToken(true)
-	assert.NoError(t, err)
-	assert.Equal(t, 128, len(accessToken))
-	assert.Equal(t, 128, len(refreshToken))
-	assert.NotEqual(t, accessToken, refreshToken)
-}
diff --git a/authenticator.go b/authenticator.go
new file mode 100644
index 0000000..78f4b95
--- /dev/null
+++ b/authenticator.go
@@ -0,0 +1,49 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "context"
+
+// Authenticator validates an [Authentication] produced by an [Extractor] and
+// returns a NEW authenticated value. It MUST NOT mutate its input — the
+// Authentication is treated as immutable everywhere in the core.
+//
+// Two-step contract:
+//
+//   - Supports reports whether the authenticator recognizes the credential
+//     type. Implementations MUST be cheap (a type switch); they MUST NOT
+//     perform I/O.
+//   - Authenticate validates the credential and either returns the new,
+//     authenticated value or an error wrapping a security sentinel
+//     ([ErrInvalidCredentials], [ErrTokenExpired], ...). Returning
+//     ([ErrUnsupportedCredential]) is the canonical way to bail out at
+//     runtime when Supports returned true but the value was nonetheless
+//     out of scope.
+//
+// Implementations MUST be safe for concurrent use.
+type Authenticator interface {
+	Supports(auth Authentication) bool
+	Authenticate(ctx context.Context, auth Authentication) (Authentication, error)
+}
+
+// AuthenticatorFunc adapts a function to the Authenticator interface. It
+// reports Supports == true for every input; callers wanting selectivity
+// should write a concrete type instead.
+type AuthenticatorFunc func(ctx context.Context, auth Authentication) (Authentication, error)
+
+// Supports implements [Authenticator].
+func (AuthenticatorFunc) Supports(Authentication) bool { return true }
+
+// Authenticate implements [Authenticator].
+func (f AuthenticatorFunc) Authenticate(ctx context.Context, auth Authentication) (Authentication, error) {
+	return f(ctx, auth)
+}
+
+// NamedAuthenticator is an optional capability: when an Authenticator
+// implements it, the [Manager] records the name in the OTel span so
+// observability backends can attribute decisions per provider.
+type NamedAuthenticator interface {
+	AuthenticatorName() string
+}
diff --git a/authorization/authorize_handler.go b/authorization/authorize_handler.go
deleted file mode 100644
index afb0b75..0000000
--- a/authorization/authorize_handler.go
+++ /dev/null
@@ -1,41 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authorization
-
-import (
-	"net/http"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-)
-
-// AuthorizeHandler check if user is authorize to access to resource.
-func AuthorizeHandler(options ...Option) func(next http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			creds := credential.FromContext(r.Context())
-			if creds == nil {
-				http.Error(w, "Access denied", http.StatusUnauthorized)
-
-				return
-			}
-
-			if !creds.IsAuthenticated() {
-				http.Error(w, "Access denied", http.StatusUnauthorized)
-
-				return
-			}
-
-			for _, opt := range options {
-				if !opt(creds) {
-					http.Error(w, "Access denied", http.StatusForbidden)
-
-					return
-				}
-			}
-
-			next.ServeHTTP(w, r)
-		})
-	}
-}
diff --git a/authorization/authorize_handler_test.go b/authorization/authorize_handler_test.go
deleted file mode 100644
index d0fea04..0000000
--- a/authorization/authorize_handler_test.go
+++ /dev/null
@@ -1,196 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authorization
-
-import (
-	"io"
-	"io/ioutil"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/gilcrest/alice"
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-type TestAuthenticationProvider struct {
-	authenticated bool
-	user          user.User
-}
-
-func (p *TestAuthenticationProvider) Authenticate(r *http.Request, creds credential.Credential) (*http.Request, error) {
-	creds.SetAuthenticated(p.authenticated)
-
-	if p.user != nil {
-		creds.SetUser(p.user)
-	}
-
-	return r, nil
-}
-
-func (p *TestAuthenticationProvider) IsSupported(creds credential.Credential) bool {
-	return true
-}
-
-func TestAuthorizeHandlerWithoutCredential(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		authentication.Handler(&TestAuthenticationProvider{}),
-		AuthorizeHandler(),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("Access denied\n"), body)
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestAuthorizeHandlerWithBadCredential(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		authentication.Handler(&TestAuthenticationProvider{authenticated: false}),
-		AuthorizeHandler(),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("Access denied\n"), body)
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestAuthorizeHandler(t *testing.T) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		authentication.Handler(&TestAuthenticationProvider{authenticated: true}),
-		AuthorizeHandler(),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-}
-
-func TestAuthorizeHandlerWithBadHasRole(t *testing.T) {
-	userMock := &user.MockUser{}
-
-	userMock.On("GetRoles").Return([]string{"ROLE_USER"})
-
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		authentication.Handler(&TestAuthenticationProvider{authenticated: true, user: userMock}),
-		AuthorizeHandler(HasRole("ROLE_ADMIN")),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("Access denied\n"), body)
-	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
-
-	userMock.AssertExpectations(t)
-}
-
-func TestAuthorizeHandlerWithHasRole(t *testing.T) {
-	userMock := &user.MockUser{}
-
-	userMock.On("GetRoles").Return([]string{"ROLE_ADMIN", "ROLE_USER"})
-
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Basic Zm9vOmJhcg==")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		authentication.Handler(&TestAuthenticationProvider{authenticated: true, user: userMock}),
-		AuthorizeHandler(HasRole("ROLE_ADMIN")),
-	)
-
-	middleware.ThenFunc(handler).ServeHTTP(w, req)
-
-	resp := w.Result()
-	body, err := ioutil.ReadAll(resp.Body)
-	assert.NoError(t, err)
-	assert.Equal(t, []byte("OK"), body)
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	userMock.AssertExpectations(t)
-}
-
-func BenchmarkAuthorizeHandler(b *testing.B) {
-	handler := func(w http.ResponseWriter, r *http.Request) {
-		io.WriteString(w, "OK")
-	}
-
-	req := httptest.NewRequest("GET", "http://example.com/v1/me", nil)
-	req.Header.Set("Authorization", "Bearer foo")
-
-	w := httptest.NewRecorder()
-
-	middleware := alice.New(
-		authentication.FilterHandler(authentication.NewHTTPBasicFilter(), authentication.NewBearerFilter()),
-		AuthorizeHandler(),
-	)
-
-	b.ResetTimer()
-
-	for n := 0; n < b.N; n++ {
-		middleware.ThenFunc(handler).ServeHTTP(w, req)
-	}
-}
diff --git a/authorization/has_role_option.go b/authorization/has_role_option.go
deleted file mode 100644
index 648db1d..0000000
--- a/authorization/has_role_option.go
+++ /dev/null
@@ -1,28 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authorization
-
-import "github.com/hyperscale-stack/security/authentication/credential"
-
-// HasRole check if user has role.
-func HasRole(role string) Option {
-	return func(creds credential.Credential) bool {
-		user := creds.GetUser()
-
-		if user == nil {
-			return false
-		}
-
-		roles := user.GetRoles()
-
-		for _, r := range roles {
-			if r == role {
-				return true
-			}
-		}
-
-		return false
-	}
-}
diff --git a/authorization/has_role_option_test.go b/authorization/has_role_option_test.go
deleted file mode 100644
index 658c196..0000000
--- a/authorization/has_role_option_test.go
+++ /dev/null
@@ -1,51 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authorization
-
-import (
-	"testing"
-
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestHasRoleWithoutUser(t *testing.T) {
-	opt := HasRole("ROLE_ADMIN")
-
-	credential := credential.NewUsernamePasswordCredential("foo", "bar")
-
-	assert.False(t, opt(credential))
-}
-
-func TestHasRoleWithBadRole(t *testing.T) {
-	opt := HasRole("ROLE_ADMIN")
-
-	userMock := &user.MockUser{}
-
-	userMock.On("GetRoles").Return([]string{"ROLE_USER"})
-
-	credential := credential.NewUsernamePasswordCredential("foo", "bar")
-	credential.SetUser(userMock)
-
-	assert.False(t, opt(credential))
-
-	userMock.AssertExpectations(t)
-}
-
-func TestHasRole(t *testing.T) {
-	opt := HasRole("ROLE_ADMIN")
-
-	userMock := &user.MockUser{}
-
-	userMock.On("GetRoles").Return([]string{"ROLE_USER", "ROLE_ADMIN"})
-
-	credential := credential.NewUsernamePasswordCredential("foo", "bar")
-	credential.SetUser(userMock)
-
-	assert.True(t, opt(credential))
-
-	userMock.AssertExpectations(t)
-}
diff --git a/authorization/option.go b/authorization/option.go
deleted file mode 100644
index 778df4c..0000000
--- a/authorization/option.go
+++ /dev/null
@@ -1,10 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package authorization
-
-import "github.com/hyperscale-stack/security/authentication/credential"
-
-// Option type.
-type Option func(creds credential.Credential) bool
diff --git a/basic/authentication.go b/basic/authentication.go
new file mode 100644
index 0000000..dcc833f
--- /dev/null
+++ b/basic/authentication.go
@@ -0,0 +1,88 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic
+
+import "github.com/hyperscale-stack/security"
+
+// Authentication is the [security.Authentication] produced by the Basic
+// [Extractor]. It carries the supplied username/password pair before
+// validation and the resolved [PasswordUser] after. The struct is immutable;
+// "mutations" return a fresh value.
+type Authentication struct {
+	username    string
+	password    string
+	user        PasswordUser
+	authorities []string
+	authed      bool
+}
+
+// New constructs an unauthenticated Authentication from a username/password
+// pair. Reserved for [Extractor] implementations; application code should
+// build authentications via the Engine pipeline instead.
+func New(username, password string) Authentication {
+	return Authentication{username: username, password: password}
+}
+
+// Username returns the username extracted from the request. It MAY differ
+// from the resolved [PasswordUser]'s subject (e.g. login by email).
+func (a Authentication) Username() string { return a.username }
+
+// Password returns the cleartext password. Once an [Authenticator] has
+// validated the credential, the returned value is zeroed (see WithAuthenticated).
+func (a Authentication) Password() string { return a.password }
+
+// WithAuthenticated returns a new Authentication marked as validated, with
+// the resolved user attached, the cleartext password redacted, and the
+// authorities materialized from the user.
+func (a Authentication) WithAuthenticated(user PasswordUser, authorities []string) Authentication {
+	cp := authorities
+	if authorities != nil {
+		cp = make([]string, len(authorities))
+		copy(cp, authorities)
+	}
+
+	return Authentication{
+		username:    a.username,
+		password:    "", // redact cleartext after successful auth
+		user:        user,
+		authorities: cp,
+		authed:      true,
+	}
+}
+
+// Principal implements [security.Authentication]. Returns the resolved
+// [PasswordUser] when the value is authenticated, the [security.AnonymousPrincipal]
+// otherwise (so downstream code can rely on a non-nil principal).
+func (a Authentication) Principal() security.Principal {
+	if a.user != nil {
+		return a.user
+	}
+
+	return security.AnonymousPrincipal
+}
+
+// Credentials implements [security.Authentication]. Returns the cleartext
+// password before authentication, nil after.
+func (a Authentication) Credentials() any {
+	if a.password == "" {
+		return nil
+	}
+
+	return a.password
+}
+
+// Authorities implements [security.Authentication].
+func (a Authentication) Authorities() []string { return a.authorities }
+
+// IsAuthenticated implements [security.Authentication].
+func (a Authentication) IsAuthenticated() bool { return a.authed }
+
+// Name implements [security.Authentication]. Returns the username, which is
+// the user-facing identifier for HTTP Basic flows.
+func (a Authentication) Name() string { return a.username }
+
+// User returns the resolved [PasswordUser], or nil when the value is still
+// pre-authentication.
+func (a Authentication) User() PasswordUser { return a.user }
diff --git a/basic/authentication_test.go b/basic/authentication_test.go
new file mode 100644
index 0000000..19d8605
--- /dev/null
+++ b/basic/authentication_test.go
@@ -0,0 +1,66 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/basic"
+	"github.com/stretchr/testify/assert"
+)
+
+// fakeUser is a minimal basic.PasswordUser for the authentication tests.
+type fakeUser struct{ sub string }
+
+func (u fakeUser) Subject() string           { return u.sub }
+func (u fakeUser) GetPasswordHash() string   { return "" }
+func (u fakeUser) IsEnabled() bool           { return true }
+func (u fakeUser) IsLocked() bool            { return false }
+func (u fakeUser) IsExpired() bool           { return false }
+func (u fakeUser) IsCredentialsExpired() bool { return false }
+
+func TestAuthenticationPreAuth(t *testing.T) {
+	t.Parallel()
+
+	auth := basic.New("alice", "s3cr3t")
+
+	assert.Equal(t, "alice", auth.Username())
+	assert.Equal(t, "s3cr3t", auth.Password())
+	assert.Equal(t, "alice", auth.Name())
+	assert.False(t, auth.IsAuthenticated())
+	assert.Nil(t, auth.Authorities())
+	assert.Nil(t, auth.User())
+
+	// Before authentication the cleartext password is the credential.
+	assert.Equal(t, "s3cr3t", auth.Credentials())
+
+	// With no resolved user the principal falls back to the anonymous one.
+	assert.Equal(t, security.AnonymousPrincipal, auth.Principal())
+}
+
+func TestAuthenticationPostAuth(t *testing.T) {
+	t.Parallel()
+
+	user := fakeUser{sub: "alice"}
+	auth := basic.New("alice", "s3cr3t").WithAuthenticated(user, []string{"ROLE_ADMIN"})
+
+	assert.True(t, auth.IsAuthenticated())
+	assert.Equal(t, []string{"ROLE_ADMIN"}, auth.Authorities())
+	assert.Equal(t, user, auth.User())
+	assert.Equal(t, user, auth.Principal())
+
+	// The cleartext password is redacted once authenticated.
+	assert.Empty(t, auth.Password())
+	assert.Nil(t, auth.Credentials())
+}
+
+func TestAuthenticationEmptyPasswordHasNoCredentials(t *testing.T) {
+	t.Parallel()
+
+	// An empty password yields a nil credential without going through
+	// authentication (e.g. a malformed header that produced no secret).
+	assert.Nil(t, basic.New("bob", "").Credentials())
+}
diff --git a/basic/authenticator.go b/basic/authenticator.go
new file mode 100644
index 0000000..f05fea2
--- /dev/null
+++ b/basic/authenticator.go
@@ -0,0 +1,112 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/password"
+)
+
+// AuthorityResolver maps a [PasswordUser] to the authorities (roles, scopes,
+// claims) attached to the resulting [security.Authentication]. The default
+// resolver returns nil; applications that ship role-based authorization
+// provide one that reads the authorities from the user record.
+type AuthorityResolver func(PasswordUser) []string
+
+// Authenticator implements [security.Authenticator] for the HTTP Basic
+// scheme. It loads the user via a [UserLoader], runs lifecycle checks,
+// verifies the password with a [password.Hasher], then returns the
+// authenticated [Authentication].
+//
+// Errors are always wrapped in [security.ErrInvalidCredentials] to avoid
+// account-enumeration via response-time / response-code analysis. Detailed
+// causes remain reachable through errors.As / errors.Is for server-side
+// telemetry only — do NOT mirror them in the client response.
+type Authenticator struct {
+	loader     UserLoader
+	hasher     password.Hasher
+	authResolv AuthorityResolver
+}
+
+// NewAuthenticator returns an Authenticator using the supplied loader and
+// hasher. Authorities default to nil (use [WithAuthorityResolver] to
+// populate them from the user record).
+func NewAuthenticator(loader UserLoader, hasher password.Hasher, opts ...Option) *Authenticator {
+	a := &Authenticator{loader: loader, hasher: hasher}
+
+	for _, o := range opts {
+		o(a)
+	}
+
+	return a
+}
+
+// Option configures an Authenticator.
+type Option func(*Authenticator)
+
+// WithAuthorityResolver overrides the resolver mapping a [PasswordUser] to
+// the authorities materialized on the [Authentication].
+func WithAuthorityResolver(r AuthorityResolver) Option {
+	return func(a *Authenticator) { a.authResolv = r }
+}
+
+// AuthenticatorName implements [security.NamedAuthenticator] so the core
+// Manager can attribute spans to "basic".
+func (a *Authenticator) AuthenticatorName() string { return "basic" }
+
+// Supports reports whether auth is a [basic.Authentication]. Returns false
+// for everything else, which lets the [security.Manager] delegate to the
+// next authenticator in line.
+func (a *Authenticator) Supports(auth security.Authentication) bool {
+	_, ok := auth.(Authentication)
+
+	return ok
+}
+
+// Authenticate implements [security.Authenticator].
+func (a *Authenticator) Authenticate(ctx context.Context, auth security.Authentication) (security.Authentication, error) {
+	in, ok := auth.(Authentication)
+	if !ok {
+		return auth, security.ErrUnsupportedCredential
+	}
+
+	user, err := a.loader.LoadByUsername(ctx, in.Username())
+	if err != nil {
+		// Loader-level errors (db down, unknown user, ...) collapse to a
+		// single ErrInvalidCredentials at the client boundary. The original
+		// error stays in the chain for observability.
+		return auth, fmt.Errorf("basic: load user %q: %w (%w)", in.Username(), err, security.ErrInvalidCredentials)
+	}
+
+	if user == nil {
+		return auth, fmt.Errorf("basic: user not found: %w", security.ErrInvalidCredentials)
+	}
+
+	if !user.IsEnabled() || user.IsLocked() || user.IsExpired() || user.IsCredentialsExpired() {
+		return auth, fmt.Errorf("basic: account ineligible: %w", security.ErrInvalidCredentials)
+	}
+
+	ok, err = a.hasher.Verify(ctx, user.GetPasswordHash(), in.Password())
+	if err != nil {
+		return auth, fmt.Errorf("basic: hash verify: %w (%w)", err, security.ErrInvalidCredentials)
+	}
+
+	if !ok {
+		return auth, fmt.Errorf("basic: password mismatch: %w", security.ErrInvalidCredentials)
+	}
+
+	var authorities []string
+	if a.authResolv != nil {
+		authorities = a.authResolv(user)
+	}
+
+	return in.WithAuthenticated(user, authorities), nil
+}
+
+// Compile-time interface check.
+var _ security.Authenticator = (*Authenticator)(nil)
diff --git a/basic/authenticator_test.go b/basic/authenticator_test.go
new file mode 100644
index 0000000..3154ef8
--- /dev/null
+++ b/basic/authenticator_test.go
@@ -0,0 +1,189 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/basic"
+	"github.com/hyperscale-stack/security/password"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// stubUser is a [basic.PasswordUser] driven by per-field flags so individual
+// tests can dial in the exact lifecycle scenario they need.
+type stubUser struct {
+	subject              string
+	passwordHash         string
+	enabled              bool
+	locked               bool
+	expired              bool
+	credentialsExpired   bool
+}
+
+func (u *stubUser) Subject() string            { return u.subject }
+func (u *stubUser) GetPasswordHash() string    { return u.passwordHash }
+func (u *stubUser) IsEnabled() bool            { return u.enabled }
+func (u *stubUser) IsLocked() bool             { return u.locked }
+func (u *stubUser) IsExpired() bool            { return u.expired }
+func (u *stubUser) IsCredentialsExpired() bool { return u.credentialsExpired }
+
+// stubLoader is a tiny in-memory loader.
+type stubLoader struct {
+	user *stubUser
+	err  error
+}
+
+func (l *stubLoader) LoadByUsername(_ context.Context, username string) (basic.PasswordUser, error) {
+	if l.err != nil {
+		return nil, l.err
+	}
+
+	if l.user == nil || l.user.Subject() != username {
+		return nil, nil
+	}
+
+	return l.user, nil
+}
+
+func newHasher(t *testing.T) password.Hasher {
+	t.Helper()
+
+	return password.NewBCryptHasher(4)
+}
+
+func mustHash(t *testing.T, h password.Hasher, plain string) string {
+	t.Helper()
+
+	out, err := h.Hash(context.Background(), plain)
+	require.NoError(t, err)
+
+	return out
+}
+
+func TestAuthenticatorSupportsOnlyBasicAuthentications(t *testing.T) {
+	t.Parallel()
+
+	a := basic.NewAuthenticator(&stubLoader{}, newHasher(t))
+	assert.True(t, a.Supports(basic.New("u", "p")))
+	assert.False(t, a.Supports(security.Anonymous()))
+}
+
+func TestAuthenticatorSuccess(t *testing.T) {
+	t.Parallel()
+
+	h := newHasher(t)
+	u := &stubUser{subject: "alice", passwordHash: mustHash(t, h, "p4ss"), enabled: true}
+	auth := basic.NewAuthenticator(&stubLoader{user: u}, h)
+
+	got, err := auth.Authenticate(context.Background(), basic.New("alice", "p4ss"))
+	require.NoError(t, err)
+	assert.True(t, got.IsAuthenticated())
+	assert.Equal(t, "alice", got.Principal().Subject())
+
+	ba := got.(basic.Authentication)
+	assert.Equal(t, "", ba.Password(), "cleartext password must be redacted after success")
+	assert.Same(t, u, ba.User())
+}
+
+func TestAuthenticatorBadPassword(t *testing.T) {
+	t.Parallel()
+
+	h := newHasher(t)
+	u := &stubUser{subject: "alice", passwordHash: mustHash(t, h, "good"), enabled: true}
+	auth := basic.NewAuthenticator(&stubLoader{user: u}, h)
+
+	_, err := auth.Authenticate(context.Background(), basic.New("alice", "bad"))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+}
+
+func TestAuthenticatorUnknownUser(t *testing.T) {
+	t.Parallel()
+
+	auth := basic.NewAuthenticator(&stubLoader{}, newHasher(t))
+
+	_, err := auth.Authenticate(context.Background(), basic.New("ghost", "x"))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials,
+		"unknown user must NOT leak via a distinct error (account enumeration)")
+}
+
+func TestAuthenticatorLifecycleFlagsAreEnforced(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name   string
+		mutate func(*stubUser)
+	}{
+		{"disabled", func(u *stubUser) { u.enabled = false }},
+		{"locked", func(u *stubUser) { u.locked = true }},
+		{"expired", func(u *stubUser) { u.expired = true }},
+		{"credentials_expired", func(u *stubUser) { u.credentialsExpired = true }},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			h := newHasher(t)
+			u := &stubUser{subject: "alice", passwordHash: mustHash(t, h, "p"), enabled: true}
+			c.mutate(u)
+
+			a := basic.NewAuthenticator(&stubLoader{user: u}, h)
+			_, err := a.Authenticate(context.Background(), basic.New("alice", "p"))
+			require.Error(t, err)
+			assert.ErrorIs(t, err, security.ErrInvalidCredentials,
+				"lifecycle failures MUST collapse to ErrInvalidCredentials at the boundary")
+		})
+	}
+}
+
+func TestAuthenticatorLoaderErrorWraps(t *testing.T) {
+	t.Parallel()
+
+	boom := errors.New("db unreachable")
+	a := basic.NewAuthenticator(&stubLoader{err: boom}, newHasher(t))
+
+	_, err := a.Authenticate(context.Background(), basic.New("alice", "p"))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+	assert.ErrorIs(t, err, boom, "loader error chain must remain inspectable for ops")
+}
+
+func TestAuthenticatorAuthorityResolverPopulatesAuthorities(t *testing.T) {
+	t.Parallel()
+
+	h := newHasher(t)
+	u := &stubUser{subject: "alice", passwordHash: mustHash(t, h, "p"), enabled: true}
+	a := basic.NewAuthenticator(&stubLoader{user: u}, h, basic.WithAuthorityResolver(
+		func(basic.PasswordUser) []string { return []string{"ROLE_USER", "scope:read"} },
+	))
+
+	got, err := a.Authenticate(context.Background(), basic.New("alice", "p"))
+	require.NoError(t, err)
+	assert.Equal(t, []string{"ROLE_USER", "scope:read"}, got.Authorities())
+}
+
+func TestAuthenticatorRejectsForeignAuthentication(t *testing.T) {
+	t.Parallel()
+
+	a := basic.NewAuthenticator(&stubLoader{}, newHasher(t))
+
+	_, err := a.Authenticate(context.Background(), security.Anonymous())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrUnsupportedCredential)
+}
+
+func TestAuthenticatorName(t *testing.T) {
+	t.Parallel()
+
+	a := basic.NewAuthenticator(nil, nil)
+	assert.Equal(t, "basic", a.AuthenticatorName())
+}
diff --git a/basic/doc.go b/basic/doc.go
new file mode 100644
index 0000000..8e12baa
--- /dev/null
+++ b/basic/doc.go
@@ -0,0 +1,15 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package basic provides HTTP Basic authentication for the security core.
+//
+// It ships an Extractor that reads "Authorization: Basic ..." headers from a
+// Carrier, and an Authenticator that consumes a UserLoader + a Hasher to
+// validate the username/password pair against a backing store.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - github.com/hyperscale-stack/security/password (for password hashing)
+//   - stdlib only
+package basic
diff --git a/basic/extractor.go b/basic/extractor.go
new file mode 100644
index 0000000..5d3ebc8
--- /dev/null
+++ b/basic/extractor.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// ErrBadFormat is returned by the [Extractor] when the Authorization header
+// carries a Basic scheme but the payload cannot be decoded (invalid base64,
+// missing colon, ...). It is wrapped around [security.ErrInvalidCredentials]
+// so error mappers route it to 401 — and to prevent oracle attacks that
+// distinguish "malformed" from "wrong".
+var ErrBadFormat = errors.New("basic: malformed credentials")
+
+const scheme = "Basic"
+
+// Extractor implements [security.Extractor] for the HTTP Basic scheme
+// (RFC 7617). It reads the Authorization header from the Carrier and parses
+// the base64-encoded "username:password" payload. The scheme prefix is
+// matched case-insensitively per RFC 7235 §2.1.
+type Extractor struct{}
+
+// NewExtractor returns the canonical zero-config Extractor.
+func NewExtractor() Extractor { return Extractor{} }
+
+// Extract implements [security.Extractor]. Returns (nil, nil) when no Basic
+// credentials are present (next extractor gets a chance); a non-nil error
+// for credentials that are present but malformed.
+func (Extractor) Extract(_ context.Context, c security.Carrier) (security.Authentication, error) {
+	header := c.Get("Authorization")
+	if header == "" {
+		return nil, nil
+	}
+
+	payload, ok := extractValue(scheme, header)
+	if !ok {
+		// Header carries some other scheme (Bearer, Digest...). Let
+		// downstream extractors try.
+		return nil, nil
+	}
+
+	raw, err := base64.StdEncoding.DecodeString(payload)
+	if err != nil {
+		return nil, fmt.Errorf("basic: base64 decode: %w (%w)", ErrBadFormat, security.ErrInvalidCredentials)
+	}
+
+	colon := strings.IndexByte(string(raw), ':')
+	if colon < 0 {
+		return nil, fmt.Errorf("basic: missing colon separator: %w (%w)", ErrBadFormat, security.ErrInvalidCredentials)
+	}
+
+	return New(string(raw[:colon]), string(raw[colon+1:])), nil
+}
+
+// extractValue is the case-insensitive scheme-stripper. Duplicated locally to
+// avoid a transport-shaped dependency on httpsec (which would create a cycle
+// once httpsec composes basic.Extractor).
+func extractValue(scheme, header string) (string, bool) {
+	prefix := scheme + " "
+	if len(header) < len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+		return "", false
+	}
+
+	return header[len(prefix):], true
+}
diff --git a/basic/extractor_test.go b/basic/extractor_test.go
new file mode 100644
index 0000000..4740166
--- /dev/null
+++ b/basic/extractor_test.go
@@ -0,0 +1,136 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic_test
+
+import (
+	"context"
+	"encoding/base64"
+	"net/textproto"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/basic"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mapCarrier is a minimal security.Carrier replica used by basic tests so we
+// don't pull in httpsec.
+type mapCarrier struct{ headers map[string][]string }
+
+func newCarrier() *mapCarrier { return &mapCarrier{headers: make(map[string][]string)} }
+
+func (c *mapCarrier) key(k string) string { return textproto.CanonicalMIMEHeaderKey(k) }
+func (c *mapCarrier) Get(k string) string {
+	vs := c.headers[c.key(k)]
+	if len(vs) == 0 {
+		return ""
+	}
+
+	return vs[0]
+}
+func (c *mapCarrier) Values(k string) []string { return c.headers[c.key(k)] }
+func (c *mapCarrier) Set(k, v string)          { c.headers[c.key(k)] = []string{v} }
+func (c *mapCarrier) Add(k, v string)          { c.headers[c.key(k)] = append(c.headers[c.key(k)], v) }
+
+func encode(s string) string { return base64.StdEncoding.EncodeToString([]byte(s)) }
+
+func TestExtractorReturnsNilWhenNoAuthorizationHeader(t *testing.T) {
+	t.Parallel()
+
+	auth, err := basic.NewExtractor().Extract(context.Background(), newCarrier())
+	require.NoError(t, err)
+	assert.Nil(t, auth)
+}
+
+func TestExtractorReturnsNilWhenSchemeIsNotBasic(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Bearer abc")
+
+	auth, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	assert.Nil(t, auth, "non-Basic scheme MUST not be consumed")
+}
+
+func TestExtractorParsesValidBasicHeader(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic "+encode("alice:p4ss"))
+
+	got, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+
+	ba, ok := got.(basic.Authentication)
+	require.True(t, ok, "Extract must return basic.Authentication")
+	assert.Equal(t, "alice", ba.Username())
+	assert.Equal(t, "p4ss", ba.Password())
+	assert.False(t, ba.IsAuthenticated(), "extractor result is pre-authentication")
+}
+
+func TestExtractorIsCaseInsensitiveOnScheme(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "bAsIc "+encode("a:b"))
+
+	got, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	assert.NotNil(t, got)
+}
+
+func TestExtractorRejectsInvalidBase64(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic !!!")
+
+	_, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+	assert.ErrorIs(t, err, basic.ErrBadFormat)
+}
+
+func TestExtractorRejectsMissingColon(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic "+encode("alicepassword"))
+
+	_, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+}
+
+func TestExtractorPasswordCanContainColons(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic "+encode("alice:p4:ss:word"))
+
+	got, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+
+	ba := got.(basic.Authentication)
+	assert.Equal(t, "alice", ba.Username())
+	assert.Equal(t, "p4:ss:word", ba.Password())
+}
+
+func TestExtractorEmptyUsernameAndPasswordIsAccepted(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic "+encode(":"))
+
+	got, err := basic.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+
+	ba := got.(basic.Authentication)
+	assert.Empty(t, ba.Username())
+	assert.Empty(t, ba.Password())
+}
diff --git a/basic/go.mod b/basic/go.mod
new file mode 100644
index 0000000..7d0c595
--- /dev/null
+++ b/basic/go.mod
@@ -0,0 +1,28 @@
+module github.com/hyperscale-stack/security/basic
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/password v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../
+
+replace github.com/hyperscale-stack/security/password => ../password
diff --git a/basic/go.sum b/basic/go.sum
new file mode 100644
index 0000000..fcbab9b
--- /dev/null
+++ b/basic/go.sum
@@ -0,0 +1,42 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/basic/loader.go b/basic/loader.go
new file mode 100644
index 0000000..887c65f
--- /dev/null
+++ b/basic/loader.go
@@ -0,0 +1,51 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package basic
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// PasswordUser is the [security.Principal] specialisation expected by this
+// module's [Authenticator]. It exposes the hashed password so the
+// authenticator can call [password.Hasher].Verify against the supplied
+// credentials, plus the account-lifecycle predicates so disabled / locked /
+// expired accounts can be refused without leaking the cause to the client.
+type PasswordUser interface {
+	security.Principal
+
+	// GetPasswordHash returns the encoded hash (as produced by a
+	// [password.Hasher].Hash call). The value MUST never be logged.
+	GetPasswordHash() string
+
+	// IsEnabled reports whether the account is active. Disabled accounts
+	// MUST fail authentication.
+	IsEnabled() bool
+
+	// IsLocked reports whether the account is temporarily locked (after
+	// repeated failed attempts, manual hold, ...).
+	IsLocked() bool
+
+	// IsExpired reports whether the account itself has expired (e.g.
+	// contractor whose access window is over).
+	IsExpired() bool
+
+	// IsCredentialsExpired reports whether the password must be rotated
+	// before login is allowed.
+	IsCredentialsExpired() bool
+}
+
+// UserLoader resolves a username to a [PasswordUser]. Implementations live
+// in the application layer; this module ships no implementation to keep
+// itself storage-agnostic.
+//
+// On unknown user, implementations SHOULD return an error wrapping
+// [security.ErrInvalidCredentials] to prevent account enumeration via
+// response-time / response-code differences.
+type UserLoader interface {
+	LoadByUsername(ctx context.Context, username string) (PasswordUser, error)
+}
diff --git a/bearer/authentication.go b/bearer/authentication.go
new file mode 100644
index 0000000..8989a3e
--- /dev/null
+++ b/bearer/authentication.go
@@ -0,0 +1,100 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer
+
+import "github.com/hyperscale-stack/security"
+
+// Authentication is the [security.Authentication] produced by the bearer
+// [Extractor]. Before validation it carries only the opaque token; after
+// validation a [TokenVerifier] is expected to return a new value where
+// Principal, Authorities and IsAuthenticated are populated.
+type Authentication struct {
+	token       string
+	principal   security.Principal
+	authorities []string
+	authed      bool
+	name        string
+}
+
+// New constructs an unauthenticated bearer Authentication from an opaque
+// token. Reserved for [Extractor] implementations.
+func New(token string) Authentication {
+	return Authentication{token: token}
+}
+
+// Token returns the raw bearer token. Once a [TokenVerifier] has produced an
+// authenticated value, the token can be redacted by calling
+// [Authentication.WithAuthenticated] with a verifier that builds a fresh
+// value from scratch.
+func (a Authentication) Token() string { return a.token }
+
+// WithAuthenticated returns a new Authentication marked as validated, with
+// the provided principal, authorities and display name. The token is
+// preserved so adapters that issue refresh challenges can still inspect it.
+func (a Authentication) WithAuthenticated(p security.Principal, authorities []string, name string) Authentication {
+	cp := authorities
+	if authorities != nil {
+		cp = make([]string, len(authorities))
+		copy(cp, authorities)
+	}
+
+	if name == "" && p != nil {
+		name = p.Subject()
+	}
+
+	return Authentication{
+		token:       a.token,
+		principal:   p,
+		authorities: cp,
+		authed:      true,
+		name:        name,
+	}
+}
+
+// Principal implements [security.Authentication].
+func (a Authentication) Principal() security.Principal {
+	if a.principal != nil {
+		return a.principal
+	}
+
+	return security.AnonymousPrincipal
+}
+
+// Credentials implements [security.Authentication]. Returns the token before
+// authentication, nil after (the verifier is expected to redact via a fresh
+// WithAuthenticated call).
+func (a Authentication) Credentials() any {
+	if a.authed {
+		return nil
+	}
+
+	return a.token
+}
+
+// Authorities implements [security.Authentication].
+func (a Authentication) Authorities() []string { return a.authorities }
+
+// IsAuthenticated implements [security.Authentication].
+func (a Authentication) IsAuthenticated() bool { return a.authed }
+
+// Name implements [security.Authentication]. Returns the validated name when
+// authenticated, the principal subject otherwise, or "bearer" as a last
+// resort so log lines remain non-empty.
+func (a Authentication) Name() string {
+	if a.name != "" {
+		return a.name
+	}
+
+	if a.principal != nil {
+		return a.principal.Subject()
+	}
+
+	return schemeName
+}
+
+// schemeName is the canonical scheme label used both as a fallback
+// Authentication.Name and as the [Authenticator.AuthenticatorName] return
+// value (so span attribution stays consistent).
+const schemeName = "bearer"
diff --git a/bearer/authentication_test.go b/bearer/authentication_test.go
new file mode 100644
index 0000000..797db70
--- /dev/null
+++ b/bearer/authentication_test.go
@@ -0,0 +1,54 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	"github.com/stretchr/testify/assert"
+)
+
+type principal struct{ sub string }
+
+func (p principal) Subject() string { return p.sub }
+
+func TestAuthenticationPreAuth(t *testing.T) {
+	t.Parallel()
+
+	auth := bearer.New("opaque-token")
+
+	assert.Equal(t, "opaque-token", auth.Token())
+	assert.False(t, auth.IsAuthenticated())
+	assert.Nil(t, auth.Authorities())
+	// Before authentication the token is the credential.
+	assert.Equal(t, "opaque-token", auth.Credentials())
+	// No principal yet -> anonymous fallback, and Name falls back to the scheme.
+	assert.Equal(t, security.AnonymousPrincipal, auth.Principal())
+	assert.Equal(t, "bearer", auth.Name())
+}
+
+func TestAuthenticationPostAuth(t *testing.T) {
+	t.Parallel()
+
+	p := principal{sub: "alice"}
+	auth := bearer.New("opaque-token").WithAuthenticated(p, []string{"scope:read"}, "alice")
+
+	assert.True(t, auth.IsAuthenticated())
+	assert.Equal(t, p, auth.Principal())
+	assert.Equal(t, []string{"scope:read"}, auth.Authorities())
+	assert.Equal(t, "alice", auth.Name())
+	// The token is no longer exposed as a credential once authenticated.
+	assert.Nil(t, auth.Credentials())
+}
+
+func TestAuthenticationNameFallsBackToSubject(t *testing.T) {
+	t.Parallel()
+
+	// An empty display name falls back to the principal subject.
+	auth := bearer.New("t").WithAuthenticated(principal{sub: "bob"}, nil, "")
+	assert.Equal(t, "bob", auth.Name())
+}
diff --git a/bearer/authenticator.go b/bearer/authenticator.go
new file mode 100644
index 0000000..03e982d
--- /dev/null
+++ b/bearer/authenticator.go
@@ -0,0 +1,65 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Authenticator implements [security.Authenticator] for the Bearer scheme.
+// It delegates token validation to a pluggable [TokenVerifier]; the bearer
+// module ships no concrete verifier so it stays format-agnostic.
+type Authenticator struct {
+	verifier TokenVerifier
+}
+
+// NewAuthenticator returns an [Authenticator] backed by verifier.
+// A nil verifier triggers a panic at construction time — the configuration
+// would be silently insecure otherwise.
+func NewAuthenticator(verifier TokenVerifier) *Authenticator {
+	if verifier == nil {
+		panic("bearer: NewAuthenticator: nil TokenVerifier")
+	}
+
+	return &Authenticator{verifier: verifier}
+}
+
+// AuthenticatorName implements [security.NamedAuthenticator].
+func (a *Authenticator) AuthenticatorName() string { return schemeName }
+
+// Supports reports whether auth is a [bearer.Authentication].
+func (a *Authenticator) Supports(auth security.Authentication) bool {
+	_, ok := auth.(Authentication)
+
+	return ok
+}
+
+// Authenticate implements [security.Authenticator]. The returned
+// authentication is whatever the verifier produced; on verifier error the
+// error is propagated as-is (the verifier is expected to wrap one of the
+// security sentinels for the error mapper to route).
+func (a *Authenticator) Authenticate(ctx context.Context, auth security.Authentication) (security.Authentication, error) {
+	in, ok := auth.(Authentication)
+	if !ok {
+		return auth, security.ErrUnsupportedCredential
+	}
+
+	out, err := a.verifier.Verify(ctx, in.Token())
+	if err != nil {
+		return auth, fmt.Errorf("bearer: verify token: %w", err)
+	}
+
+	if out == nil {
+		return auth, fmt.Errorf("bearer: verifier returned nil authentication: %w", security.ErrInvalidCredentials)
+	}
+
+	return out, nil
+}
+
+// Compile-time interface check.
+var _ security.Authenticator = (*Authenticator)(nil)
diff --git a/bearer/authenticator_test.go b/bearer/authenticator_test.go
new file mode 100644
index 0000000..9e0445a
--- /dev/null
+++ b/bearer/authenticator_test.go
@@ -0,0 +1,102 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakePrincipal is the test-local Principal used by bearer tests.
+type fakePrincipal struct{ sub string }
+
+func (p fakePrincipal) Subject() string { return p.sub }
+
+func TestNewAuthenticatorPanicsOnNilVerifier(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() { bearer.NewAuthenticator(nil) })
+}
+
+func TestAuthenticatorName(t *testing.T) {
+	t.Parallel()
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(context.Context, string) (security.Authentication, error) {
+		return nil, nil
+	}))
+	assert.Equal(t, "bearer", a.AuthenticatorName())
+}
+
+func TestAuthenticatorSupportsOnlyBearerAuthentications(t *testing.T) {
+	t.Parallel()
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(context.Context, string) (security.Authentication, error) {
+		return nil, nil
+	}))
+	assert.True(t, a.Supports(bearer.New("x")))
+	assert.False(t, a.Supports(security.Anonymous()))
+}
+
+func TestAuthenticatorSuccessHandsBackVerifierOutput(t *testing.T) {
+	t.Parallel()
+
+	want := bearer.New("redacted").WithAuthenticated(fakePrincipal{sub: "alice"}, []string{"scope:read"}, "alice")
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(_ context.Context, token string) (security.Authentication, error) {
+		assert.Equal(t, "tk", token)
+
+		return want, nil
+	}))
+
+	got, err := a.Authenticate(context.Background(), bearer.New("tk"))
+	require.NoError(t, err)
+	assert.Equal(t, want, got)
+	assert.True(t, got.IsAuthenticated())
+	assert.Nil(t, got.Credentials(), "token MUST be redacted from the authenticated value")
+}
+
+func TestAuthenticatorVerifierErrorIsWrapped(t *testing.T) {
+	t.Parallel()
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(context.Context, string) (security.Authentication, error) {
+		return nil, security.ErrTokenExpired
+	}))
+
+	_, err := a.Authenticate(context.Background(), bearer.New("tk"))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrTokenExpired)
+}
+
+func TestAuthenticatorRejectsNilFromVerifier(t *testing.T) {
+	t.Parallel()
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(context.Context, string) (security.Authentication, error) {
+		return nil, nil
+	}))
+
+	_, err := a.Authenticate(context.Background(), bearer.New("tk"))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+}
+
+func TestAuthenticatorRejectsForeignAuthentication(t *testing.T) {
+	t.Parallel()
+
+	a := bearer.NewAuthenticator(bearer.VerifierFunc(func(context.Context, string) (security.Authentication, error) {
+		t.Fatal("verifier must not be called")
+
+		return nil, errors.New("unreachable")
+	}))
+
+	_, err := a.Authenticate(context.Background(), security.Anonymous())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrUnsupportedCredential)
+}
diff --git a/bearer/doc.go b/bearer/doc.go
new file mode 100644
index 0000000..7878c50
--- /dev/null
+++ b/bearer/doc.go
@@ -0,0 +1,19 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package bearer provides Bearer token extraction and an Authenticator that
+// delegates token validation to a pluggable TokenVerifier.
+//
+// The TokenVerifier interface lets users plug an opaque-token verifier
+// (calling a remote introspection endpoint), a local JWT verifier (see the
+// jwt sub-module), or any custom scheme.
+//
+// Only the Authorization-header scheme (RFC 6750 §2.1) is supported;
+// query-parameter tokens (§2.3) are intentionally not offered — they leak
+// into access logs, browser history, and Referer headers.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - stdlib only
+package bearer
diff --git a/bearer/extractor.go b/bearer/extractor.go
new file mode 100644
index 0000000..191aa4d
--- /dev/null
+++ b/bearer/extractor.go
@@ -0,0 +1,56 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer
+
+import (
+	"context"
+	"strings"
+
+	"github.com/hyperscale-stack/security"
+)
+
+const scheme = "Bearer"
+
+// Extractor implements [security.Extractor] for the Bearer scheme
+// (RFC 6750 §2.1). It reads the Authorization header from the Carrier and
+// hands the opaque token to a [TokenVerifier] downstream.
+type Extractor struct{}
+
+// NewExtractor returns the canonical zero-config Extractor reading the
+// Authorization header.
+func NewExtractor() Extractor { return Extractor{} }
+
+// Extract implements [security.Extractor]. Returns (nil, nil) when no
+// Bearer credentials are present (next extractor gets a chance). Returns
+// a non-nil Authentication carrying the raw token when the header is
+// well-formed; the verifier is responsible for validating the token shape.
+func (Extractor) Extract(_ context.Context, c security.Carrier) (security.Authentication, error) {
+	header := c.Get("Authorization")
+	if header == "" {
+		return nil, nil
+	}
+
+	token, ok := extractValue(scheme, header)
+	if !ok {
+		return nil, nil
+	}
+
+	if token == "" {
+		return nil, nil
+	}
+
+	return New(token), nil
+}
+
+// extractValue strips a case-insensitive scheme prefix from an Authorization
+// header value. Local copy so this module stays free of an httpsec dep.
+func extractValue(scheme, header string) (string, bool) {
+	prefix := scheme + " "
+	if len(header) < len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+		return "", false
+	}
+
+	return header[len(prefix):], true
+}
diff --git a/bearer/extractor_test.go b/bearer/extractor_test.go
new file mode 100644
index 0000000..0a4776c
--- /dev/null
+++ b/bearer/extractor_test.go
@@ -0,0 +1,88 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer_test
+
+import (
+	"context"
+	"net/textproto"
+	"testing"
+
+	"github.com/hyperscale-stack/security/bearer"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mapCarrier is a minimal security.Carrier replica for bearer tests.
+type mapCarrier struct{ vals map[string][]string }
+
+func newCarrier() *mapCarrier { return &mapCarrier{vals: make(map[string][]string)} }
+
+func (c *mapCarrier) key(k string) string { return textproto.CanonicalMIMEHeaderKey(k) }
+func (c *mapCarrier) Get(k string) string {
+	if vs := c.vals[c.key(k)]; len(vs) > 0 {
+		return vs[0]
+	}
+
+	return ""
+}
+func (c *mapCarrier) Values(k string) []string { return c.vals[c.key(k)] }
+func (c *mapCarrier) Set(k, v string)          { c.vals[c.key(k)] = []string{v} }
+func (c *mapCarrier) Add(k, v string)          { c.vals[c.key(k)] = append(c.vals[c.key(k)], v) }
+
+func TestExtractorReturnsNilWhenHeaderAbsent(t *testing.T) {
+	t.Parallel()
+
+	got, err := bearer.NewExtractor().Extract(context.Background(), newCarrier())
+	require.NoError(t, err)
+	assert.Nil(t, got)
+}
+
+func TestExtractorReturnsNilForNonBearerSchemes(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Basic xxx")
+
+	got, err := bearer.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	assert.Nil(t, got)
+}
+
+func TestExtractorParsesBearerHeader(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Bearer eyJabc.def.ghi")
+
+	got, err := bearer.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+
+	ba := got.(bearer.Authentication)
+	assert.Equal(t, "eyJabc.def.ghi", ba.Token())
+	assert.False(t, ba.IsAuthenticated())
+}
+
+func TestExtractorCaseInsensitiveOnScheme(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "bearer abc")
+
+	got, err := bearer.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	assert.NotNil(t, got)
+}
+
+func TestExtractorIgnoresEmptyToken(t *testing.T) {
+	t.Parallel()
+
+	c := newCarrier()
+	c.Set("Authorization", "Bearer ")
+
+	got, err := bearer.NewExtractor().Extract(context.Background(), c)
+	require.NoError(t, err)
+	assert.Nil(t, got, "Bearer with empty token must let downstream extractors try")
+}
diff --git a/bearer/go.mod b/bearer/go.mod
new file mode 100644
index 0000000..b177fc7
--- /dev/null
+++ b/bearer/go.mod
@@ -0,0 +1,23 @@
+module github.com/hyperscale-stack/security/bearer
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../
diff --git a/bearer/go.sum b/bearer/go.sum
new file mode 100644
index 0000000..56bdaa2
--- /dev/null
+++ b/bearer/go.sum
@@ -0,0 +1,40 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/bearer/verifier.go b/bearer/verifier.go
new file mode 100644
index 0000000..e03ca7c
--- /dev/null
+++ b/bearer/verifier.go
@@ -0,0 +1,34 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package bearer
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// TokenVerifier validates an opaque bearer token and returns the
+// [security.Authentication] it represents. Implementations come from other
+// modules:
+//
+//   - github.com/hyperscale-stack/security/jwt — local JWT verifier
+//   - introspection-backed verifiers calling RFC 7662 endpoints
+//   - custom verifiers calling an internal auth service
+//
+// Errors MUST wrap one of [security.ErrTokenExpired], [security.ErrTokenNotFound]
+// or [security.ErrInvalidCredentials] so the default HTTP / gRPC error mappers
+// translate them to the right status / code.
+type TokenVerifier interface {
+	Verify(ctx context.Context, token string) (security.Authentication, error)
+}
+
+// VerifierFunc adapts a function to [TokenVerifier].
+type VerifierFunc func(ctx context.Context, token string) (security.Authentication, error)
+
+// Verify implements [TokenVerifier].
+func (f VerifierFunc) Verify(ctx context.Context, token string) (security.Authentication, error) {
+	return f(ctx, token)
+}
diff --git a/carrier.go b/carrier.go
new file mode 100644
index 0000000..fce27ef
--- /dev/null
+++ b/carrier.go
@@ -0,0 +1,33 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+// Carrier abstracts a transport-level message (an HTTP request, gRPC metadata,
+// a queue envelope) from which credentials can be read and security artifacts
+// (challenges, cookies, headers) can be written.
+//
+// The interface mimics http.Header semantics so that the HTTP adapter is a
+// thin wrapper. For transports that do not naturally support multi-valued
+// keys (e.g. websocket frames), implementations MAY collapse Values() to a
+// single-element slice and treat Add() as Set().
+//
+// Implementations MUST be safe for concurrent reads but MAY require external
+// synchronization for writes — adapters are expected to wrap a request scope,
+// which is serial by construction.
+type Carrier interface {
+	// Get returns the first value associated with the given key, or the
+	// empty string if absent. Keys are case-insensitive in the HTTP sense.
+	Get(key string) string
+
+	// Values returns all values associated with the given key, or a nil
+	// slice if absent. The caller MUST NOT mutate the returned slice.
+	Values(key string) []string
+
+	// Set replaces all values associated with the given key.
+	Set(key, value string)
+
+	// Add appends a value to the list associated with the given key.
+	Add(key, value string)
+}
diff --git a/clock.go b/clock.go
new file mode 100644
index 0000000..c5fcc62
--- /dev/null
+++ b/clock.go
@@ -0,0 +1,24 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "time"
+
+// Clock abstracts time.Now to make time-sensitive code (expiry checks, TTLs,
+// token rotation windows) deterministic in tests. Implementations MUST be
+// safe for concurrent use.
+type Clock interface {
+	Now() time.Time
+}
+
+// SystemClock is the default Clock returning time.Now().
+type SystemClock struct{}
+
+// Now returns the current wall-clock time.
+func (SystemClock) Now() time.Time { return time.Now() }
+
+// DefaultClock is the package-level Clock used when none is supplied via
+// configuration. It is a value, not a pointer, so it is safe to copy.
+var DefaultClock Clock = SystemClock{}
diff --git a/clock_test.go b/clock_test.go
new file mode 100644
index 0000000..6c656f1
--- /dev/null
+++ b/clock_test.go
@@ -0,0 +1,32 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSystemClockReturnsCurrentTime(t *testing.T) {
+	t.Parallel()
+
+	clock := security.SystemClock{}
+	before := time.Now()
+	got := clock.Now()
+	after := time.Now()
+
+	assert.False(t, got.Before(before), "Now() must not predate the call site")
+	assert.False(t, got.After(after), "Now() must not postdate the call site")
+}
+
+func TestDefaultClockIsSystemClock(t *testing.T) {
+	t.Parallel()
+
+	_, ok := security.DefaultClock.(security.SystemClock)
+	assert.True(t, ok, "DefaultClock should be a SystemClock value")
+}
diff --git a/context.go b/context.go
new file mode 100644
index 0000000..5aae819
--- /dev/null
+++ b/context.go
@@ -0,0 +1,35 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "context"
+
+// authCtxKey is the private key used to store an [Authentication] in a
+// context.Context. The unexported type guarantees that no other package can
+// shadow or read the value without going through the accessors below.
+type authCtxKey struct{}
+
+// WithAuthentication returns a copy of ctx with auth attached. Subsequent
+// calls overwrite the previous value; this is the expected behavior when an
+// authenticator promotes an unauthenticated value to an authenticated one.
+//
+// Passing a nil Authentication clears the slot — useful for "logout"
+// middlewares.
+func WithAuthentication(ctx context.Context, auth Authentication) context.Context {
+	return context.WithValue(ctx, authCtxKey{}, auth)
+}
+
+// FromContext returns the [Authentication] stored in ctx and a boolean
+// indicating whether one was present. When the slot is empty, it returns
+// the anonymous authentication (see [Anonymous]) so callers can rely on a
+// non-nil value without a nil check.
+func FromContext(ctx context.Context) (Authentication, bool) {
+	v, ok := ctx.Value(authCtxKey{}).(Authentication)
+	if !ok || v == nil {
+		return Anonymous(), false
+	}
+
+	return v, true
+}
diff --git a/context_test.go b/context_test.go
new file mode 100644
index 0000000..7be4f01
--- /dev/null
+++ b/context_test.go
@@ -0,0 +1,65 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestFromContextWithoutStoredValueReturnsAnonymous(t *testing.T) {
+	t.Parallel()
+
+	auth, ok := security.FromContext(context.Background())
+
+	assert.False(t, ok, "ok must be false when nothing was stored")
+	assert.Equal(t, security.Anonymous(), auth, "must fall back to Anonymous()")
+	assert.False(t, auth.IsAuthenticated())
+}
+
+func TestWithAuthenticationRoundtrip(t *testing.T) {
+	t.Parallel()
+
+	stored := newFakeAuth("alice", "ROLE_USER").withAuthenticated()
+
+	ctx := security.WithAuthentication(context.Background(), stored)
+
+	got, ok := security.FromContext(ctx)
+
+	assert.True(t, ok)
+	assert.Equal(t, stored, got)
+	assert.True(t, got.IsAuthenticated())
+}
+
+func TestWithAuthenticationNilClearsTheSlot(t *testing.T) {
+	t.Parallel()
+
+	stored := newFakeAuth("alice").withAuthenticated()
+	ctx := security.WithAuthentication(context.Background(), stored)
+	ctx = security.WithAuthentication(ctx, nil)
+
+	got, ok := security.FromContext(ctx)
+
+	assert.False(t, ok)
+	assert.Equal(t, security.Anonymous(), got)
+}
+
+func TestWithAuthenticationOverwrites(t *testing.T) {
+	t.Parallel()
+
+	first := newFakeAuth("alice").withAuthenticated()
+	second := newFakeAuth("bob").withAuthenticated()
+
+	ctx := security.WithAuthentication(context.Background(), first)
+	ctx = security.WithAuthentication(ctx, second)
+
+	got, ok := security.FromContext(ctx)
+
+	assert.True(t, ok)
+	assert.Equal(t, second, got)
+}
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..0f23b3b
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,166 @@
+# Architecture
+
+`hyperscale-stack/security` is a transport-agnostic authentication and
+authorization toolkit for Go. It is built as a **multi-module Go workspace**:
+one core module plus satellite modules for transports, schemes, and stores.
+Consumers import only the pieces they need; the core stays free of heavy
+transitive dependencies.
+
+## Design goals
+
+- **Transport-agnostic core.** The authentication pipeline knows nothing
+  about `net/http` or gRPC. Transports are thin adapters.
+- **Small, immutable interfaces.** `Authentication` is read-only; state
+  changes produce new values. No mutable `interface{}` credential bag.
+- **Composable authorization.** A Voter / `AccessDecisionManager` model
+  (Affirmative, Consensus, Unanimous) instead of ad-hoc role checks.
+- **Lean dependency graph.** Each module declares the minimum it needs;
+  the core is stdlib + `go.opentelemetry.io/otel`.
+- **Observability built in.** OpenTelemetry spans are emitted directly by
+  each module — there is no separate audit/event abstraction.
+
+## Module map
+
+| Path                      | Import path                                                  | Purpose                                                              |
+| ------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `.`                       | `github.com/hyperscale-stack/security`                       | Core: `Authentication`, `Engine`, `Manager`, `Voter`, `AccessDecisionManager` |
+| `./http`                  | `…/security/http`                                            | `httpsec` — `net/http` middleware + carrier                          |
+| `./grpc`                  | `…/security/grpc`                                            | `grpcsec` — unary/stream interceptors + carrier                      |
+| `./basic`                 | `…/security/basic`                                           | HTTP Basic extractor + authenticator                                 |
+| `./bearer`                | `…/security/bearer`                                          | Bearer extractor + `TokenVerifier`-based authenticator               |
+| `./password`              | `…/security/password`                                        | BCrypt + Argon2id hashers (`NeedsRehash`)                            |
+| `./jwt`                   | `…/security/jwt`                                             | `jwtsec` — JWT signer/verifier, JWKS, bearer adapter                 |
+| `./session`               | `…/security/session`                                         | Stateless encrypted cookie sessions + CSRF                           |
+| `./oauth2`                | `…/security/oauth2`                                          | OAuth2 server: profiles, grants, client auth, endpoints              |
+| `./oauth2/store/sql`      | `…/security/oauth2/store/sql`                                | Production `oauth2.Storage` on `database/sql`                        |
+| `./oauth2/store/redis`    | `…/security/oauth2/store/redis`                              | Production `oauth2.Storage` on Redis (Lua atomicity)                 |
+| `./examples`              | `…/security/examples`                                        | Runnable use-case demos                                              |
+| `./internal/integrations` | (private)                                                    | Cross-module end-to-end tests                                        |
+
+`oauth2/storage/memory` is a sub-package of the `oauth2` module (not a
+separate module) — it ships an in-memory `oauth2.Storage` for dev and tests.
+
+## Dependency policy
+
+```
+core (.)                ← stdlib + go.opentelemetry.io/otel
+http/                   ← core + otel
+grpc/                   ← core + otel + google.golang.org/grpc
+basic/                  ← core + password
+bearer/                 ← core
+password/               ← golang.org/x/crypto
+jwt/                    ← core + bearer + oauth2 + go-jose/v4 + otel
+session/                ← core + golang.org/x/crypto + otel
+oauth2/                 ← core + stdlib
+oauth2/store/sql/       ← oauth2 + database/sql
+oauth2/store/redis/     ← oauth2 + github.com/redis/go-redis/v9
+examples/               ← may depend on every module above
+```
+
+The core MUST NOT depend on gRPC, JOSE libraries, OAuth2, Redis, SQL
+drivers, HTTP routers, or concrete loggers. This boundary is what keeps the
+core importable from any transport.
+
+## The authentication pipeline
+
+```
+Carrier ──▶ Extractor ──▶ Authentication (pending)
+                                │
+                                ▼
+                         Manager (first-success-wins)
+                                │  ┌── Authenticator (basic)
+                                ├──┤── Authenticator (bearer)
+                                │  └── Authenticator (…)
+                                ▼
+                       Authentication (authenticated)
+                                │
+                                ▼
+            context.Context enriched via WithAuthentication
+```
+
+- **`Carrier`** abstracts a transport message — read credentials, write
+  challenges. `httpsec.Carrier` wraps `*http.Request`/`http.ResponseWriter`;
+  `grpcsec.Carrier` wraps `metadata.MD`.
+- **`Extractor`** pulls raw, unauthenticated credentials from a `Carrier`.
+  Returns `(nil, nil)` when its scheme is absent.
+- **`Authenticator`** validates a pending `Authentication` and returns an
+  authenticated one. `Supports` lets the `Manager` skip out-of-scope inputs.
+- **`Manager`** chains authenticators — first success wins, the rest are
+  skipped; all-fail produces an aggregated error.
+- **`Engine`** is the entry point: it runs the extractors, hands the result
+  to the `Manager`, and stores the outcome in the returned context.
+
+## The authorization pipeline
+
+```
+Authentication + []Attribute
+        │
+        ▼
+AccessDecisionManager  ──▶  Voter₁ ─┐
+  (Affirmative |             Voter₂ ─┼─▶ Grant / Deny / Abstain
+   Consensus |               Voter₃ ─┘
+   Unanimous)
+        │
+        ▼
+   nil | ErrAccessDenied
+```
+
+- **`Attribute`** is an opaque authorization predicate handle: `Role`,
+  `Scope`, `Authority`, `Permission`.
+- **`Voter`** inspects an `Authentication` against attributes and returns
+  `Grant`, `Deny`, or `Abstain`. Voters are pure and concurrency-safe.
+- **`AccessDecisionManager`** aggregates voter decisions under a strategy:
+  Affirmative (one grant wins), Consensus (majority), Unanimous (one deny
+  refuses).
+
+The `voter/` sub-package ships the standard catalog: `HasRole`,
+`HasAnyRole`, `HasScope`, `HasAuthority`, `HasPermission`, `Authenticated`,
+`Anonymous`, `FullyAuthenticated`, plus `And`/`Or`/`Not` combinators.
+
+## Transport adapters
+
+Adapters are deliberately thin — they translate between a transport message
+and a `Carrier`, then map security errors to transport responses.
+
+- **`httpsec`** — `Middleware` runs the `Engine` and enriches the request
+  context; `Authorize` runs an `AccessDecisionManager`. `ErrorMapper`
+  turns sentinels into HTTP status codes + `WWW-Authenticate`.
+- **`grpcsec`** — `UnaryServerInterceptor` / `StreamServerInterceptor`
+  authenticate every RPC; `UnaryAuthorize` / `StreamAuthorize` enforce an
+  ADM. `ErrorMapper` turns sentinels into `codes.Code`.
+
+## OAuth2
+
+The `oauth2` module is an authorization server, not just a provider:
+
+- **`Profile`** — `Profile20`, `Profile20BCP` (default), `Profile21Draft`.
+  The profile gates which grants and PKCE methods are allowed, and is
+  enforced at runtime on the grants — PKCE is required and the `plain`
+  transformation refused under BCP / 2.1.
+- **Grants** — `authorization_code` (PKCE), `client_credentials`,
+  `refresh_token` (rotation + reuse detection), plus the opt-in legacy
+  `password` grant (`grant.NewLegacyPassword`, refused outside `Profile20`).
+- **Client authentication** — `client_secret_basic`, `client_secret_post`,
+  `none` (public clients, PKCE required).
+- **Endpoints** — `/authorize` (RFC 6749 §3.1, `authorization_code` and the
+  opt-in legacy `implicit` flow, with an application-supplied consent hook),
+  `/token`, `/revoke` (RFC 7009), `/introspect` (RFC 7662),
+  `/.well-known/oauth-authorization-server` (RFC 8414). The endpoint path
+  prefix used in the metadata document is configurable via
+  `ServerConfig.RoutePrefix`.
+- **`Storage`** — an interface with explicit atomicity contracts
+  (`ConsumeAuthorizationCode`, `RotateRefreshToken`). Three implementations:
+  in-memory, SQL (Postgres/MySQL/SQLite), Redis (Lua scripts). All three
+  pass the shared `oauth2/storetest` conformance suite.
+
+Tokens and authorization codes are **never stored in cleartext** — the
+store only ever sees a hash.
+
+## Observability
+
+Every long-lived operation opens an OpenTelemetry span. Instrumentation
+lives directly in the module that owns the operation; there is no central
+audit package. See [observability.md](observability.md) for the full span
+catalog. No secret (password, token, code, client secret, raw session ID)
+is ever placed on a span attribute — identifiers that need correlation are
+hashed first.
diff --git a/docs/migration-from-v0.md b/docs/migration-from-v0.md
new file mode 100644
index 0000000..95c85ee
--- /dev/null
+++ b/docs/migration-from-v0.md
@@ -0,0 +1,94 @@
+# Migrating from v0
+
+The v0 stack (`authentication/`, `authorization/`, the in-tree `password`
+package, and `authentication/provider/oauth2`) was removed during the
+refactor. This guide maps the old API to the v2 stack. For the workspace
+layout and the new module list see [../MIGRATION.md](../MIGRATION.md).
+
+## Concept mapping
+
+| v0                                              | v2                                                       |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `authentication.Credential` (mutable, `any`)    | `security.Authentication` (immutable interface)           |
+| `authentication.Filter` / `OnFilter`            | `security.Extractor` — `Extract(ctx, Carrier)`            |
+| `authentication.Provider` / `Authenticate`      | `security.Authenticator` — `Authenticate(ctx, Authentication)` |
+| `authentication.Handler` (the filter loop)      | `security.Engine` + `httpsec.Middleware`                  |
+| `authorization.Option` checks                   | `voter.*` + `security.AccessDecisionManager`              |
+| `password.BCryptHasher`                         | `password.Hasher` (`NewBCryptHasher` / `NewArgon2idHasher`) |
+| `NewOAuth2AuthenticationProvider`               | `oauth2.Server` (issuer) + `bearer`/`jwtsec` (resource server) |
+
+## Authentication is now immutable
+
+v0 credentials were a mutable bag mutated in place by each filter. v2
+`Authentication` is a read-only interface; an authenticator returns a *new*
+value rather than mutating its input:
+
+```go
+// v2
+func (a *Authenticator) Authenticate(ctx context.Context, auth security.Authentication) (security.Authentication, error) {
+    // …validate…
+    return in.WithAuthenticated(user, authorities), nil // new value
+}
+```
+
+## Context is propagated everywhere
+
+Every runtime operation now takes `context.Context` as its first argument —
+`Extract`, `Authenticate`, `Hasher.Hash`/`Verify`, `UserLoader.Load`,
+`TokenVerifier.Verify`. Thread the request context through; do not use
+`context.Background()` on the request path.
+
+## The Handler loop bug is gone
+
+v0's `Handler` kept iterating filters after a successful authentication and
+silently swallowed provider errors. v2 replaces it with:
+
+- `security.Manager` — first-success-wins, then stops; all-fail produces an
+  aggregated error reachable via `errors.Is`.
+- `security.Engine` — runs extractors, calls the `Manager`, stores the
+  result in the context.
+- `httpsec.Middleware` / `grpcsec` interceptors — wire the `Engine` into a
+  transport and map failures to status codes.
+
+## Password verification reports errors
+
+v0's `Verify` returned a bare `bool`, conflating "wrong password" with
+"malformed hash". v2:
+
+```go
+ok, err := hasher.Verify(ctx, encodedHash, password)
+// err != nil  -> malformed hash / unknown algorithm / cancelled
+// err == nil  -> ok tells you whether the password matched
+```
+
+Call `hasher.NeedsRehash(encodedHash)` after a successful verify to upgrade
+stored hashes when you raise the cost factor.
+
+## Authorization: from option checks to voters
+
+Replace ad-hoc role checks with attributes, voters, and an
+`AccessDecisionManager`:
+
+```go
+adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+mux.Handle("/admin", httpsec.Authorize(adm, security.Role("ADMIN"))(adminHandler))
+```
+
+## OAuth2: provider split into issuer and resource server
+
+v0's `NewOAuth2AuthenticationProvider` mixed token issuance and token
+validation. v2 separates them:
+
+- **Authorization server** — `oauth2.NewServer(cfg)` exposes
+  `TokenHandler`, `RevokeHandler`, `IntrospectHandler`, `MetadataHandler`.
+- **Resource server** — validate incoming bearer tokens with `bearer` +
+  a `TokenVerifier` (`jwtsec` for JWT access tokens, or introspection).
+
+See [examples/oauth2](../examples/oauth2) for both halves wired together,
+and the [examples/](../examples) directory for the other per-scenario demos.
+
+## Transport imports
+
+The v0 example imported `gorilla/mux`. v2 examples use the standard
+`net/http.ServeMux` — no third-party router is required, and none is a
+dependency of any module.
diff --git a/docs/observability.md b/docs/observability.md
new file mode 100644
index 0000000..eed0f34
--- /dev/null
+++ b/docs/observability.md
@@ -0,0 +1,96 @@
+# Observability
+
+Every module instruments its long-lived operations with OpenTelemetry
+spans. Instrumentation lives directly inside the module that owns the
+operation — there is no central audit or event-sink package. To collect the
+spans, install a `TracerProvider` from the OpenTelemetry SDK in your
+application; the library uses the global provider via `otel.Tracer`.
+
+## Instrumentation scopes
+
+Each module reports under a stable instrumentation scope (the tracer name):
+
+| Module    | Instrumentation scope                          |
+| --------- | ---------------------------------------------- |
+| core      | `github.com/hyperscale-stack/security`         |
+| `httpsec` | `github.com/hyperscale-stack/security/http`    |
+| `grpcsec` | `github.com/hyperscale-stack/security/grpc`    |
+| `jwtsec`  | `github.com/hyperscale-stack/security/jwt`     |
+| `session` | `github.com/hyperscale-stack/security/session` |
+
+The `basic`, `bearer`, `password` and `oauth2` modules do not open spans of
+their own — keeping them free of a direct `go.opentelemetry.io/otel`
+dependency. Basic/Bearer authentication is still observable: the core
+`security.Manager.Authenticate` span records which authenticator ran via
+the `security.authenticator.name` attribute and an `authenticator.try`
+event per candidate. OAuth2 HTTP endpoints are observable through the host
+server's HTTP instrumentation (e.g. `otelhttp`).
+
+## Span catalog
+
+### Core — `github.com/hyperscale-stack/security`
+
+| Span                                   | When                                   | Attributes                                                                       | Error status                                              |
+| --------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `security.Engine.Process`               | `Engine.Process` — extract + authenticate | `security.extractors.count` (int), `security.authenticated` (bool)                | `ErrNoExtractor`, extractor error, or manager error        |
+| `security.Manager.Authenticate`         | `Manager.Authenticate` — chain authenticators | `security.authenticators.count` (int), `security.authenticated` (bool, on success), `security.authenticator.name` (string, on success); event `authenticator.try` per candidate | `ErrUnsupportedCredential`, `ErrAuthenticatorRefused`      |
+| `security.AccessDecisionManager.Decide` | `AccessDecisionManager.Decide`          | `security.strategy` (string), `security.attributes` (string, joined), `security.decision` (string) | `ErrAccessDenied` when the final decision is not Grant     |
+
+`security.principal.subject` is a **reserved** attribute key. It is not
+emitted by default — subject identifiers are PII and high-cardinality. Wire
+it yourself only behind a deliberate, low-cardinality (hashed) opt-in.
+
+### HTTP — `github.com/hyperscale-stack/security/http`
+
+| Span                | When                          | Attributes                                                          | Error status            |
+| ------------------- | ----------------------------- | -------------------------------------------------------------------- | ----------------------- |
+| `httpsec.Middleware` | Per request through `Middleware` | `http.method` (string), `http.route` (string), `security.handled` (bool) | inherited from the core |
+
+`httpsec.Middleware` is the parent span of the core `security.Engine.*`
+spans for that request. `httpsec.Authorize` does **not** open its own span —
+it delegates to `security.AccessDecisionManager.Decide`.
+
+### gRPC — `github.com/hyperscale-stack/security/grpc`
+
+| Span                   | When                                            | Attributes                                                  | Error status            |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------ | ----------------------- |
+| `grpcsec.Authenticate` | Per RPC, unary and stream interceptors          | `rpc.method` (string), `security.authenticated` (bool)       | inherited from the core |
+| `grpcsec.Authorize`    | `UnaryAuthorize` / `StreamAuthorize`            | none directly — delegates to `security.AccessDecisionManager.Decide` | inherited from the core |
+
+`grpcsec` deliberately does **not** open an `rpc` span — that belongs to
+`otelgrpc`, which you compose alongside these interceptors.
+
+### JWT — `github.com/hyperscale-stack/security/jwt`
+
+| Span                  | When               | Attributes                                              | Error status                                                        |
+| --------------------- | ------------------ | -------------------------------------------------------- | --------------------------------------------------------------------- |
+| `jwtsec.Signer.Sign`  | `Signer.Sign`      | `jwt.alg` (string), `jwt.kid` (string)                  | —                                                                     |
+| `jwtsec.Verifier.Verify` | `Verifier.Verify` | `jwt.alg` (string), `jwt.kid` (string), `jwt.iss` (string) | parse, multi-signature, disallowed alg, unknown kid, bad signature, malformed payload, claim validation |
+
+### Session — `github.com/hyperscale-stack/security/session`
+
+| Span                     | When                | Attributes                                                       | Error status |
+| ------------------------ | ------------------- | ----------------------------------------------------------------- | ------------ |
+| `session.Manager.Login`  | `Manager.Login`     | `session.id_hash` (string)                                        | —            |
+| `session.Manager.Get`    | `Manager.Get`       | `session.id_hash` (string, on success)                            | —            |
+| `session.Manager.Touch`  | `Manager.Touch`     | none                                                              | —            |
+| `session.Manager.Rotate` | `Manager.Rotate`    | `session.old_id_hash` (string), `session.new_id_hash` (string)    | —            |
+| `session.Manager.Logout` | `Manager.Logout`    | none                                                              | —            |
+
+Session IDs are never placed on a span raw — `session.*id_hash` attributes
+carry a non-reversible SHA-256 fingerprint for correlation only.
+
+## Secrets policy
+
+No span attribute ever carries a secret: cleartext passwords, access or
+refresh tokens, authorization codes, client secrets, or raw session IDs.
+Where correlation is genuinely needed, the value is hashed first
+(`session.id_hash`). When you add your own instrumentation around this
+library, keep the same rule.
+
+## Verifying spans in tests
+
+The test suites use the OpenTelemetry SDK's in-memory exporter
+(`tracetest.NewSpanRecorder`) to assert span names, attributes, and status.
+Apply the same pattern in your own integration tests, or run any example
+with `OTEL_TRACES_EXPORTER=console` to see the spans on stdout.
diff --git a/docs/security-considerations.md b/docs/security-considerations.md
new file mode 100644
index 0000000..fa53c65
--- /dev/null
+++ b/docs/security-considerations.md
@@ -0,0 +1,119 @@
+# Security considerations
+
+This document records the security posture of the library: the defaults it
+ships, the attacks it defends against, and the choices left to the operator.
+
+## Password hashing
+
+Two `password.Hasher` implementations are shipped:
+
+- **bcrypt** — `NewBCryptHasher(cost)`. Constant-time comparison is provided
+  by `golang.org/x/crypto/bcrypt`.
+- **Argon2id** — `NewArgon2idHasher(params)`. The default profile
+  (`DefaultArgon2idParams`) follows RFC 9106 §4 / OWASP 2024: memory 19 MiB,
+  time 2, parallelism 1, 32-byte key, 16-byte salt.
+
+`NeedsRehash` lets a login flow transparently upgrade a stored hash when the
+operator raises the cost factor. Call it after a successful `Verify` and
+re-hash if it returns true.
+
+A plain mismatch returns `(false, nil)` — only malformed input or context
+cancellation produces an error. Never store or log the cleartext password.
+
+## Account enumeration
+
+`basic.Authenticator` collapses every failure — unknown user, loader error,
+disabled/locked/expired account, password mismatch — into a single
+`security.ErrInvalidCredentials` at the client boundary. The detailed cause
+stays in the wrapped error chain for server-side telemetry only. Do not
+mirror the detailed cause in the HTTP/gRPC response.
+
+## JWT
+
+`jwtsec` defends against the two classic JWT attacks:
+
+- **`alg=none`** — rejected. The verifier parses with an explicit algorithm
+  allowlist, so an unsigned token never reaches key resolution.
+- **Algorithm confusion** (HS256 forged with an RSA public key) — the
+  default allowlist is asymmetric only: `RS256/384/512`, `PS256/384/512`,
+  `ES256/384/512`, `EdDSA`. HMAC algorithms are **not** allowed by default;
+  enable them with `WithAllowedAlgorithms` only when both ends share a
+  symmetric secret and you understand the trade-off.
+
+The verifier also validates `iss`, `aud`, `exp`, `nbf`, and `iat` with a
+configurable clock skew, and resolves keys by `kid` against a JWKS provider
+(static or cached-remote).
+
+## OAuth2
+
+- **PKCE** — `authorization_code` requires PKCE. `S256` is the only method
+  allowed under `Profile21Draft`; `plain` is accepted (with a warning) only
+  under the looser profiles.
+- **Refresh-token rotation** — every refresh issues a new token and
+  invalidates the old one. Re-use of an already-rotated token is treated as
+  theft: the whole token family is revoked (`RotateRefreshToken` returns
+  `ErrRefreshTokenReused`).
+- **Token storage** — access tokens, refresh tokens, and authorization
+  codes are stored **hashed only** (SHA-256, via `oauth2.HashToken`). The
+  store never sees cleartext, so a database compromise does not yield
+  usable tokens. Tokens carry ≥ 128 bits of entropy, so the bare hash is
+  preimage- and brute-force-resistant.
+- **Atomic single-use** — `ConsumeAuthorizationCode` and
+  `RotateRefreshToken` are atomic in every `Storage` implementation (SQL
+  transactions, Redis Lua scripts). Concurrent use of the same code/token
+  yields exactly one winner; the conformance suite verifies this under
+  100-goroutine races.
+- **Profiles** — `Profile20BCP` (the default) follows the OAuth 2.0
+  Security BCP: it refuses the `implicit` grant. `Profile21Draft`
+  additionally refuses the `password` grant. Legacy grants are opt-in and
+  refused outright under the stricter profile.
+- **Client authentication** — `client_secret_basic` / `client_secret_post`
+  compare secrets in constant time. Public clients use `none` and MUST use
+  PKCE.
+
+## Sessions
+
+`session` issues a **stateless encrypted cookie** — there is no server-side
+session store to compromise or scale.
+
+- **Confidentiality + integrity** — the cookie payload is sealed with
+  AES-256-GCM (AEAD): tampering fails decryption, it is not merely detected.
+- **Key rotation** — the `Codec` accepts an ordered key list. New cookies
+  are sealed with the first key; decryption is attempted against every key,
+  so a key can be retired gracefully.
+- **Cookie attributes** — defaults are conservative: `Secure=true`,
+  `HttpOnly=true`, `SameSite=Lax`. Disable `Secure` only for local plain-HTTP
+  development.
+- **Session fixation** — `Manager.Rotate` mints a fresh session ID; call it
+  immediately after a privilege change (login). The ID never appears raw in
+  a span — only a SHA-256 fingerprint.
+- **CSRF** — the synchronizer-token helper (`CSRFToken` / `VerifyCSRF`)
+  compares tokens in constant time. The session cookie being `HttpOnly`
+  keeps the token out of reach of XSS.
+- **Size** — the whole session is JSON-encoded into the cookie; browsers
+  cap a cookie near 4 KiB. Keep `Values` small.
+
+## Transport error mapping
+
+Error mappers return terse, code-first responses. HTTP emits a status code
+plus a `WWW-Authenticate` challenge; gRPC emits a `codes.Code`. Clients are
+expected to branch on the code, not parse the message — the message never
+leaks why authentication failed.
+
+## Observability
+
+No secret is ever placed on a span attribute or log line. See
+[observability.md](observability.md) for the secrets policy and the full
+span catalog.
+
+## Operator checklist
+
+- [ ] Pick a password hasher and review its cost against current hardware.
+- [ ] Rotate JWT signing keys; expose them through a JWKS endpoint.
+- [ ] Keep the JWT allowlist asymmetric unless you truly need HMAC.
+- [ ] Use `Profile20BCP` or stricter; do not enable the `implicit` /
+      `password` legacy grants without a documented reason.
+- [ ] Serve over HTTPS so `Secure` cookies and bearer tokens are protected.
+- [ ] Supply at least two session keys so rotation is possible without
+      invalidating live sessions.
+- [ ] Install an OpenTelemetry `TracerProvider` to collect the spans.
diff --git a/engine.go b/engine.go
new file mode 100644
index 0000000..9edee98
--- /dev/null
+++ b/engine.go
@@ -0,0 +1,105 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import (
+	"context"
+	"fmt"
+
+	"go.opentelemetry.io/otel/codes"
+)
+
+// Engine is the high-level entry point: it drives a chain of [Extractor]s
+// against a [Carrier], hands the produced [Authentication] to its [Manager],
+// and returns a context enriched with the result so downstream handlers can
+// call [FromContext].
+//
+// Engine is safe for concurrent use.
+type Engine interface {
+	// Process runs extractors in order and consults the manager on the first
+	// non-empty result. The returned context always carries an Authentication
+	// (the anonymous one when nothing was extracted).
+	Process(ctx context.Context, c Carrier) (context.Context, Authentication, error)
+}
+
+// NewEngine returns an [Engine]. Passing zero extractors is allowed; the
+// engine will produce the anonymous authentication and return
+// [ErrNoExtractor] so callers can fail-closed if they wish.
+func NewEngine(m Manager, extractors ...Extractor) Engine {
+	cp := make([]Extractor, len(extractors))
+	copy(cp, extractors)
+
+	return &engine{manager: m, extractors: cp}
+}
+
+type engine struct {
+	manager    Manager
+	extractors []Extractor
+}
+
+// Process implements [Engine].
+func (e *engine) Process(ctx context.Context, c Carrier) (context.Context, Authentication, error) {
+	ctx, span := tracer().Start(ctx, "security.Engine.Process")
+	defer span.End()
+
+	span.SetAttributes(AttrExtractorsCount.Int(len(e.extractors)))
+
+	if len(e.extractors) == 0 {
+		span.SetStatus(codes.Error, ErrNoExtractor.Error())
+		span.RecordError(ErrNoExtractor)
+
+		ctx = WithAuthentication(ctx, Anonymous())
+
+		return ctx, Anonymous(), ErrNoExtractor
+	}
+
+	var extracted Authentication
+
+	for _, ex := range e.extractors {
+		auth, err := ex.Extract(ctx, c)
+		if err != nil {
+			span.SetStatus(codes.Error, err.Error())
+			span.RecordError(err)
+
+			ctx = WithAuthentication(ctx, Anonymous())
+
+			return ctx, Anonymous(), err
+		}
+
+		if auth != nil {
+			extracted = auth
+
+			break
+		}
+	}
+
+	if extracted == nil {
+		span.SetAttributes(AttrAuthenticated.Bool(false))
+
+		ctx = WithAuthentication(ctx, Anonymous())
+
+		return ctx, Anonymous(), nil
+	}
+
+	authed, err := e.manager.Authenticate(ctx, extracted)
+	if err != nil {
+		// Manager already attached its own span / status; propagate as-is
+		// after recording the engine-level outcome. We attach the
+		// (unauthenticated) extracted value to the context so that
+		// error-mapping middleware can inspect Kind via FromContext for
+		// richer challenges.
+		span.SetStatus(codes.Error, err.Error())
+
+		ctx = WithAuthentication(ctx, extracted)
+
+		return ctx, extracted, fmt.Errorf("security.Engine: %w", err)
+	}
+
+	span.SetAttributes(AttrAuthenticated.Bool(authed.IsAuthenticated()))
+
+	ctx = WithAuthentication(ctx, authed)
+
+	return ctx, authed, nil
+}
diff --git a/engine_test.go b/engine_test.go
new file mode 100644
index 0000000..b4f3426
--- /dev/null
+++ b/engine_test.go
@@ -0,0 +1,120 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEngineReturnsErrNoExtractorWhenNoneConfigured(t *testing.T) {
+	e := security.NewEngine(security.NewManager())
+
+	ctx, auth, err := e.Process(context.Background(), newMapCarrier())
+
+	assert.ErrorIs(t, err, security.ErrNoExtractor)
+	assert.Equal(t, security.Anonymous(), auth)
+
+	got, _ := security.FromContext(ctx)
+	assert.Equal(t, security.Anonymous(), got, "context must carry Anonymous on error")
+}
+
+func TestEngineFallsThroughToAnonymousWhenNoExtractorFinds(t *testing.T) {
+	first := scriptedExtractor{}  // (nil, nil) -> "did not apply"
+	second := scriptedExtractor{} // same
+
+	e := security.NewEngine(security.NewManager(), first, second)
+
+	ctx, auth, err := e.Process(context.Background(), newMapCarrier())
+
+	require.NoError(t, err)
+	assert.Equal(t, security.Anonymous(), auth)
+	got, _ := security.FromContext(ctx)
+	assert.Equal(t, security.Anonymous(), got,
+		"Engine stores Anonymous explicitly so downstream code can always read it")
+}
+
+func TestEngineShortCircuitsOnExtractorError(t *testing.T) {
+	boom := errors.New("malformed header")
+
+	first := scriptedExtractor{err: boom}
+	second := &countingExtractor{}
+
+	e := security.NewEngine(security.NewManager(), first, second)
+
+	_, _, err := e.Process(context.Background(), newMapCarrier())
+
+	assert.ErrorIs(t, err, boom)
+	assert.Zero(t, second.calls, "subsequent extractors must not run after an error")
+}
+
+func TestEngineHandsExtractedToManager(t *testing.T) {
+	pending := newFakeAuth("alice").withCredentials("p4ssw0rd")
+	authed := newFakeAuth("alice").withAuthenticated()
+
+	extractor := scriptedExtractor{auth: pending}
+	authn := &scriptedAuthenticator{name: "basic", result: authed}
+
+	e := security.NewEngine(security.NewManager(authn), extractor)
+
+	ctx, got, err := e.Process(context.Background(), newMapCarrier())
+
+	require.NoError(t, err)
+	assert.Equal(t, Authentication(authed), got)
+	stored, ok := security.FromContext(ctx)
+	assert.True(t, ok)
+	assert.Equal(t, Authentication(authed), stored)
+}
+
+func TestEnginePropagatesManagerError(t *testing.T) {
+	pending := newFakeAuth("alice").withCredentials("bad")
+	extractor := scriptedExtractor{auth: pending}
+	authn := &scriptedAuthenticator{name: "basic", err: security.ErrInvalidCredentials}
+
+	e := security.NewEngine(security.NewManager(authn), extractor)
+
+	ctx, got, err := e.Process(context.Background(), newMapCarrier())
+
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+	assert.Equal(t, Authentication(pending), got,
+		"failed auth returns the pre-authentication value so adapters can craft a challenge")
+	stored, _ := security.FromContext(ctx)
+	assert.Equal(t, Authentication(pending), stored)
+}
+
+func TestEngineSpanRecordsExtractorAndAuthenticationFlags(t *testing.T) {
+	authed := newFakeAuth("alice").withAuthenticated()
+	extractor := scriptedExtractor{auth: newFakeAuth("alice").withCredentials("ok")}
+	authn := &scriptedAuthenticator{name: "basic", result: authed}
+
+	e := security.NewEngine(security.NewManager(authn), extractor, scriptedExtractor{})
+
+	spans := spanRecorder(func() {
+		_, _, err := e.Process(context.Background(), newMapCarrier())
+		require.NoError(t, err)
+	})
+
+	require.GreaterOrEqual(t, len(spans), 1)
+
+	var engineSpan int = -1
+
+	for i, s := range spans {
+		if s.Name() == "security.Engine.Process" {
+			engineSpan = i
+
+			break
+		}
+	}
+
+	require.GreaterOrEqual(t, engineSpan, 0, "engine span must be emitted")
+	span := spans[engineSpan]
+	assert.Equal(t, "2", findAttr(span.Attributes(), security.AttrExtractorsCount))
+	assert.Equal(t, "true", findAttr(span.Attributes(), security.AttrAuthenticated))
+}
diff --git a/errors.go b/errors.go
new file mode 100644
index 0000000..3a85bd4
--- /dev/null
+++ b/errors.go
@@ -0,0 +1,76 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+// SecurityError is the marker interface implemented by every error returned by
+// this module's public API. Callers SHOULD use errors.Is/errors.As against the
+// sentinel values exported here rather than relying on string matching.
+//
+// The unexported method securityError() prevents foreign types from
+// accidentally satisfying the interface.
+type SecurityError interface {
+	error
+	securityError()
+}
+
+// Sentinel errors. Wrap them via fmt.Errorf("...: %w", ErrXxx) when adding
+// contextual information so errors.Is keeps working.
+var (
+	// ErrInvalidCredentials indicates that the supplied credentials could not
+	// be validated (bad password, unknown user, malformed token). Maps to
+	// HTTP 401 / gRPC Unauthenticated.
+	ErrInvalidCredentials = newSentinel("security: invalid credentials")
+
+	// ErrClientSecretMismatch indicates that an OAuth2 client presented a
+	// secret that did not match the registered value. Maps to HTTP 401.
+	ErrClientSecretMismatch = newSentinel("security: oauth2 client secret mismatch")
+
+	// ErrTokenExpired indicates that a valid token has passed its expiry.
+	// Maps to HTTP 401.
+	ErrTokenExpired = newSentinel("security: token expired")
+
+	// ErrTokenNotFound indicates that the presented token does not exist in
+	// the configured storage. Maps to HTTP 401.
+	ErrTokenNotFound = newSentinel("security: token not found")
+
+	// ErrUnsupportedCredential indicates that no provider recognized the
+	// credential type. Maps to HTTP 400.
+	ErrUnsupportedCredential = newSentinel("security: unsupported credential type")
+
+	// ErrNoExtractor indicates that the [Engine] was configured without any
+	// [Extractor]. The Engine returns the anonymous authentication and this
+	// error so that the caller can distinguish "no extractor" from "all
+	// extractors found nothing".
+	ErrNoExtractor = newSentinel("security: no extractor configured")
+
+	// ErrAuthenticatorRefused is the umbrella error returned by [Manager]
+	// when every supporting [Authenticator] rejected the credential. The
+	// individual errors are joined via errors.Join and reachable through
+	// errors.Is / errors.As.
+	ErrAuthenticatorRefused = newSentinel("security: every authenticator refused the credential")
+
+	// ErrAccessDenied indicates that authorisation voting denied access.
+	// Maps to HTTP 403 / gRPC PermissionDenied.
+	ErrAccessDenied = newSentinel("security: access denied")
+
+	// ErrInsufficientScope indicates that the principal is authenticated but
+	// does not carry the OAuth2 scope required for the resource. Maps to
+	// HTTP 403 with the "insufficient_scope" WWW-Authenticate parameter.
+	ErrInsufficientScope = newSentinel("security: insufficient scope")
+)
+
+// sentinelError is the concrete type backing every package-level sentinel.
+// Keeping the type unexported guarantees that no caller can mint new values
+// that satisfy SecurityError without going through this package.
+type sentinelError struct {
+	msg string
+}
+
+func newSentinel(msg string) *sentinelError {
+	return &sentinelError{msg: msg}
+}
+
+func (e *sentinelError) Error() string  { return e.msg }
+func (e *sentinelError) securityError() {}
diff --git a/errors_test.go b/errors_test.go
new file mode 100644
index 0000000..0b96f0a
--- /dev/null
+++ b/errors_test.go
@@ -0,0 +1,85 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSentinelErrorsAreDistinct(t *testing.T) {
+	t.Parallel()
+
+	sentinels := []error{
+		security.ErrInvalidCredentials,
+		security.ErrClientSecretMismatch,
+		security.ErrTokenExpired,
+		security.ErrTokenNotFound,
+		security.ErrUnsupportedCredential,
+	}
+
+	for i, a := range sentinels {
+		for j, b := range sentinels {
+			if i == j {
+				assert.ErrorIs(t, a, b)
+
+				continue
+			}
+
+			assert.NotErrorIs(t, a, b, "sentinels at %d and %d should be distinct", i, j)
+		}
+	}
+}
+
+func TestSentinelImplementsSecurityError(t *testing.T) {
+	t.Parallel()
+
+	var marker security.SecurityError
+	marker, ok := any(security.ErrInvalidCredentials).(security.SecurityError)
+	assert.True(t, ok)
+	assert.NotNil(t, marker)
+}
+
+func TestSentinelErrorsWrappable(t *testing.T) {
+	t.Parallel()
+
+	wrapped := fmt.Errorf("context: %w", security.ErrInvalidCredentials)
+
+	assert.ErrorIs(t, wrapped, security.ErrInvalidCredentials)
+	assert.NotErrorIs(t, wrapped, security.ErrTokenExpired)
+}
+
+func TestSentinelErrorMessages(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		err  error
+		want string
+	}{
+		{security.ErrInvalidCredentials, "security: invalid credentials"},
+		{security.ErrClientSecretMismatch, "security: oauth2 client secret mismatch"},
+		{security.ErrTokenExpired, "security: token expired"},
+		{security.ErrTokenNotFound, "security: token not found"},
+		{security.ErrUnsupportedCredential, "security: unsupported credential type"},
+	}
+
+	for _, c := range cases {
+		assert.Equal(t, c.want, c.err.Error())
+	}
+}
+
+func TestSecurityErrorInterfaceForbidsForeignTypes(t *testing.T) {
+	t.Parallel()
+
+	// A foreign error built with errors.New must NOT satisfy SecurityError —
+	// the unexported securityError() method is the gate.
+	foreign := errors.New("from outside")
+	_, ok := any(foreign).(security.SecurityError)
+	assert.False(t, ok)
+}
diff --git a/example/oauth2/go.mod b/example/oauth2/go.mod
deleted file mode 100644
index af8c5aa..0000000
--- a/example/oauth2/go.mod
+++ /dev/null
@@ -1,11 +0,0 @@
-module github.com/hyperscale-stack/security/example/oauth2
-
-go 1.16
-
-require (
-	github.com/gilcrest/alice v1.0.0
-	github.com/gorilla/mux v1.8.0
-	github.com/hyperscale-stack/security v0.0.0-20210721230237-494160d3eb0e
-)
-
-replace github.com/hyperscale-stack/security => ../../
diff --git a/example/oauth2/go.sum b/example/oauth2/go.sum
deleted file mode 100644
index 9d61a5a..0000000
--- a/example/oauth2/go.sum
+++ /dev/null
@@ -1,38 +0,0 @@
-github.com/coreos/go-systemd v0.0.0-20190321100706-95778dfbb74e/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
-github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/gilcrest/alice v1.0.0 h1:5+CasxidJEUHmgghQxLOl09uYhOlavDfDgNZhyR62LU=
-github.com/gilcrest/alice v1.0.0/go.mod h1:q5HRhK5WEyU1pDBIIfmYapVGLd/IAAPwiO8LNxKADpw=
-github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI=
-github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So=
-github.com/hyperscale-stack/secure v1.0.0 h1:ayGoa/Y/0RcAcP767WKjla1r9KlR+Tul5DPI/jE9dP0=
-github.com/hyperscale-stack/secure v1.0.0/go.mod h1:PY+BMJQI2aP+YYA3C7R0bFTS/XGJ4xPCYjBp9rEqmtQ=
-github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
-github.com/rs/zerolog v1.20.0 h1:38k9hgtUBdxFwE34yS8rTHmHBa4eN16E4DJlv177LNs=
-github.com/rs/zerolog v1.20.0/go.mod h1:IzD0RJ65iWH0w97OQQebJEvTZYvsCUm9WVLWBQrJRjo=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.3.0 h1:NGXK3lHquSN08v5vWalVI/L8XU9hdzE/G6xsrze47As=
-github.com/stretchr/objx v0.3.0/go.mod h1:qt09Ya8vawLte6SNmTgCsAVtYtaKzEcn8ATUoHMkEqE=
-github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20210220033148-5ea612d1eb83/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I=
-golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
-golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
-golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/tools v0.0.0-20190828213141-aed303cbaa74/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
-golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=
-gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/example/oauth2/main.go b/example/oauth2/main.go
deleted file mode 100644
index 0ec737b..0000000
--- a/example/oauth2/main.go
+++ /dev/null
@@ -1,59 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package main
-
-import (
-	"net/http"
-
-	"github.com/gilcrest/alice"
-	"github.com/gorilla/mux"
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/storage"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token/random"
-	"github.com/hyperscale-stack/security/authorization"
-)
-
-func main() {
-	r := mux.NewRouter()
-
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	storageProvider.SaveClient(&oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	})
-
-	// Add authentication filters
-	r.Use(authentication.FilterHandler(
-		authentication.NewBearerFilter(),
-		authentication.NewAccessTokenFilter(),
-		authentication.NewHTTPBasicFilter(),
-	))
-
-	// Add authentication handler
-	r.Use(authentication.Handler(
-		oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, storageProvider),
-	))
-
-	private := alice.New(
-		authorization.AuthorizeHandler(),
-	)
-
-	r.Handle("/protected", private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})).Methods(http.MethodGet)
-
-	r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		// public route
-	}).Methods(http.MethodGet)
-
-	if err := http.ListenAndServe(":1337", r); err != nil {
-		panic(err)
-	}
-}
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..d5ad94b
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,164 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// userAuth is an example concrete Authentication produced by a fictional
+// authenticator. The point of this example is the Engine wiring, so the type
+// is kept minimal.
+type userAuth struct {
+	sub         string
+	roles       []string
+	credentials string
+	verified    bool
+}
+
+func (u userAuth) Principal() security.Principal { return userPrincipal{sub: u.sub} }
+func (u userAuth) Credentials() any              { return u.credentials }
+func (u userAuth) Authorities() []string         { return u.roles }
+func (u userAuth) IsAuthenticated() bool         { return u.verified }
+func (u userAuth) Name() string                  { return u.sub }
+
+type userPrincipal struct{ sub string }
+
+func (p userPrincipal) Subject() string { return p.sub }
+
+// staticExtractor returns a fixed userAuth when the "X-Demo-User" header is
+// set, and (nil, nil) otherwise.
+type staticExtractor struct{}
+
+func (staticExtractor) Extract(_ context.Context, c security.Carrier) (security.Authentication, error) {
+	sub := c.Get("X-Demo-User")
+	if sub == "" {
+		return nil, nil
+	}
+
+	return userAuth{sub: sub, credentials: "password"}, nil
+}
+
+// staticAuthenticator accepts only "alice" / "password".
+type staticAuthenticator struct{}
+
+func (staticAuthenticator) AuthenticatorName() string                  { return "static" }
+func (staticAuthenticator) Supports(_ security.Authentication) bool    { return true }
+func (staticAuthenticator) Authenticate(_ context.Context, a security.Authentication) (security.Authentication, error) {
+	u, ok := a.(userAuth)
+	if !ok {
+		return a, security.ErrUnsupportedCredential
+	}
+
+	if u.sub != "alice" || u.credentials != "password" {
+		return a, security.ErrInvalidCredentials
+	}
+
+	u.roles = []string{"ROLE_USER"}
+	u.verified = true
+
+	return u, nil
+}
+
+// demoCarrier is a tiny Carrier used to drive the example without depending
+// on the http sub-module.
+type demoCarrier struct{ headers map[string]string }
+
+func (c *demoCarrier) Get(k string) string         { return c.headers[k] }
+func (c *demoCarrier) Values(k string) []string    { return []string{c.headers[k]} }
+func (c *demoCarrier) Set(k, v string)             { c.headers[k] = v }
+func (c *demoCarrier) Add(k, v string)             { c.headers[k] = v }
+
+// roleVoter implements [security.Voter] for the example. It supports any
+// attribute string starting with "role:" and grants when the principal has
+// the matching role.
+type roleVoter struct{}
+
+func (roleVoter) Supports(a security.Attribute) bool {
+	if a == nil {
+		return false
+	}
+	const prefix = "role:"
+	if len(a.String()) < len(prefix) {
+		return false
+	}
+
+	return a.String()[:len(prefix)] == prefix
+}
+
+func (roleVoter) Vote(_ context.Context, auth security.Authentication, attrs []security.Attribute) security.Decision {
+	for _, a := range attrs {
+		const prefix = "role:"
+		if len(a.String()) < len(prefix) || a.String()[:len(prefix)] != prefix {
+			continue
+		}
+
+		want := a.String()[len(prefix):]
+		for _, r := range auth.Authorities() {
+			if r == want {
+				return security.DecisionGrant
+			}
+		}
+	}
+
+	return security.DecisionDeny
+}
+
+type roleAttr string
+
+func (r roleAttr) String() string { return "role:" + string(r) }
+
+// Example_engine shows the canonical pipeline: extractor -> authenticator
+// orchestrated by the Engine, ending with an AccessDecisionManager.
+func Example_engine() {
+	engine := security.NewEngine(
+		security.NewManager(staticAuthenticator{}),
+		staticExtractor{},
+	)
+
+	carrier := &demoCarrier{headers: map[string]string{"X-Demo-User": "alice"}}
+
+	ctx, auth, err := engine.Process(context.Background(), carrier)
+	if err != nil {
+		fmt.Println("auth error:", err)
+
+		return
+	}
+
+	fmt.Printf("authenticated=%t subject=%s\n", auth.IsAuthenticated(), auth.Principal().Subject())
+
+	adm := security.NewAffirmativeDecisionManager(roleVoter{})
+	if err := adm.Decide(ctx, auth, []security.Attribute{roleAttr("ROLE_USER")}); err != nil {
+		fmt.Println("denied:", err)
+
+		return
+	}
+
+	fmt.Println("granted")
+	// Output:
+	// authenticated=true subject=alice
+	// granted
+}
+
+// ExampleNewManager illustrates first-success-wins semantics.
+func ExampleNewManager() {
+	first := security.AuthenticatorFunc(func(_ context.Context, a security.Authentication) (security.Authentication, error) {
+		return a, errors.New("first refuses")
+	})
+	second := security.AuthenticatorFunc(func(_ context.Context, a security.Authentication) (security.Authentication, error) {
+		return userAuth{sub: "bob", verified: true}, nil
+	})
+
+	m := security.NewManager(first, second)
+
+	auth, err := m.Authenticate(context.Background(), userAuth{sub: "bob"})
+	fmt.Println(auth.Name(), err)
+	// Output:
+	// bob <nil>
+}
diff --git a/examples/basic-http/main.go b/examples/basic-http/main.go
new file mode 100644
index 0000000..b82e384
--- /dev/null
+++ b/examples/basic-http/main.go
@@ -0,0 +1,148 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Command basic-http is a runnable HTTP Basic authentication demo.
+//
+// It wires the security core into a net/http server: every request is
+// authenticated against an in-memory user store, and the /admin route is
+// additionally gated by a role-based authorization decision.
+//
+// Run:
+//
+//	go run ./basic-http
+//
+// Probe — public identity behind Basic auth:
+//
+//	curl -i -u alice:alice-secret http://localhost:8080/
+//
+// Probe — admin route (alice is not an admin -> 403):
+//
+//	curl -i -u alice:alice-secret http://localhost:8080/admin
+//
+// Probe — admin route as an admin -> 200:
+//
+//	curl -i -u root:root-secret http://localhost:8080/admin
+//
+// Probe — wrong password -> 401:
+//
+//	curl -i -u alice:nope http://localhost:8080/
+package main
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"log"
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/basic"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/hyperscale-stack/security/password"
+	"github.com/hyperscale-stack/security/voter"
+)
+
+// user is an in-memory [basic.PasswordUser]. A real application would back
+// this with a database row.
+type user struct {
+	subject string
+	hash    string
+	roles   []string
+}
+
+func (u user) Subject() string            { return u.subject }
+func (u user) GetPasswordHash() string    { return u.hash }
+func (u user) IsEnabled() bool            { return true }
+func (u user) IsLocked() bool             { return false }
+func (u user) IsExpired() bool            { return false }
+func (u user) IsCredentialsExpired() bool { return false }
+
+// loader is an in-memory [basic.UserLoader].
+type loader struct{ users map[string]user }
+
+// LoadByUsername implements [basic.UserLoader]. An unknown user yields an
+// error wrapping [security.ErrInvalidCredentials] so the response is
+// indistinguishable from a wrong password (anti-enumeration).
+func (l loader) LoadByUsername(_ context.Context, username string) (basic.PasswordUser, error) {
+	u, ok := l.users[username]
+	if !ok {
+		return nil, fmt.Errorf("unknown user %q: %w", username, security.ErrInvalidCredentials)
+	}
+
+	return u, nil
+}
+
+// newServer builds the demo HTTP handler. It is separate from main so the
+// end-to-end test can exercise the exact same wiring.
+func newServer() (http.Handler, error) {
+	hasher := password.NewBCryptHasher(10)
+
+	ctx := context.Background()
+
+	aliceHash, err := hasher.Hash(ctx, "alice-secret")
+	if err != nil {
+		return nil, fmt.Errorf("hash alice: %w", err)
+	}
+
+	rootHash, err := hasher.Hash(ctx, "root-secret")
+	if err != nil {
+		return nil, fmt.Errorf("hash root: %w", err)
+	}
+
+	store := loader{users: map[string]user{
+		"alice": {subject: "alice", hash: aliceHash, roles: []string{"USER"}},        //nolint:goconst // example code, readability over deduplication
+		"root":  {subject: "root", hash: rootHash, roles: []string{"USER", "ADMIN"}}, //nolint:goconst // example code, readability over deduplication
+	}}
+
+	authenticator := basic.NewAuthenticator(store, hasher,
+		basic.WithAuthorityResolver(func(u basic.PasswordUser) []string {
+			if known, ok := u.(user); ok {
+				return known.roles
+			}
+
+			return nil
+		}),
+	)
+
+	engine := security.NewEngine(
+		security.NewManager(authenticator),
+		basic.NewExtractor(),
+	)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		auth, _ := security.FromContext(r.Context())
+
+		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+
+		//nolint:gosec // G705: name is the authenticated identity, written escaped to a text/plain body
+		fmt.Fprintf(w, "hello %s (roles: %s)\n",
+			html.EscapeString(auth.Name()), html.EscapeString(fmt.Sprint(auth.Authorities())))
+	})
+
+	admin := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth, _ := security.FromContext(r.Context())
+
+		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+
+		//nolint:gosec // G705: name is the authenticated identity, written escaped to a text/plain body
+		fmt.Fprintf(w, "admin area, welcome %s\n", html.EscapeString(auth.Name()))
+	})
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+	mux.Handle("/admin", httpsec.Authorize(adm, security.Role("ADMIN"))(admin))
+
+	return httpsec.Middleware(engine)(mux), nil
+}
+
+func main() {
+	handler, err := newServer()
+	if err != nil {
+		log.Fatalf("basic-http: %v", err)
+	}
+
+	addr := ":8080"
+	log.Printf("basic-http: listening on %s", addr)
+	log.Fatal(http.ListenAndServe(addr, handler)) //nolint:gosec // demo server, no timeouts needed
+}
diff --git a/examples/basic-http/main_test.go b/examples/basic-http/main_test.go
new file mode 100644
index 0000000..39df9bf
--- /dev/null
+++ b/examples/basic-http/main_test.go
@@ -0,0 +1,58 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBasicHTTPExample(t *testing.T) {
+	t.Parallel()
+
+	handler, err := newServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	cases := []struct {
+		name     string
+		path     string
+		user     string
+		pass     string
+		wantCode int
+	}{
+		{"authenticated identity", "/", "alice", "alice-secret", http.StatusOK},
+		{"wrong password", "/", "alice", "nope", http.StatusUnauthorized},
+		{"unknown user", "/", "ghost", "whatever", http.StatusUnauthorized},
+		{"no credentials", "/", "", "", http.StatusUnauthorized},
+		{"admin route denied for plain user", "/admin", "alice", "alice-secret", http.StatusForbidden},
+		{"admin route granted for admin", "/admin", "root", "root-secret", http.StatusOK},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			req, err := http.NewRequest(http.MethodGet, srv.URL+tc.path, nil)
+			require.NoError(t, err)
+
+			if tc.user != "" {
+				req.SetBasicAuth(tc.user, tc.pass)
+			}
+
+			resp, err := srv.Client().Do(req)
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = resp.Body.Close() })
+
+			assert.Equal(t, tc.wantCode, resp.StatusCode)
+		})
+	}
+}
diff --git a/examples/bearer-jwt/main.go b/examples/bearer-jwt/main.go
new file mode 100644
index 0000000..32e6680
--- /dev/null
+++ b/examples/bearer-jwt/main.go
@@ -0,0 +1,147 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Command bearer-jwt is a runnable JWT bearer-token demo.
+//
+// It plays both roles in one process: a tiny issuer that mints EdDSA-signed
+// JWTs, and a resource server that validates the Bearer token on every
+// request and gates one route on an OAuth2 scope.
+//
+// Run:
+//
+//	go run ./bearer-jwt
+//
+// Probe — mint a token:
+//
+//	TOKEN=$(curl -s -X POST http://localhost:8081/token | sed 's/.*"access_token":"//;s/".*//')
+//
+// Probe — call the protected route:
+//
+//	curl -i -H "Authorization: Bearer $TOKEN" http://localhost:8081/
+//
+// Probe — call the scope-gated route (token carries "resource:read"):
+//
+//	curl -i -H "Authorization: Bearer $TOKEN" http://localhost:8081/reports
+//
+// Probe — no token -> 401:
+//
+//	curl -i http://localhost:8081/
+package main
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/json"
+	"fmt"
+	"html"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	httpsec "github.com/hyperscale-stack/security/http"
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/hyperscale-stack/security/voter"
+)
+
+const (
+	issuer   = "https://issuer.example"
+	audience = "https://api.example"
+	keyID    = "demo-key"
+)
+
+// newServer builds the demo handler. The signer mints tokens, the verifier
+// validates them; in a real deployment those live in separate processes and
+// the resource server fetches the issuer's public keys over JWKS.
+func newServer() (http.Handler, error) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, fmt.Errorf("generate key: %w", err)
+	}
+
+	signer := jwtsec.NewSigner(jwtsec.PrivateKey{
+		KeyID:     keyID,
+		Algorithm: jwtsec.EdDSA,
+		Key:       priv,
+	})
+
+	jwks := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{{
+		KeyID:     keyID,
+		Algorithm: jwtsec.EdDSA,
+		Key:       pub,
+	}})
+
+	verifier := jwtsec.NewVerifier(jwks,
+		jwtsec.WithIssuer(issuer),
+		jwtsec.WithAudience(audience),
+	)
+
+	engine := security.NewEngine(
+		security.NewManager(bearer.NewAuthenticator(jwtsec.BearerVerifier(verifier, nil))),
+		bearer.NewExtractor(),
+	)
+
+	mux := http.NewServeMux()
+
+	// /token mints a demo token. A real issuer would authenticate the
+	// caller and derive the subject + scopes from the grant.
+	mux.HandleFunc("/token", func(w http.ResponseWriter, r *http.Request) {
+		now := time.Now()
+
+		token, err := signer.Sign(r.Context(), &jwtsec.StandardClaims{
+			Issuer:    issuer,
+			Subject:   "demo-user",
+			Audience:  jwtsec.Audience{audience},
+			IssuedAt:  jwtsec.NewNumericDate(now),
+			ExpiresAt: jwtsec.NewNumericDate(now.Add(time.Hour)),
+			Scope:     "resource:read",
+		})
+		if err != nil {
+			http.Error(w, "mint failed", http.StatusInternalServerError)
+
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]string{"access_token": token})
+	})
+
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		auth, _ := security.FromContext(r.Context())
+
+		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+
+		//nolint:gosec // G705: name is the authenticated identity, written escaped to a text/plain body
+		fmt.Fprintf(w, "hello %s (authorities: %s)\n",
+			html.EscapeString(auth.Name()), html.EscapeString(fmt.Sprint(auth.Authorities())))
+	})
+
+	reports := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintln(w, "here are your reports")
+	})
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasScope("resource:read"))
+	mux.Handle("/reports", httpsec.Authorize(adm, security.Scope("resource:read"))(reports))
+
+	// The /token route is public; everything else requires a valid token.
+	protected := httpsec.Middleware(engine)(mux)
+
+	root := http.NewServeMux()
+	root.Handle("/token", mux)
+	root.Handle("/", protected)
+
+	return root, nil
+}
+
+func main() {
+	handler, err := newServer()
+	if err != nil {
+		log.Fatalf("bearer-jwt: %v", err)
+	}
+
+	addr := ":8081"
+	log.Printf("bearer-jwt: listening on %s", addr)
+	log.Fatal(http.ListenAndServe(addr, handler)) //nolint:gosec // demo server, no timeouts needed
+}
diff --git a/examples/bearer-jwt/main_test.go b/examples/bearer-jwt/main_test.go
new file mode 100644
index 0000000..f998c00
--- /dev/null
+++ b/examples/bearer-jwt/main_test.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBearerJWTExample(t *testing.T) {
+	t.Parallel()
+
+	handler, err := newServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	// Mint a token via the public /token endpoint.
+	resp, err := srv.Client().Post(srv.URL+"/token", "", nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = resp.Body.Close() })
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	var minted struct {
+		AccessToken string `json:"access_token"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&minted))
+	require.NotEmpty(t, minted.AccessToken)
+
+	get := func(t *testing.T, path, token string) int {
+		t.Helper()
+
+		req, err := http.NewRequest(http.MethodGet, srv.URL+path, nil)
+		require.NoError(t, err)
+
+		if token != "" {
+			req.Header.Set("Authorization", "Bearer "+token)
+		}
+
+		r, err := srv.Client().Do(req)
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = r.Body.Close() })
+
+		return r.StatusCode
+	}
+
+	t.Run("valid token reaches the protected route", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, http.StatusOK, get(t, "/", minted.AccessToken))
+	})
+
+	t.Run("valid token carries the resource:read scope", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, http.StatusOK, get(t, "/reports", minted.AccessToken))
+	})
+
+	t.Run("missing token is rejected", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, http.StatusUnauthorized, get(t, "/", ""))
+	})
+
+	t.Run("garbage token is rejected", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, http.StatusUnauthorized, get(t, "/", "not-a-jwt"))
+	})
+}
diff --git a/examples/doc.go b/examples/doc.go
new file mode 100644
index 0000000..281652c
--- /dev/null
+++ b/examples/doc.go
@@ -0,0 +1,20 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package examples is a container module hosting the use-case examples
+// shipped alongside the security library. Each example is a sub-package
+// with a runnable main; the package doc comment of every main documents the
+// curl / grpcurl probes.
+//
+// The examples module is free to depend on every other module of the
+// workspace (this is the only place where doing so is acceptable).
+//
+// Available examples:
+//
+//   - basic-http   — HTTP Basic authentication + role-based authorization.
+//   - bearer-jwt   — JWT issuance and Bearer-token validation, scope gating.
+//   - grpc-bearer  — gRPC unary interceptors authenticating a Bearer JWT.
+//   - session-web  — cookie-session login form with a CSRF-protected logout.
+//   - oauth2       — OAuth2 authorization server + Bearer resource server.
+package examples
diff --git a/examples/go.mod b/examples/go.mod
new file mode 100644
index 0000000..3daa4e9
--- /dev/null
+++ b/examples/go.mod
@@ -0,0 +1,56 @@
+module github.com/hyperscale-stack/security/examples
+
+go 1.26
+
+// Examples may depend on every other module of the workspace.
+replace github.com/hyperscale-stack/security => ../
+
+replace github.com/hyperscale-stack/security/http => ../http
+
+replace github.com/hyperscale-stack/security/grpc => ../grpc
+
+replace github.com/hyperscale-stack/security/basic => ../basic
+
+replace github.com/hyperscale-stack/security/bearer => ../bearer
+
+replace github.com/hyperscale-stack/security/password => ../password
+
+replace github.com/hyperscale-stack/security/jwt => ../jwt
+
+replace github.com/hyperscale-stack/security/session => ../session
+
+replace github.com/hyperscale-stack/security/oauth2 => ../oauth2
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/basic v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/bearer v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/grpc v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/http v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/jwt v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/oauth2 v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/password v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/session v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	google.golang.org/grpc v1.69.2
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
+	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8 // indirect
+	google.golang.org/protobuf v1.36.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
diff --git a/examples/go.sum b/examples/go.sum
new file mode 100644
index 0000000..a629241
--- /dev/null
+++ b/examples/go.sum
@@ -0,0 +1,58 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8 h1:TqExAhdPaB60Ux47Cn0oLV07rGnxZzIsaRhQaqS666A=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8/go.mod h1:lcTa1sDdWEIHMWlITnIczmw5w60CF9ffkb8Z+DVmmjA=
+google.golang.org/grpc v1.69.2 h1:U3S9QEtbXC0bYNvRtcoklF3xGtLViumSYxWykJS+7AU=
+google.golang.org/grpc v1.69.2/go.mod h1:vyjdE6jLBI76dgpDojsFGNaHlxdjXN9ghpnd2o7JGZ4=
+google.golang.org/protobuf v1.36.1 h1:yBPeRvTftaleIgM3PZ/WBIZ7XM/eEYAaEyCwvyjq/gk=
+google.golang.org/protobuf v1.36.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/examples/grpc-bearer/main.go b/examples/grpc-bearer/main.go
new file mode 100644
index 0000000..d738be5
--- /dev/null
+++ b/examples/grpc-bearer/main.go
@@ -0,0 +1,139 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Command grpc-bearer is a runnable gRPC Bearer-token demo.
+//
+// It exposes the standard gRPC health service behind two interceptors: one
+// authenticates every RPC against a JWT, the other authorizes it against an
+// OAuth2 scope. The process also mints a demo token at start-up.
+//
+// Run:
+//
+//	go run ./grpc-bearer
+//
+// The server logs a ready-to-use token. Probe it with grpcurl:
+//
+//	grpcurl -plaintext \
+//	    -H "authorization: Bearer <TOKEN>" \
+//	    localhost:9090 grpc.health.v1.Health/Check
+//
+// Without the token the call fails with codes.Unauthenticated; with a token
+// that lacks the "health:read" scope it fails with codes.PermissionDenied.
+package main
+
+import (
+	"context"
+	"crypto/ed25519"
+	"crypto/rand"
+	"fmt"
+	"log"
+	"net"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/hyperscale-stack/security/voter"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/health"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+)
+
+const (
+	issuer   = "https://issuer.example"
+	audience = "https://grpc.example"
+	keyID    = "demo-key"
+	scope    = "health:read"
+)
+
+// minter signs a demo JWT carrying the requested scope.
+type minter func(scope string) (string, error)
+
+// newServer builds the gRPC server with the security interceptors and
+// returns a token minter sharing the server's signing key. It is separate
+// from main so the end-to-end test can serve it over an in-memory listener.
+func newServer() (*grpc.Server, minter, error) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, nil, fmt.Errorf("generate key: %w", err)
+	}
+
+	signer := jwtsec.NewSigner(jwtsec.PrivateKey{
+		KeyID:     keyID,
+		Algorithm: jwtsec.EdDSA,
+		Key:       priv,
+	})
+
+	jwks := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{{
+		KeyID:     keyID,
+		Algorithm: jwtsec.EdDSA,
+		Key:       pub,
+	}})
+
+	verifier := jwtsec.NewVerifier(jwks,
+		jwtsec.WithIssuer(issuer),
+		jwtsec.WithAudience(audience),
+	)
+
+	engine := security.NewEngine(
+		security.NewManager(bearer.NewAuthenticator(jwtsec.BearerVerifier(verifier, nil))),
+		bearer.NewExtractor(),
+	)
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasScope(scope))
+
+	srv := grpc.NewServer(
+		grpc.ChainUnaryInterceptor(
+			grpcsec.UnaryServerInterceptor(engine),
+			grpcsec.UnaryAuthorize(adm, []security.Attribute{security.Scope(scope)}),
+		),
+	)
+	healthpb.RegisterHealthServer(srv, health.NewServer())
+
+	mint := func(grant string) (string, error) {
+		now := time.Now()
+
+		token, err := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+			Issuer:    issuer,
+			Subject:   "demo-user",
+			Audience:  jwtsec.Audience{audience},
+			IssuedAt:  jwtsec.NewNumericDate(now),
+			ExpiresAt: jwtsec.NewNumericDate(now.Add(time.Hour)),
+			Scope:     grant,
+		})
+		if err != nil {
+			return "", fmt.Errorf("mint token: %w", err)
+		}
+
+		return token, nil
+	}
+
+	return srv, mint, nil
+}
+
+func main() {
+	srv, mint, err := newServer()
+	if err != nil {
+		log.Fatalf("grpc-bearer: %v", err)
+	}
+
+	token, err := mint(scope)
+	if err != nil {
+		log.Fatalf("grpc-bearer: %v", err)
+	}
+
+	addr := ":9090"
+
+	var lc net.ListenConfig
+
+	lis, err := lc.Listen(context.Background(), "tcp", addr) //nolint:gosec // G102: demo server, binding to all interfaces is intentional
+	if err != nil {
+		log.Fatalf("grpc-bearer: listen: %v", err)
+	}
+
+	log.Printf("grpc-bearer: listening on %s", addr)
+	log.Printf("grpc-bearer: demo token: %s", token)
+	log.Fatal(srv.Serve(lis))
+}
diff --git a/examples/grpc-bearer/main_test.go b/examples/grpc-bearer/main_test.go
new file mode 100644
index 0000000..0fbff9a
--- /dev/null
+++ b/examples/grpc-bearer/main_test.go
@@ -0,0 +1,83 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"context"
+	"net"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/credentials/insecure"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+func TestGRPCBearerExample(t *testing.T) {
+	t.Parallel()
+
+	srv, mint, err := newServer()
+	require.NoError(t, err)
+
+	lis := bufconn.Listen(1 << 20)
+	go func() { _ = srv.Serve(lis) }()
+	t.Cleanup(srv.Stop)
+
+	conn, err := grpc.NewClient(
+		"passthrough:///bufnet",
+		grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
+			return lis.DialContext(ctx)
+		}),
+		grpc.WithTransportCredentials(insecure.NewCredentials()),
+	)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = conn.Close() })
+
+	client := healthpb.NewHealthClient(conn)
+
+	goodToken, err := mint(scope)
+	require.NoError(t, err)
+
+	wrongScopeToken, err := mint("other:read")
+	require.NoError(t, err)
+
+	check := func(t *testing.T, token string) error {
+		t.Helper()
+
+		ctx := context.Background()
+		if token != "" {
+			ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token)
+		}
+
+		_, err := client.Check(ctx, &healthpb.HealthCheckRequest{})
+
+		return err
+	}
+
+	t.Run("valid token with the right scope succeeds", func(t *testing.T) {
+		t.Parallel()
+		assert.NoError(t, check(t, goodToken))
+	})
+
+	t.Run("missing token is unauthenticated", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, codes.Unauthenticated, status.Code(check(t, "")))
+	})
+
+	t.Run("garbage token is unauthenticated", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, codes.Unauthenticated, status.Code(check(t, "not-a-jwt")))
+	})
+
+	t.Run("valid token without the scope is permission-denied", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, codes.PermissionDenied, status.Code(check(t, wrongScopeToken)))
+	})
+}
diff --git a/examples/oauth2/README.md b/examples/oauth2/README.md
new file mode 100644
index 0000000..1b7b22e
--- /dev/null
+++ b/examples/oauth2/README.md
@@ -0,0 +1,89 @@
+# OAuth2 server + Bearer resource server
+
+End-to-end wiring of the v2 security library running in a single binary:
+
+- an OAuth2 authorization server exposing `/oauth2/authorize`,
+  `/oauth2/token`, `/oauth2/revoke`, `/oauth2/introspect`, and
+  `/.well-known/oauth-authorization-server` (Profile 2.0 BCP — PKCE /
+  refresh rotation mandatory when relevant);
+- a Bearer-protected resource at `GET /protected`, sharing the OAuth2
+  storage so it can validate opaque tokens locally (the in-process
+  equivalent of RFC 7662 introspection).
+
+## Run
+
+```sh
+go run .
+```
+
+The server listens on `:1337`.
+
+## Probe — public
+
+```sh
+curl -i http://localhost:1337/
+```
+
+## Probe — protected without token → `401 Unauthorized`
+
+```sh
+curl -i http://localhost:1337/protected
+```
+
+## Probe — mint a client_credentials token
+
+```sh
+curl -i -u 5cc06c3b-5755-4229-958c-a515a245aaeb:WTvuAztPD2XBauomleRzGFYuZawS07Ym \
+    -d 'grant_type=client_credentials&scope=api:read' \
+    http://localhost:1337/oauth2/token
+```
+
+Response body shape (RFC 6749 §5.1):
+
+```json
+{"access_token":"<opaque>","token_type":"Bearer","expires_in":3599,"scope":"api:read"}
+```
+
+## Probe — call the protected resource with the issued token
+
+```sh
+TOKEN=$(curl -s -u 5cc06c3b-5755-4229-958c-a515a245aaeb:WTvuAztPD2XBauomleRzGFYuZawS07Ym \
+    -d 'grant_type=client_credentials&scope=api:read' \
+    http://localhost:1337/oauth2/token | jq -r .access_token)
+curl -i -H "Authorization: Bearer $TOKEN" http://localhost:1337/protected
+```
+
+## Probe — discovery document (RFC 8414)
+
+```sh
+curl -s http://localhost:1337/.well-known/oauth-authorization-server | jq
+```
+
+## Probe — the authorization-code flow (browser)
+
+Open this URL in a browser — it carries an RFC 7636 sample PKCE challenge:
+
+```
+http://localhost:1337/oauth2/authorize?response_type=code&client_id=5cc06c3b-5755-4229-958c-a515a245aaeb&redirect_uri=http://localhost:1337/callback&scope=api:read&state=demo&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
+```
+
+Approve on the consent page; the browser lands on `/callback?code=…`.
+Exchange that code (the verifier is `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk`):
+
+```sh
+curl -i -u 5cc06c3b-5755-4229-958c-a515a245aaeb:WTvuAztPD2XBauomleRzGFYuZawS07Ym \
+    -d 'grant_type=authorization_code&code=<CODE>&redirect_uri=http://localhost:1337/callback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
+    http://localhost:1337/oauth2/token
+```
+
+## What this example does NOT cover
+
+- JWT-formatted access tokens (`jwt.OAuth2AccessTokenSigner` adapter wires
+  the JWT module into the token generator; not enabled here).
+- Persistent storage (memory store — every restart wipes tokens).
+- `private_key_jwt` client authentication.
+- The legacy `password` / `implicit` flows — opt-in, refused under the
+  BCP profile this example uses.
+
+See [docs/migration-from-v0.md](../../docs/migration-from-v0.md) for the
+mapping from the removed v0 stack to this wiring.
diff --git a/examples/oauth2/main.go b/examples/oauth2/main.go
new file mode 100644
index 0000000..b6d7e05
--- /dev/null
+++ b/examples/oauth2/main.go
@@ -0,0 +1,234 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package main demonstrates wiring of the v2 security library: an OAuth2
+// authorization server (authorization_code with PKCE, client_credentials,
+// refresh_token) plus a resource server protected by a bearer middleware
+// sharing the same storage as the auth server.
+//
+// Run:
+//
+//	go run ./examples/oauth2
+//
+// Probe — request an access token (client_credentials):
+//
+//	curl -i -u 5cc06c3b-5755-4229-958c-a515a245aaeb:WTvuAztPD2XBauomleRzGFYuZawS07Ym \
+//	    -d 'grant_type=client_credentials&scope=api:read' \
+//	    http://localhost:1337/oauth2/token
+//
+// Probe — call the protected resource with the issued token:
+//
+//	TOKEN=...  # from the previous response
+//	curl -i -H "Authorization: Bearer $TOKEN" http://localhost:1337/protected
+//
+// Probe — the authorization-code flow is browser-driven: open
+// http://localhost:1337/oauth2/authorize?response_type=code&client_id=5cc06c3b-5755-4229-958c-a515a245aaeb&redirect_uri=http://localhost:1337/callback&scope=api:read&state=demo&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
+// then approve — the browser lands on /callback with the code.
+package main
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/clientauth"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// Demo credentials. Hard-coded for the example; in real usage these come
+// from a client store seeded out-of-band.
+const (
+	demoClientID     = "5cc06c3b-5755-4229-958c-a515a245aaeb"
+	demoClientSecret = "WTvuAztPD2XBauomleRzGFYuZawS07Ym" //nolint:gosec // demo
+)
+
+// staticClientStore is a tiny in-memory [oauth2.ClientStore] suitable for
+// dev / demos. Production deployments plug a database-backed store.
+type staticClientStore struct{ clients map[string]oauth2.Client }
+
+func (s *staticClientStore) LoadClient(_ context.Context, id string) (oauth2.Client, error) {
+	c, ok := s.clients[id]
+	if !ok {
+		return nil, nil
+	}
+
+	return c, nil
+}
+
+// localIntrospectVerifier is the in-process verifier used by the resource
+// server. It hashes the bearer token and queries the OAuth2 storage —
+// the local equivalent of an RFC 7662 introspection call.
+type localIntrospectVerifier struct {
+	store oauth2.AccessTokenStore
+}
+
+// Verify implements [bearer.TokenVerifier].
+func (v *localIntrospectVerifier) Verify(ctx context.Context, tok string) (security.Authentication, error) {
+	hash := oauth2.HashToken(nil, tok)
+
+	at, err := v.store.LookupAccessToken(ctx, hash)
+	if err != nil {
+		return nil, security.ErrTokenNotFound
+	}
+
+	if at.IsExpired(time.Now()) {
+		return nil, security.ErrTokenExpired
+	}
+
+	return bearer.New(tok).WithAuthenticated(principal{sub: at.Subject}, nil, at.Subject), nil
+}
+
+type principal struct{ sub string }
+
+func (p principal) Subject() string { return p.sub }
+
+// buildServer wires the authorization server and the Bearer-protected
+// resource server onto a single mux. It is separate from main so the
+// end-to-end test can exercise the exact same wiring.
+func buildServer() (http.Handler, error) {
+	// Storage shared between the authorization server and the resource
+	// server. In a multi-process deployment each side uses its own
+	// storage implementation (SQL / Redis / introspection HTTP call).
+	store := memory.New()
+
+	// Seed a demo confidential client. The redirect URI points back at this
+	// same binary so the authorization-code flow is observable end to end.
+	clients := &staticClientStore{clients: map[string]oauth2.Client{
+		demoClientID: &oauth2.DefaultClient{
+			IDValue:           demoClientID,
+			Secret:            demoClientSecret,
+			TypeValue:         oauth2.ClientConfidential,
+			RedirectURIValues: []string{"http://localhost:1337/callback"},
+			ScopeValues:       []string{"api:read"},
+		},
+	}}
+
+	// Authorization server.
+	gcfg := grant.Config{
+		Storage:             store,
+		AccessTokens:        token.NewOpaque(32),
+		RefreshTokens:       token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)},
+		AccessTTL:           time.Hour,
+		RefreshTTL:          24 * time.Hour,
+		RotateRefreshTokens: true,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile:        oauth2.Profile20BCP,
+		Storage:        store,
+		ClientStore:    clients,
+		IssuerResolver: oauth2.StaticIssuer("http://localhost:1337", "api"),
+		Grants: []oauth2.Grant{
+			grant.NewAuthorizationCode(gcfg),
+			grant.NewClientCredentials(gcfg),
+			grant.NewRefreshToken(gcfg),
+		},
+		ClientAuth: []oauth2.ClientAuthenticator{clientauth.NewBasic(), clientauth.NewPost()},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("oauth2.NewServer: %w", err)
+	}
+
+	// Resource server: Bearer middleware backed by the introspection
+	// verifier that consults the shared storage.
+	verifier := &localIntrospectVerifier{store: store}
+	engine := security.NewEngine(
+		security.NewManager(bearer.NewAuthenticator(verifier)),
+		bearer.NewExtractor(),
+	)
+	protect := httpsec.Middleware(engine, httpsec.WithRealm("api"))
+
+	// The mount paths must match ServerConfig.RoutePrefix (default
+	// "/oauth2") so the metadata document advertises the right URLs.
+	mux := http.NewServeMux()
+	// /authorize answers GET (consent page) and POST (decision).
+	authorize := srv.AuthorizeHandler(oauth2.AuthorizeConfig{}, consentHandler)
+	mux.Handle("GET /oauth2/authorize", authorize)
+	mux.Handle("POST /oauth2/authorize", authorize)
+	mux.Handle("POST /oauth2/token", srv.TokenHandler())
+	mux.Handle("POST /oauth2/revoke", srv.RevokeHandler())
+	mux.Handle("POST /oauth2/introspect", srv.IntrospectHandler())
+	mux.Handle("GET /.well-known/oauth-authorization-server", srv.MetadataHandler())
+	mux.Handle("GET /protected", protect(http.HandlerFunc(protectedHandler)))
+	mux.HandleFunc("GET /callback", showCallback)
+	mux.HandleFunc("GET /", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+		_, _ = w.Write([]byte("public\n"))
+	})
+
+	return mux, nil
+}
+
+// consentHandler is the /authorize consent hook. A real application
+// authenticates the resource owner and renders branded UI; this demo
+// renders a bare Approve / Deny form and treats every visitor as the
+// fixed "demo-user".
+func consentHandler(w http.ResponseWriter, r *http.Request, ar *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+	if r.Method == http.MethodPost {
+		return &oauth2.Consent{
+			Approved: r.FormValue("decision") == "approve",
+			Subject:  "demo-user",
+		}, nil
+	}
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+
+	//nolint:gosec // G705: every interpolated value is HTML-escaped
+	fmt.Fprintf(w, `<!doctype html><title>Authorize</title>
+<p>Client <b>%s</b> requests scope <b>%s</b>.</p>
+<form method="post" action="/oauth2/authorize?%s">
+<button name="decision" value="approve">Approve</button>
+<button name="decision" value="deny">Deny</button>
+</form>`,
+		html.EscapeString(ar.Client.ID()),
+		html.EscapeString(ar.Scope),
+		html.EscapeString(r.URL.RawQuery))
+
+	return nil, nil // the consent page was rendered
+}
+
+// showCallback stands in for the client's redirect endpoint: it just
+// echoes the authorization code the browser was redirected with.
+func showCallback(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+
+	//nolint:gosec // G705: the code is echoed HTML-escaped
+	fmt.Fprintf(w, "authorization code: %s\n", html.EscapeString(r.URL.Query().Get("code")))
+}
+
+func main() {
+	handler, err := buildServer()
+	if err != nil {
+		log.Fatalf("example/oauth2: %v", err)
+	}
+
+	addr := ":1337"
+	log.Printf("listening on %s", addr)
+
+	server := &http.Server{
+		Addr:              addr,
+		Handler:           handler,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	if err := server.ListenAndServe(); err != nil {
+		log.Fatalf("listen: %v", err)
+	}
+}
+
+func protectedHandler(w http.ResponseWriter, r *http.Request) {
+	auth, _ := security.FromContext(r.Context())
+
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	_, _ = w.Write([]byte("hello " + auth.Principal().Subject() + "\n")) //nolint:gosec // demo
+}
diff --git a/examples/oauth2/main_test.go b/examples/oauth2/main_test.go
new file mode 100644
index 0000000..55474d8
--- /dev/null
+++ b/examples/oauth2/main_test.go
@@ -0,0 +1,158 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExampleOAuth2EndToEnd(t *testing.T) {
+	t.Parallel()
+
+	handler, err := buildServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	// 1. The authorization server mints an access token over client_credentials.
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+	form.Set("scope", "api:read")
+
+	req, err := http.NewRequest(http.MethodPost, srv.URL+"/oauth2/token", strings.NewReader(form.Encode()))
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(demoClientID, demoClientSecret)
+
+	resp, err := srv.Client().Do(req)
+	require.NoError(t, err)
+
+	var token struct {
+		AccessToken string `json:"access_token"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&token))
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	require.NotEmpty(t, token.AccessToken)
+
+	// 2. The protected resource accepts the issued token.
+	probe, err := http.NewRequest(http.MethodGet, srv.URL+"/protected", nil)
+	require.NoError(t, err)
+	probe.Header.Set("Authorization", "Bearer "+token.AccessToken)
+
+	resp, err = srv.Client().Do(probe)
+	require.NoError(t, err)
+	body, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Contains(t, string(body), "hello")
+
+	// 3. The protected resource rejects a request with no token.
+	resp, err = srv.Client().Get(srv.URL + "/protected")
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+
+	// 4. The metadata document is served.
+	resp, err = srv.Client().Get(srv.URL + "/.well-known/oauth-authorization-server")
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	// 5. The public route needs no authentication.
+	resp, err = srv.Client().Get(srv.URL + "/")
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+}
+
+// RFC 7636 Appendix B sample PKCE pair.
+const (
+	pkceVerifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+	pkceChallenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+)
+
+// TestExampleOAuth2AuthorizationCodeFlow drives the browser flow: the
+// consent page, the approval redirect carrying the code, and the code
+// exchange at /token.
+func TestExampleOAuth2AuthorizationCodeFlow(t *testing.T) {
+	t.Parallel()
+
+	handler, err := buildServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	client := srv.Client()
+	client.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse // inspect the redirect rather than follow it
+	}
+
+	authz := url.Values{
+		"response_type":         {"code"},
+		"client_id":             {demoClientID},
+		"redirect_uri":          {"http://localhost:1337/callback"},
+		"scope":                 {"api:read"},
+		"state":                 {"demo-state"},
+		"code_challenge":        {pkceChallenge},
+		"code_challenge_method": {"S256"},
+	}.Encode()
+
+	// 1. GET /authorize renders the consent page.
+	resp, err := client.Get(srv.URL + "/oauth2/authorize?" + authz)
+	require.NoError(t, err)
+	page, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Contains(t, string(page), "Approve")
+
+	// 2. Approving redirects to the callback with an authorization code.
+	resp, err = client.PostForm(srv.URL+"/oauth2/authorize?"+authz, url.Values{"decision": {"approve"}})
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusFound, resp.StatusCode)
+
+	loc, err := url.Parse(resp.Header.Get("Location"))
+	require.NoError(t, err)
+
+	code := loc.Query().Get("code")
+	require.NotEmpty(t, code)
+	assert.Equal(t, "demo-state", loc.Query().Get("state"))
+
+	// 3. The code is exchanged for an access token at /token.
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {"http://localhost:1337/callback"},
+		"code_verifier": {pkceVerifier},
+	}
+
+	req, err := http.NewRequest(http.MethodPost, srv.URL+"/oauth2/token", strings.NewReader(form.Encode()))
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(demoClientID, demoClientSecret)
+
+	resp, err = client.Do(req)
+	require.NoError(t, err)
+
+	var tok struct {
+		AccessToken string `json:"access_token"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&tok))
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.NotEmpty(t, tok.AccessToken)
+}
diff --git a/examples/session-web/main.go b/examples/session-web/main.go
new file mode 100644
index 0000000..c9e30c3
--- /dev/null
+++ b/examples/session-web/main.go
@@ -0,0 +1,164 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Command session-web is a runnable cookie-session web demo.
+//
+// It is a tiny login-form application: a successful login mints an
+// encrypted session cookie, the home page reads it, and logout clears it.
+// The logout form is protected by a CSRF synchronizer token.
+//
+// Run:
+//
+//	go run ./session-web
+//
+// Then open http://localhost:8082 in a browser and log in with
+// alice / alice-secret. The session cookie is AES-256-GCM sealed; tampering
+// with it simply drops the session.
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"fmt"
+	"html"
+	"log"
+	"net/http"
+
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/hyperscale-stack/security/password"
+	"github.com/hyperscale-stack/security/session"
+)
+
+// principal is the minimal [security.Principal] stored on login.
+type principal struct{ subject string }
+
+func (p principal) Subject() string { return p.subject }
+
+// app holds the demo dependencies.
+type app struct {
+	manager *session.Manager
+	hasher  password.Hasher
+	users   map[string]string // username -> bcrypt hash
+}
+
+// newServer builds the demo handler. It is separate from main so the
+// end-to-end test can drive the exact same wiring.
+func newServer() (http.Handler, error) {
+	key := make([]byte, 32) // AES-256
+	if _, err := rand.Read(key); err != nil {
+		return nil, fmt.Errorf("generate codec key: %w", err)
+	}
+
+	codec, err := session.NewCodec(key)
+	if err != nil {
+		return nil, fmt.Errorf("new codec: %w", err)
+	}
+
+	hasher := password.NewBCryptHasher(10)
+
+	aliceHash, err := hasher.Hash(context.Background(), "alice-secret")
+	if err != nil {
+		return nil, fmt.Errorf("hash alice: %w", err)
+	}
+
+	a := &app{
+		manager: session.NewManager(codec),
+		hasher:  hasher,
+		users:   map[string]string{"alice": aliceHash},
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /", a.home)
+	mux.HandleFunc("GET /login", a.loginForm)
+	mux.HandleFunc("POST /login", a.login)
+	mux.HandleFunc("POST /logout", a.logout)
+
+	return mux, nil
+}
+
+// home renders the protected page, or redirects to the login form when no
+// valid session cookie is present.
+func (a *app) home(w http.ResponseWriter, r *http.Request) {
+	s, err := a.manager.Get(r.Context(), httpsec.NewCarrier(w, r))
+	if err != nil {
+		http.Redirect(w, r, "/login", http.StatusSeeOther)
+
+		return
+	}
+
+	sub, _ := s.Values["sub"].(string)
+
+	//nolint:gosec // G705: both interpolated values are HTML-escaped above
+	fmt.Fprintf(w, `<h1>Welcome %s</h1>
+<form method="post" action="/logout">
+<input type="hidden" name="csrf_token" value="%s">
+<button type="submit">Log out</button>
+</form>`, html.EscapeString(sub), html.EscapeString(session.CSRFToken(s)))
+}
+
+// loginForm renders the login form.
+func (a *app) loginForm(w http.ResponseWriter, _ *http.Request) {
+	fmt.Fprint(w, `<h1>Sign in</h1>
+<form method="post" action="/login">
+<input name="username" placeholder="username">
+<input name="password" type="password" placeholder="password">
+<button type="submit">Sign in</button>
+</form>`)
+}
+
+// login verifies the credentials and mints a session on success.
+func (a *app) login(w http.ResponseWriter, r *http.Request) {
+	username := r.FormValue("username")
+	hash, ok := a.users[username]
+
+	if ok {
+		match, err := a.hasher.Verify(r.Context(), hash, r.FormValue("password"))
+		if err == nil && match {
+			if _, err := a.manager.Login(r.Context(), httpsec.NewCarrier(w, r), principal{subject: username}); err != nil {
+				http.Error(w, "session error", http.StatusInternalServerError)
+
+				return
+			}
+
+			http.Redirect(w, r, "/", http.StatusSeeOther)
+
+			return
+		}
+	}
+
+	// Same response for unknown user and wrong password (anti-enumeration).
+	http.Error(w, "invalid credentials", http.StatusUnauthorized)
+}
+
+// logout clears the session after checking the CSRF token.
+func (a *app) logout(w http.ResponseWriter, r *http.Request) {
+	carrier := httpsec.NewCarrier(w, r)
+
+	s, err := a.manager.Get(r.Context(), carrier)
+	if err != nil {
+		http.Redirect(w, r, "/login", http.StatusSeeOther)
+
+		return
+	}
+
+	if !session.VerifyCSRF(s, r.FormValue("csrf_token")) {
+		http.Error(w, "bad CSRF token", http.StatusForbidden)
+
+		return
+	}
+
+	a.manager.Logout(r.Context(), carrier)
+	http.Redirect(w, r, "/login", http.StatusSeeOther)
+}
+
+func main() {
+	handler, err := newServer()
+	if err != nil {
+		log.Fatalf("session-web: %v", err)
+	}
+
+	addr := ":8082"
+	log.Printf("session-web: listening on %s", addr)
+	log.Fatal(http.ListenAndServe(addr, handler)) //nolint:gosec // demo server, no timeouts needed
+}
diff --git a/examples/session-web/main_test.go b/examples/session-web/main_test.go
new file mode 100644
index 0000000..82cc6de
--- /dev/null
+++ b/examples/session-web/main_test.go
@@ -0,0 +1,128 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"io"
+	"net/http"
+	"net/http/cookiejar"
+	"net/http/httptest"
+	"net/url"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var csrfRE = regexp.MustCompile(`name="csrf_token" value="([^"]+)"`)
+
+func TestSessionWebExample(t *testing.T) {
+	t.Parallel()
+
+	handler, err := newServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	jar, err := cookiejar.New(nil)
+	require.NoError(t, err)
+
+	client := srv.Client()
+	client.Jar = jar
+	client.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse // inspect redirects instead of following them
+	}
+
+	get := func(t *testing.T, path string) *http.Response {
+		t.Helper()
+
+		resp, err := client.Get(srv.URL + path)
+		require.NoError(t, err)
+
+		return resp
+	}
+
+	postForm := func(t *testing.T, path string, form url.Values) *http.Response {
+		t.Helper()
+
+		resp, err := client.PostForm(srv.URL+path, form)
+		require.NoError(t, err)
+
+		return resp
+	}
+
+	// 1. The home page redirects to /login when no session cookie is set.
+	resp := get(t, "/")
+	assert.Equal(t, http.StatusSeeOther, resp.StatusCode)
+	assert.Equal(t, "/login", resp.Header.Get("Location"))
+	_ = resp.Body.Close()
+
+	// 2. Wrong password is rejected.
+	resp = postForm(t, "/login", url.Values{"username": {"alice"}, "password": {"wrong"}})
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+	_ = resp.Body.Close()
+
+	// 3. Correct credentials mint a session and redirect home.
+	resp = postForm(t, "/login", url.Values{"username": {"alice"}, "password": {"alice-secret"}})
+	assert.Equal(t, http.StatusSeeOther, resp.StatusCode)
+	assert.Equal(t, "/", resp.Header.Get("Location"))
+	_ = resp.Body.Close()
+
+	// 4. The home page now renders the authenticated view.
+	resp = get(t, "/")
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	assert.Contains(t, string(body), "Welcome alice")
+
+	match := csrfRE.FindStringSubmatch(string(body))
+	require.Len(t, match, 2, "home page must embed a CSRF token")
+	csrf := match[1]
+
+	// 5. Logout without the CSRF token is forbidden.
+	resp = postForm(t, "/logout", url.Values{"csrf_token": {"forged"}})
+	assert.Equal(t, http.StatusForbidden, resp.StatusCode)
+	_ = resp.Body.Close()
+
+	// 6. Logout with the CSRF token clears the session.
+	resp = postForm(t, "/logout", url.Values{"csrf_token": {csrf}})
+	assert.Equal(t, http.StatusSeeOther, resp.StatusCode)
+	_ = resp.Body.Close()
+
+	// 7. The home page redirects to /login again.
+	resp = get(t, "/")
+	assert.Equal(t, http.StatusSeeOther, resp.StatusCode)
+	_ = resp.Body.Close()
+}
+
+func TestSessionWebTamperedCookieIsDropped(t *testing.T) {
+	t.Parallel()
+
+	handler, err := newServer()
+	require.NoError(t, err)
+
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+
+	req, err := http.NewRequest(http.MethodGet, srv.URL+"/", nil)
+	require.NoError(t, err)
+	req.Header.Set("Cookie", "session="+strings.Repeat("A", 80))
+
+	client := srv.Client()
+	client.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse
+	}
+
+	resp, err := client.Do(req)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = resp.Body.Close() })
+
+	// A garbage cookie must not panic — it is treated as "no session".
+	assert.Equal(t, http.StatusSeeOther, resp.StatusCode)
+}
diff --git a/extractor.go b/extractor.go
new file mode 100644
index 0000000..03bceaa
--- /dev/null
+++ b/extractor.go
@@ -0,0 +1,26 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "context"
+
+// Extractor pulls raw, unauthenticated credentials from a [Carrier] and
+// returns an [Authentication] that captures them. The returned value MUST
+// have IsAuthenticated() == false: validation is the [Authenticator]'s job.
+//
+// Sentinel conventions:
+//
+//   - Return (nil, nil) when no credentials of the supported scheme are
+//     present. The Engine treats this as "this extractor does not apply"
+//     and consults the next one.
+//   - Return (nil, err) wrapping a security sentinel when credentials were
+//     present but malformed (e.g. invalid base64 in Basic). The Engine
+//     surfaces err to the caller and stops; downstream authenticators are
+//     not invoked.
+//
+// Implementations MUST be safe for concurrent use.
+type Extractor interface {
+	Extract(ctx context.Context, c Carrier) (Authentication, error)
+}
diff --git a/go.mod b/go.mod
index de53a99..1ac1a4b 100644
--- a/go.mod
+++ b/go.mod
@@ -1,20 +1,23 @@
 module github.com/hyperscale-stack/security
 
-go 1.25.0
+go 1.26
 
 require (
-	github.com/gilcrest/alice v1.0.0
-	github.com/hyperscale-stack/secure v1.0.0
-	github.com/rs/zerolog v1.35.1
 	github.com/stretchr/testify v1.11.1
-	golang.org/x/crypto v0.51.0
+	go.opentelemetry.io/otel v1.43.0
+	go.opentelemetry.io/otel/sdk v1.43.0
+	go.opentelemetry.io/otel/trace v1.43.0
 )
 
 require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/chigopher/pathlib v0.19.1 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/fsnotify/fsnotify v1.8.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
 	github.com/huandu/xstrings v1.4.0 // indirect
 	github.com/iancoleman/strcase v0.3.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
@@ -25,6 +28,7 @@ require (
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.3 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/rs/zerolog v1.35.1 // indirect
 	github.com/sagikazarmark/locafero v0.7.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spf13/afero v1.12.0 // indirect
@@ -32,9 +36,10 @@ require (
 	github.com/spf13/cobra v1.8.1 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/spf13/viper v1.20.0 // indirect
-	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/vektra/mockery/v2 v2.53.5 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/mod v0.35.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
diff --git a/go.sum b/go.sum
index 8585b84..3a3a5ac 100644
--- a/go.sum
+++ b/go.sum
@@ -1,23 +1,27 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chigopher/pathlib v0.19.1 h1:RoLlUJc0CqBGwq239cilyhxPNLXTK+HXoASGyGznx5A=
 github.com/chigopher/pathlib v0.19.1/go.mod h1:tzC1dZLW8o33UQpWkNkhvPwL5n4yyFRFm/jL1YGWFvY=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M=
 github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/gilcrest/alice v1.0.0 h1:5+CasxidJEUHmgghQxLOl09uYhOlavDfDgNZhyR62LU=
-github.com/gilcrest/alice v1.0.0/go.mod h1:q5HRhK5WEyU1pDBIIfmYapVGLd/IAAPwiO8LNxKADpw=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-viper/mapstructure/v2 v2.2.1 h1:ZAaOCxANMuZx5RCeg0mBdEZk7DZasvvZIxtHqx8aGss=
 github.com/go-viper/mapstructure/v2 v2.2.1/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/huandu/xstrings v1.4.0 h1:D17IlohoQq4UcpqD7fDk80P7l+lwAmlFaBHgOipl2FU=
 github.com/huandu/xstrings v1.4.0/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
-github.com/hyperscale-stack/secure v1.0.0 h1:ayGoa/Y/0RcAcP767WKjla1r9KlR+Tul5DPI/jE9dP0=
-github.com/hyperscale-stack/secure v1.0.0/go.mod h1:PY+BMJQI2aP+YYA3C7R0bFTS/XGJ4xPCYjBp9rEqmtQ=
 github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSASxEI=
 github.com/iancoleman/strcase v0.3.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
@@ -36,15 +40,12 @@ github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
-github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
-github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
 github.com/pelletier/go-toml/v2 v2.2.3 h1:YmeHyLY8mFWbdkNWwpr+qIL2bEqT0o95WSdkNHvL12M=
 github.com/pelletier/go-toml/v2 v2.2.3/go.mod h1:MfCQTFTvCcUyyvvwm1+G6H/jORL20Xlb6rzQu9GuUkc=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
 github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
@@ -63,20 +64,30 @@ github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
 github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.20.0 h1:zrxIyR3RQIOsarIrgL8+sAvALXul9jeEPa06Y0Ph6vY=
 github.com/spf13/viper v1.20.0/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/vektra/mockery/v2 v2.53.5 h1:iktAY68pNiMvLoHxKqlSNSv/1py0QF/17UGrrAMYDI8=
 github.com/vektra/mockery/v2 v2.53.5/go.mod h1:hIFFb3CvzPdDJJiU7J4zLRblUMv7OuezWsHPmswriwo=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
 go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
-golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
-golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
 golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
@@ -91,8 +102,7 @@ golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
 golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU=
-gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/go.work b/go.work
new file mode 100644
index 0000000..9a0e8cb
--- /dev/null
+++ b/go.work
@@ -0,0 +1,17 @@
+go 1.26
+
+use (
+	.
+	./basic
+	./bearer
+	./examples
+	./grpc
+	./http
+	./internal/integrations
+	./jwt
+	./oauth2
+	./oauth2/store/redis
+	./oauth2/store/sql
+	./password
+	./session
+)
diff --git a/go.work.sum b/go.work.sum
new file mode 100644
index 0000000..843e673
--- /dev/null
+++ b/go.work.sum
@@ -0,0 +1,77 @@
+cel.dev/expr v0.16.1/go.mod h1:AsGA5zb3WruAEQeQng1RZdGEXmBj0jvMWh6l5SnNuC8=
+cel.dev/expr v0.16.2/go.mod h1:gXngZQMkWJoSbE8mOzehJlXQyubn/Vg0vR9/F3W7iw8=
+cloud.google.com/go v0.116.0/go.mod h1:cEPSRWPzZEswwdr9BxE6ChEn01dWlTaF05LiC2Xs70U=
+cloud.google.com/go/auth v0.13.0/go.mod h1:COOjD9gwfKNKz+IIduatIhYJQIc0mG3H102r/EMxX6Q=
+cloud.google.com/go/auth/oauth2adapt v0.2.6/go.mod h1:AlmsELtlEBnaNTL7jCj8VQFLy6mbZv0s4Q7NGBeQ5E8=
+cloud.google.com/go/compute/metadata v0.6.0/go.mod h1:FjyFAW1MW0C203CEOMDTu3Dk1FlqW3Rga40jzHL4hfg=
+cloud.google.com/go/iam v1.2.2/go.mod h1:0Ys8ccaZHdI1dEUilwzqng/6ps2YB6vRsjIe00/+6JY=
+cloud.google.com/go/monitoring v1.21.2/go.mod h1:hS3pXvaG8KgWTSz+dAdyzPrGUYmi2Q+WFX8g2hqVEZU=
+cloud.google.com/go/storage v1.49.0/go.mod h1:k1eHhhpLvrPjVGfo0mOUPEJ4Y2+a/Hv5PiwehZI9qGU=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.25.0/go.mod h1:obipzmGjfSjam60XLwGfqUkJsfiheAl+TUjG+4yzyPM=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.48.1/go.mod h1:jyqM3eLpJ3IbIFDTKVz2rF9T/xWGW0rIriGwnz8l9Tk=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.48.1/go.mod h1:viRWSEhtMZqz1rhwmOVKkWl6SwmVowfL9O2YR5gI2PE=
+github.com/alicebob/miniredis/v2 v2.34.0/go.mod h1:kWShP4b58T1CW0Y5dViCd5ztzrDqRWqM3nksiyXk5s8=
+github.com/census-instrumentation/opencensus-proto v0.4.1/go.mod h1:4T9NM4+4Vw91VeyqjLS6ao50K5bOcLKN6Q42XnYaRYw=
+github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
+github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
+github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
+github.com/cncf/xds/go v0.0.0-20240905190251-b4127c9b8d78/go.mod h1:W+zGtBO5Y1IgJhy4+A9GOqVhqLpfZi+vwmdNXUehLA8=
+github.com/coreos/go-systemd/v22 v22.7.0/go.mod h1:xNUYtjHu2EDXbsxz1i41wouACIwT7Ybq9o0BQhMwD0w=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/envoyproxy/go-control-plane v0.13.1/go.mod h1:X45hY0mufo6Fd0KW3rqsGvQMw58jvjymeCzBU3mWyHw=
+github.com/envoyproxy/protoc-gen-validate v1.1.0/go.mod h1:sXRDRVmzEbkM7CVcM06s9shE/m23dg3wzjl0UWqJ2q4=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-jose/go-jose/v4 v4.0.4/go.mod h1:NKb5HO1EZccyMpiZNbdUw/14tiXNyUJh188dfnMCAfc=
+github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/golang/glog v1.2.2/go.mod h1:6AhwSGph0fcJtXVM/PEHPqZlFeoLxhs7/t5UDAwmO+w=
+github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/s2a-go v0.1.8/go.mod h1:6iNWHTpQ+nfNRN5E00MSdfDwVesa8hhS32PhPO8deJA=
+github.com/googleapis/enterprise-certificate-proxy v0.3.4/go.mod h1:YKe7cfqYXjKGpGvmSg28/fFvhNzinZQm8DGnaburhGA=
+github.com/googleapis/gax-go/v2 v2.14.1/go.mod h1:Hb/NubMaVM88SrNkvl8X/o8XWwDJEPqouaLeN2IUxoA=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/sftp v1.13.7/go.mod h1:KMKI0t3T6hfA+lTR/ssZdunHo+uwq7ghoN09/FSu3DY=
+github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+go.opencensus.io v0.24.0/go.mod h1:vNK8G9p7aAivkbmorf4v+7Hgx+Zs0yY+0fOtgBfjQKo=
+go.opentelemetry.io/contrib/detectors/gcp v1.29.0/go.mod h1:GW2aWZNwR2ZxDLdv8OyC2G8zkRoQBuURgV7RPQgcPoU=
+go.opentelemetry.io/contrib/detectors/gcp v1.31.0/go.mod h1:tzQL6E1l+iV44YFTkcAeNQqzXUiekSYP9jjJjXwEd00=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.54.0/go.mod h1:B9yO6b04uB80CzjedvewuqDhxJxi11s7/GtiGa8bAjI=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0/go.mod h1:L7UH0GbB0p47T4Rri3uHjbpCFYrVrwc1I25QhNPiGK8=
+go.opentelemetry.io/otel v1.29.0/go.mod h1:N/WtXPs1CNCUEx+Agz5uouwCba+i+bJGFicT8SR4NP8=
+go.opentelemetry.io/otel/metric v1.29.0/go.mod h1:auu/QWieFVWx+DmQOUMgj0F8LHWdgalxXqvp7BII/W8=
+go.opentelemetry.io/otel/sdk v1.29.0/go.mod h1:pM8Dx5WKnvxLCb+8lG1PRNIDxu9g9b9g59Qr7hfAAok=
+go.opentelemetry.io/otel/sdk/metric v1.29.0/go.mod h1:6zZLdCl2fkauYoZIOn/soQIDSWFmNSRcICarHfuhNJQ=
+go.opentelemetry.io/otel/trace v1.29.0/go.mod h1:eHl3w0sp3paPkYstJOmAimxhiFXPg+MMTlEh3nsQgWQ=
+go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
+golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+golang.org/x/mod v0.21.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
+golang.org/x/oauth2 v0.25.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
+golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/telemetry v0.0.0-20260409153401-be6f6cb8b1fa/go.mod h1:kHjTxDEnAu6/Nl9lDkzjWpR+bmKfxeiRuSDlsMb70gE=
+golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/time v0.8.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
+golang.org/x/tools v0.26.0/go.mod h1:TPVVj70c7JJ3WCazhD8OdXcZg/og+b9+tH/KxylGwH0=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/api v0.215.0/go.mod h1:fta3CVtuJYOEdugLNWm6WodzOS8KdFckABwN4I40hzY=
+google.golang.org/genproto v0.0.0-20241118233622-e639e219e697 h1:ToEetK57OidYuqD4Q5w+vfEnPvPpuTwedCNVohYJfNk=
+google.golang.org/genproto v0.0.0-20241118233622-e639e219e697/go.mod h1:JJrvXBWRZaFMxBufik1a4RpFw4HhgVtBBWQeQgUj2cc=
+google.golang.org/genproto/googleapis/api v0.0.0-20241209162323-e6fa225c2576/go.mod h1:1R3kvZ1dtP3+4p4d3G8uJ8rFk/fWlScl38vanWACI08=
+google.golang.org/grpc v1.67.3/go.mod h1:YGaHCc6Oap+FzBJTZLBzkGSYt/cvGPFTPxkn7QfSU8s=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+google.golang.org/protobuf v1.36.0/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+modernc.org/sqlite v1.34.4/go.mod h1:3QQFCG2SEMtc2nv+Wq4cQCH7Hjcg+p/RMlS1XK+zwbk=
diff --git a/grpc/authorize.go b/grpc/authorize.go
new file mode 100644
index 0000000..3540e61
--- /dev/null
+++ b/grpc/authorize.go
@@ -0,0 +1,78 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+	"go.opentelemetry.io/otel"
+	"google.golang.org/grpc"
+)
+
+// UnaryAuthorize returns a unary interceptor that enforces an
+// [security.AccessDecisionManager] against the request's
+// [security.Authentication]. Install it AFTER [UnaryServerInterceptor] in
+// the interceptor chain so the context already carries an authentication.
+//
+// On grant the handler runs; on deny the configured [ErrorMapper]
+// translates the decision (typically codes.PermissionDenied).
+func UnaryAuthorize(
+	adm security.AccessDecisionManager,
+	attrs []security.Attribute,
+	opts ...Option,
+) grpc.UnaryServerInterceptor {
+	cfg := buildConfig(opts...)
+
+	return func(
+		ctx context.Context,
+		req any,
+		_ *grpc.UnaryServerInfo,
+		handler grpc.UnaryHandler,
+	) (any, error) {
+		if err := decide(ctx, adm, attrs); err != nil {
+			return nil, cfg.errorMapper.Map(ctx, err)
+		}
+
+		return handler(ctx, req)
+	}
+}
+
+// StreamAuthorize is the streaming counterpart of [UnaryAuthorize].
+func StreamAuthorize(
+	adm security.AccessDecisionManager,
+	attrs []security.Attribute,
+	opts ...Option,
+) grpc.StreamServerInterceptor {
+	cfg := buildConfig(opts...)
+
+	return func(
+		srv any,
+		ss grpc.ServerStream,
+		_ *grpc.StreamServerInfo,
+		handler grpc.StreamHandler,
+	) error {
+		if err := decide(ss.Context(), adm, attrs); err != nil {
+			return cfg.errorMapper.Map(ss.Context(), err)
+		}
+
+		return handler(srv, ss)
+	}
+}
+
+// decide pulls the Authentication from ctx and runs the ADM, wrapping the
+// call in a "grpcsec.Authorize" span.
+func decide(ctx context.Context, adm security.AccessDecisionManager, attrs []security.Attribute) error {
+	ctx, span := otel.Tracer(tracerName).Start(ctx, "grpcsec.Authorize")
+	defer span.End()
+
+	auth, _ := security.FromContext(ctx)
+
+	if err := adm.Decide(ctx, auth, attrs); err != nil {
+		return err //nolint:wrapcheck // security.* sentinels pass through to the ErrorMapper
+	}
+
+	return nil
+}
diff --git a/grpc/authorize_test.go b/grpc/authorize_test.go
new file mode 100644
index 0000000..b95abc1
--- /dev/null
+++ b/grpc/authorize_test.go
@@ -0,0 +1,120 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/status"
+)
+
+// chainUnary composes two unary interceptors (authenticate then authorize)
+// so the authorisation step sees the context the authentication step
+// produced — mirroring how applications wire grpc.ChainUnaryInterceptor.
+func chainUnary(a, b grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor {
+	return func(
+		ctx context.Context,
+		req any,
+		info *grpc.UnaryServerInfo,
+		handler grpc.UnaryHandler,
+	) (any, error) {
+		return a(ctx, req, info, func(ctx context.Context, req any) (any, error) {
+			return b(ctx, req, info, handler)
+		})
+	}
+}
+
+func TestUnaryAuthorizeGrantsWhenRolePresent(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+
+	interceptor := chainUnary(
+		grpcsec.UnaryServerInterceptor(newEngine("ROLE_ADMIN")),
+		grpcsec.UnaryAuthorize(adm, []security.Attribute{security.Role("ADMIN")}),
+	)
+
+	client := dialBufconn(t, interceptor, nil)
+
+	resp, err := client.Check(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+	assert.Equal(t, healthpb.HealthCheckResponse_SERVING, resp.GetStatus())
+}
+
+func TestUnaryAuthorizeDeniesWhenRoleMissing(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+
+	interceptor := chainUnary(
+		grpcsec.UnaryServerInterceptor(newEngine("ROLE_USER")), // not ADMIN
+		grpcsec.UnaryAuthorize(adm, []security.Attribute{security.Role("ADMIN")}),
+	)
+
+	client := dialBufconn(t, interceptor, nil)
+
+	_, err := client.Check(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.Error(t, err)
+	assert.Equal(t, codes.PermissionDenied, status.Code(err))
+}
+
+func TestUnaryAuthorizeDeniesAnonymous(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+
+	// No authentication interceptor in front: the request is anonymous,
+	// the role voter denies.
+	client := dialBufconn(t,
+		grpcsec.UnaryAuthorize(adm, []security.Attribute{security.Role("ADMIN")}),
+		nil,
+	)
+
+	_, err := client.Check(context.Background(), &healthpb.HealthCheckRequest{})
+	require.Error(t, err)
+	assert.Equal(t, codes.PermissionDenied, status.Code(err))
+}
+
+func TestStreamAuthorizeGrantsAndDenies(t *testing.T) {
+	t.Parallel()
+
+	adm := security.NewAffirmativeDecisionManager(voter.HasScope("watch"))
+
+	chain := func(authorities ...string) grpc.StreamServerInterceptor {
+		auth := grpcsec.StreamServerInterceptor(newEngine(authorities...))
+		authz := grpcsec.StreamAuthorize(adm, []security.Attribute{security.Scope("watch")})
+
+		return func(srv any, ss grpc.ServerStream, info *grpc.StreamServerInfo, h grpc.StreamHandler) error {
+			return auth(srv, ss, info, func(srv any, ss grpc.ServerStream) error {
+				return authz(srv, ss, info, h)
+			})
+		}
+	}
+
+	// Granted: principal carries scope:watch.
+	granted := dialBufconn(t, nil, chain("scope:watch"))
+	stream, err := granted.Watch(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+	resp, err := stream.Recv()
+	require.NoError(t, err)
+	assert.Equal(t, healthpb.HealthCheckResponse_SERVING, resp.GetStatus())
+
+	// Denied: principal lacks the scope.
+	denied := dialBufconn(t, nil, chain("scope:other"))
+	stream, err = denied.Watch(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+	_, err = stream.Recv()
+	require.Error(t, err)
+	assert.Equal(t, codes.PermissionDenied, status.Code(err))
+}
diff --git a/grpc/carrier.go b/grpc/carrier.go
new file mode 100644
index 0000000..2ea61f6
--- /dev/null
+++ b/grpc/carrier.go
@@ -0,0 +1,75 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec
+
+import (
+	"context"
+	"strings"
+
+	"github.com/hyperscale-stack/security"
+	"google.golang.org/grpc/metadata"
+)
+
+// Carrier adapts gRPC request metadata to [security.Carrier].
+//
+// Reads consult the incoming metadata (metadata.FromIncomingContext).
+// gRPC normalises metadata keys to lower-case; the Carrier lower-cases
+// lookups so callers can use the conventional "Authorization" spelling.
+//
+// Writes accumulate in a private metadata.MD that the interceptor flushes
+// as a response header (grpc.SetHeader) before returning. This lets an
+// ErrorMapper attach, e.g., a diagnostic header alongside a status error.
+//
+// Carrier is NOT safe for concurrent use; one instance per RPC.
+type Carrier struct {
+	in  metadata.MD
+	out metadata.MD
+}
+
+// NewCarrier builds a Carrier from an RPC context. When ctx carries no
+// incoming metadata (a non-gRPC caller, a unit test), the read side is
+// simply empty.
+func NewCarrier(ctx context.Context) *Carrier {
+	in, ok := metadata.FromIncomingContext(ctx)
+	if !ok {
+		in = metadata.MD{}
+	}
+
+	return &Carrier{in: in, out: metadata.MD{}}
+}
+
+// Get implements [security.Carrier]. Returns the first value for key.
+func (c *Carrier) Get(key string) string {
+	vs := c.in.Get(strings.ToLower(key))
+	if len(vs) == 0 {
+		return ""
+	}
+
+	return vs[0]
+}
+
+// Values implements [security.Carrier].
+func (c *Carrier) Values(key string) []string {
+	return c.in.Get(strings.ToLower(key))
+}
+
+// Set implements [security.Carrier]. The value is staged in the response
+// metadata; the interceptor flushes it via grpc.SetHeader.
+func (c *Carrier) Set(key, value string) {
+	c.out.Set(strings.ToLower(key), value)
+}
+
+// Add implements [security.Carrier].
+func (c *Carrier) Add(key, value string) {
+	c.out.Append(strings.ToLower(key), value)
+}
+
+// ResponseMetadata returns the staged response metadata. The interceptor
+// calls it after the engine / handler run and, when non-empty, pushes it
+// with grpc.SetHeader.
+func (c *Carrier) ResponseMetadata() metadata.MD { return c.out }
+
+// Compile-time check.
+var _ security.Carrier = (*Carrier)(nil)
diff --git a/grpc/carrier_test.go b/grpc/carrier_test.go
new file mode 100644
index 0000000..9141636
--- /dev/null
+++ b/grpc/carrier_test.go
@@ -0,0 +1,41 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"testing"
+
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	"github.com/stretchr/testify/assert"
+	"google.golang.org/grpc/metadata"
+)
+
+func TestCarrierReads(t *testing.T) {
+	t.Parallel()
+
+	ctx := metadata.NewIncomingContext(context.Background(), metadata.MD{
+		"authorization": {"Bearer one", "Bearer two"},
+	})
+	c := grpcsec.NewCarrier(ctx)
+
+	// gRPC lowercases metadata keys; the carrier lower-cases lookups so the
+	// conventional "Authorization" spelling resolves.
+	assert.Equal(t, "Bearer one", c.Get("Authorization"))
+	assert.Equal(t, []string{"Bearer one", "Bearer two"}, c.Values("Authorization"))
+	assert.Empty(t, c.Values("x-absent"))
+}
+
+func TestCarrierWritesResponseMetadata(t *testing.T) {
+	t.Parallel()
+
+	c := grpcsec.NewCarrier(context.Background())
+
+	c.Set("x-trace", "abc")
+	c.Add("x-trace", "def")
+
+	md := c.ResponseMetadata()
+	assert.Equal(t, []string{"abc", "def"}, md.Get("x-trace"))
+}
diff --git a/grpc/doc.go b/grpc/doc.go
new file mode 100644
index 0000000..a130708
--- /dev/null
+++ b/grpc/doc.go
@@ -0,0 +1,16 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package grpcsec is the gRPC transport adapter for the security core.
+//
+// It exposes unary and stream server interceptors that hand the gRPC metadata
+// (the Carrier) to the core Engine and map security errors to the appropriate
+// gRPC status codes (codes.Unauthenticated, codes.PermissionDenied, …).
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - google.golang.org/grpc
+//   - go.opentelemetry.io/otel
+//   - stdlib only
+package grpcsec
diff --git a/grpc/error_mapper.go b/grpc/error_mapper.go
new file mode 100644
index 0000000..9e1f254
--- /dev/null
+++ b/grpc/error_mapper.go
@@ -0,0 +1,75 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec
+
+import (
+	"context"
+	"errors"
+
+	"github.com/hyperscale-stack/security"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// ErrorMapper translates a security error into a gRPC status error. Custom
+// mappers can localize messages or attach status details; the default
+// mapper covers the canonical security sentinels.
+//
+// Implementations MUST be safe for concurrent use.
+type ErrorMapper interface {
+	// Map returns the gRPC status error for err. It MUST return a non-nil
+	// error (callers only invoke it on a failure path).
+	Map(ctx context.Context, err error) error
+}
+
+// DefaultErrorMapper returns the canonical mapper:
+//
+//   - codes.InvalidArgument  for [security.ErrUnsupportedCredential]
+//   - codes.PermissionDenied for [security.ErrAccessDenied] and
+//     [security.ErrInsufficientScope]
+//   - codes.Unauthenticated  for ErrInvalidCredentials,
+//     ErrClientSecretMismatch, ErrTokenExpired, ErrTokenNotFound,
+//     ErrAuthenticatorRefused, and any other unclassified error
+//
+// The message is intentionally terse — gRPC clients branch on the code,
+// not the string.
+func DefaultErrorMapper() ErrorMapper { return defaultErrorMapper{} }
+
+type defaultErrorMapper struct{}
+
+// Map implements [ErrorMapper]. The returned status error is the final
+// wire value — not a wrapping of err — so wrapcheck is silenced here.
+func (defaultErrorMapper) Map(_ context.Context, err error) error {
+	code, msg := classify(err)
+
+	return status.Error(code, msg) //nolint:wrapcheck // status error is the terminal wire value
+}
+
+func classify(err error) (codes.Code, string) {
+	switch {
+	case errors.Is(err, security.ErrUnsupportedCredential):
+		return codes.InvalidArgument, "unsupported credential"
+
+	case errors.Is(err, security.ErrAccessDenied):
+		return codes.PermissionDenied, "access denied"
+
+	case errors.Is(err, security.ErrInsufficientScope):
+		return codes.PermissionDenied, "insufficient scope"
+
+	case errors.Is(err, security.ErrTokenExpired):
+		return codes.Unauthenticated, "token expired"
+
+	case errors.Is(err, security.ErrTokenNotFound):
+		return codes.Unauthenticated, "token not found"
+
+	case errors.Is(err, security.ErrInvalidCredentials),
+		errors.Is(err, security.ErrClientSecretMismatch),
+		errors.Is(err, security.ErrAuthenticatorRefused):
+		return codes.Unauthenticated, "invalid credentials"
+
+	default:
+		return codes.Unauthenticated, "unauthenticated"
+	}
+}
diff --git a/grpc/error_mapper_test.go b/grpc/error_mapper_test.go
new file mode 100644
index 0000000..3cb0cec
--- /dev/null
+++ b/grpc/error_mapper_test.go
@@ -0,0 +1,50 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	"github.com/stretchr/testify/assert"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+func TestDefaultErrorMapperClassification(t *testing.T) {
+	t.Parallel()
+
+	mapper := grpcsec.DefaultErrorMapper()
+
+	cases := []struct {
+		name string
+		err  error
+		want codes.Code
+	}{
+		{"unsupported_credential", security.ErrUnsupportedCredential, codes.InvalidArgument},
+		{"access_denied", security.ErrAccessDenied, codes.PermissionDenied},
+		{"insufficient_scope", security.ErrInsufficientScope, codes.PermissionDenied},
+		{"token_expired", security.ErrTokenExpired, codes.Unauthenticated},
+		{"token_not_found", security.ErrTokenNotFound, codes.Unauthenticated},
+		{"invalid_credentials", security.ErrInvalidCredentials, codes.Unauthenticated},
+		{"client_secret_mismatch", security.ErrClientSecretMismatch, codes.Unauthenticated},
+		{"authenticator_refused", security.ErrAuthenticatorRefused, codes.Unauthenticated},
+		{"unknown_defaults_to_unauthenticated", errors.New("boom"), codes.Unauthenticated},
+		{"wrapped_access_denied", fmt.Errorf("ctx: %w", security.ErrAccessDenied), codes.PermissionDenied},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := mapper.Map(context.Background(), c.err)
+			assert.Equal(t, c.want, status.Code(got))
+		})
+	}
+}
diff --git a/grpc/example_test.go b/grpc/example_test.go
new file mode 100644
index 0000000..7759686
--- /dev/null
+++ b/grpc/example_test.go
@@ -0,0 +1,59 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	"github.com/hyperscale-stack/security/voter"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// Example wires the Bearer-token engine into a gRPC server: the
+// authentication interceptor validates the token, the authorization
+// interceptor enforces a role, and the call only reaches the handler when
+// both pass.
+func Example() {
+	engine := security.NewEngine(
+		security.NewManager(tokenAuthenticator{authorities: []string{"ROLE_ADMIN"}}),
+		tokenExtractor{},
+	)
+	adm := security.NewAffirmativeDecisionManager(voter.HasRole("ADMIN"))
+
+	// In a real server:
+	//
+	//	grpc.NewServer(
+	//	    grpc.ChainUnaryInterceptor(
+	//	        grpcsec.UnaryServerInterceptor(engine),
+	//	        grpcsec.UnaryAuthorize(adm, []security.Attribute{security.Role("ADMIN")}),
+	//	    ),
+	//	)
+	//
+	// Here we just demonstrate the error mapping the interceptors apply.
+	_ = engine
+	_ = adm
+
+	mapper := grpcsec.DefaultErrorMapper()
+	for _, err := range []error{
+		security.ErrInvalidCredentials,
+		security.ErrAccessDenied,
+		security.ErrUnsupportedCredential,
+	} {
+		fmt.Println(status.Code(mapper.Map(context.Background(), err)))
+	}
+
+	_ = healthpb.HealthCheckRequest{}
+	_ = codes.OK
+
+	// Output:
+	// Unauthenticated
+	// PermissionDenied
+	// InvalidArgument
+}
diff --git a/grpc/go.mod b/grpc/go.mod
new file mode 100644
index 0000000..688ca4f
--- /dev/null
+++ b/grpc/go.mod
@@ -0,0 +1,30 @@
+module github.com/hyperscale-stack/security/grpc
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	go.opentelemetry.io/otel v1.43.0
+	google.golang.org/grpc v1.69.2
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/sdk/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8 // indirect
+	google.golang.org/protobuf v1.36.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../
diff --git a/grpc/go.sum b/grpc/go.sum
new file mode 100644
index 0000000..87bdc7d
--- /dev/null
+++ b/grpc/go.sum
@@ -0,0 +1,54 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8 h1:TqExAhdPaB60Ux47Cn0oLV07rGnxZzIsaRhQaqS666A=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8/go.mod h1:lcTa1sDdWEIHMWlITnIczmw5w60CF9ffkb8Z+DVmmjA=
+google.golang.org/grpc v1.69.2 h1:U3S9QEtbXC0bYNvRtcoklF3xGtLViumSYxWykJS+7AU=
+google.golang.org/grpc v1.69.2/go.mod h1:vyjdE6jLBI76dgpDojsFGNaHlxdjXN9ghpnd2o7JGZ4=
+google.golang.org/protobuf v1.36.1 h1:yBPeRvTftaleIgM3PZ/WBIZ7XM/eEYAaEyCwvyjq/gk=
+google.golang.org/protobuf v1.36.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/grpc/interceptor.go b/grpc/interceptor.go
new file mode 100644
index 0000000..f233b97
--- /dev/null
+++ b/grpc/interceptor.go
@@ -0,0 +1,106 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"google.golang.org/grpc"
+)
+
+const tracerName = "github.com/hyperscale-stack/security/grpc"
+
+// authenticate runs the engine against the RPC metadata and returns the
+// enriched context. It is shared by the unary and stream interceptors.
+func authenticate(ctx context.Context, engine security.Engine, cfg *config, method string) (context.Context, error) {
+	ctx, span := otel.Tracer(tracerName).Start(ctx, "grpcsec.Authenticate")
+	defer span.End()
+
+	span.SetAttributes(attribute.String("rpc.method", method))
+
+	carrier := NewCarrier(ctx)
+
+	newCtx, auth, err := engine.Process(ctx, carrier)
+	if err != nil {
+		// "no extractor configured" is tolerated only when the caller
+		// opted into anonymous fallback; every other error is fatal.
+		tolerated := cfg.anonymousFallback && errors.Is(err, security.ErrNoExtractor)
+		if !tolerated {
+			return ctx, fmt.Errorf("grpcsec: authenticate: %w", err)
+		}
+	}
+
+	if !auth.IsAuthenticated() && !cfg.anonymousFallback {
+		return ctx, security.ErrInvalidCredentials
+	}
+
+	span.SetAttributes(attribute.Bool("security.authenticated", auth.IsAuthenticated()))
+
+	return newCtx, nil
+}
+
+// UnaryServerInterceptor authenticates every unary RPC. On success the
+// handler runs with the request context enriched via
+// [security.WithAuthentication]; on failure the configured [ErrorMapper]
+// turns the security error into a gRPC status error and the handler is
+// not invoked.
+//
+// It opens a "grpcsec.Authenticate" span but deliberately does NOT open an
+// "rpc" span — that belongs to otelgrpc, which users compose alongside
+// this interceptor.
+func UnaryServerInterceptor(engine security.Engine, opts ...Option) grpc.UnaryServerInterceptor {
+	cfg := buildConfig(opts...)
+
+	return func(
+		ctx context.Context,
+		req any,
+		info *grpc.UnaryServerInfo,
+		handler grpc.UnaryHandler,
+	) (any, error) {
+		newCtx, err := authenticate(ctx, engine, cfg, info.FullMethod)
+		if err != nil {
+			return nil, cfg.errorMapper.Map(ctx, err)
+		}
+
+		return handler(newCtx, req)
+	}
+}
+
+// StreamServerInterceptor is the streaming counterpart of
+// [UnaryServerInterceptor]. The wrapped stream exposes the enriched
+// context through ServerStream.Context().
+func StreamServerInterceptor(engine security.Engine, opts ...Option) grpc.StreamServerInterceptor {
+	cfg := buildConfig(opts...)
+
+	return func(
+		srv any,
+		ss grpc.ServerStream,
+		info *grpc.StreamServerInfo,
+		handler grpc.StreamHandler,
+	) error {
+		newCtx, err := authenticate(ss.Context(), engine, cfg, info.FullMethod)
+		if err != nil {
+			return cfg.errorMapper.Map(ss.Context(), err)
+		}
+
+		return handler(srv, &wrappedStream{ServerStream: ss, ctx: newCtx})
+	}
+}
+
+// wrappedStream overrides Context() so downstream handlers see the
+// authenticated context. Every other method delegates to the embedded
+// grpc.ServerStream.
+type wrappedStream struct {
+	grpc.ServerStream
+	ctx context.Context
+}
+
+// Context returns the security-enriched context.
+func (w *wrappedStream) Context() context.Context { return w.ctx }
diff --git a/grpc/interceptor_test.go b/grpc/interceptor_test.go
new file mode 100644
index 0000000..b77fce9
--- /dev/null
+++ b/grpc/interceptor_test.go
@@ -0,0 +1,155 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"sync"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	grpcsec "github.com/hyperscale-stack/security/grpc"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
+)
+
+func newEngine(authorities ...string) security.Engine {
+	return security.NewEngine(
+		security.NewManager(tokenAuthenticator{authorities: authorities}),
+		tokenExtractor{},
+	)
+}
+
+func bearer(ctx context.Context, token string) context.Context {
+	return metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token)
+}
+
+func TestUnaryInterceptorAllowsAuthenticatedCall(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, grpcsec.UnaryServerInterceptor(newEngine()), nil)
+
+	resp, err := client.Check(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+	assert.Equal(t, healthpb.HealthCheckResponse_SERVING, resp.GetStatus())
+}
+
+func TestUnaryInterceptorRejectsMissingCredential(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, grpcsec.UnaryServerInterceptor(newEngine()), nil)
+
+	_, err := client.Check(context.Background(), &healthpb.HealthCheckRequest{})
+	require.Error(t, err)
+	assert.Equal(t, codes.Unauthenticated, status.Code(err))
+}
+
+func TestUnaryInterceptorRejectsBadToken(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, grpcsec.UnaryServerInterceptor(newEngine()), nil)
+
+	_, err := client.Check(bearer(context.Background(), "wrong"), &healthpb.HealthCheckRequest{})
+	require.Error(t, err)
+	assert.Equal(t, codes.Unauthenticated, status.Code(err))
+}
+
+func TestUnaryInterceptorAnonymousFallbackLetsCallThrough(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t,
+		grpcsec.UnaryServerInterceptor(newEngine(), grpcsec.WithAnonymousFallback(true)),
+		nil,
+	)
+
+	// No credential, but the fallback lets the unary RPC reach the handler.
+	resp, err := client.Check(context.Background(), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+	assert.Equal(t, healthpb.HealthCheckResponse_SERVING, resp.GetStatus())
+}
+
+func TestStreamInterceptorAllowsAuthenticatedStream(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, nil, grpcsec.StreamServerInterceptor(newEngine()))
+
+	stream, err := client.Watch(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err)
+
+	// The health Watch server pushes at least one status update.
+	resp, err := stream.Recv()
+	require.NoError(t, err)
+	assert.Equal(t, healthpb.HealthCheckResponse_SERVING, resp.GetStatus())
+}
+
+func TestStreamInterceptorRejectsMissingCredential(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, nil, grpcsec.StreamServerInterceptor(newEngine()))
+
+	stream, err := client.Watch(context.Background(), &healthpb.HealthCheckRequest{})
+	require.NoError(t, err, "stream opens lazily; the error surfaces on Recv")
+
+	_, err = stream.Recv()
+	require.Error(t, err)
+	assert.Equal(t, codes.Unauthenticated, status.Code(err))
+}
+
+func TestInterceptorCustomErrorMapper(t *testing.T) {
+	t.Parallel()
+
+	mapper := &recordingMapper{ErrorMapper: grpcsec.DefaultErrorMapper()}
+	client := dialBufconn(t,
+		grpcsec.UnaryServerInterceptor(newEngine(), grpcsec.WithErrorMapper(mapper)),
+		nil,
+	)
+
+	_, err := client.Check(context.Background(), &healthpb.HealthCheckRequest{})
+	require.Error(t, err)
+	assert.True(t, mapper.called.Load())
+}
+
+type recordingMapper struct {
+	grpcsec.ErrorMapper
+	called atomicBool
+}
+
+func (m *recordingMapper) Map(ctx context.Context, err error) error {
+	m.called.Store(true)
+
+	return m.ErrorMapper.Map(ctx, err)
+}
+
+type atomicBool struct {
+	mu sync.Mutex
+	v  bool
+}
+
+func (a *atomicBool) Store(b bool) { a.mu.Lock(); a.v = b; a.mu.Unlock() }
+func (a *atomicBool) Load() bool   { a.mu.Lock(); defer a.mu.Unlock(); return a.v }
+
+func TestUnaryInterceptorIsRaceSafe(t *testing.T) {
+	t.Parallel()
+
+	client := dialBufconn(t, grpcsec.UnaryServerInterceptor(newEngine()), nil)
+
+	var wg sync.WaitGroup
+	for range 50 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			_, err := client.Check(bearer(context.Background(), "letmein"), &healthpb.HealthCheckRequest{})
+			assert.NoError(t, err)
+		}()
+	}
+
+	wg.Wait()
+}
diff --git a/grpc/options.go b/grpc/options.go
new file mode 100644
index 0000000..dc565cd
--- /dev/null
+++ b/grpc/options.go
@@ -0,0 +1,44 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec
+
+// config is the consolidated interceptor configuration, built from the
+// applied [Option] values.
+type config struct {
+	errorMapper       ErrorMapper
+	anonymousFallback bool
+}
+
+// Option configures an interceptor.
+type Option func(*config)
+
+// WithErrorMapper overrides the [ErrorMapper] used to translate security
+// errors into gRPC status errors. Defaults to [DefaultErrorMapper].
+func WithErrorMapper(m ErrorMapper) Option {
+	return func(c *config) {
+		if m != nil {
+			c.errorMapper = m
+		}
+	}
+}
+
+// WithAnonymousFallback controls what happens when no extractor finds a
+// credential. With true, the RPC proceeds carrying the anonymous
+// [security.Authentication] and downstream authorisation interceptors are
+// responsible for rejecting it. Default: false (reject with
+// codes.Unauthenticated immediately).
+func WithAnonymousFallback(allow bool) Option {
+	return func(c *config) { c.anonymousFallback = allow }
+}
+
+// buildConfig applies opts onto the default config.
+func buildConfig(opts ...Option) *config {
+	cfg := &config{errorMapper: DefaultErrorMapper()}
+	for _, o := range opts {
+		o(cfg)
+	}
+
+	return cfg
+}
diff --git a/grpc/testing_helpers_test.go b/grpc/testing_helpers_test.go
new file mode 100644
index 0000000..64fb8ec
--- /dev/null
+++ b/grpc/testing_helpers_test.go
@@ -0,0 +1,138 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grpcsec_test
+
+import (
+	"context"
+	"net"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/health"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+// The tests reuse the standard gRPC health service (grpc_health_v1) as the
+// guinea-pig service: Check is a unary RPC and Watch is a server stream,
+// so both interceptor kinds are exercised without generating any protobuf.
+
+// dialBufconn starts an in-memory gRPC server with the given interceptors,
+// registers the health service, and returns a connected client. Everything
+// is torn down via t.Cleanup.
+func dialBufconn(
+	t *testing.T,
+	unary grpc.UnaryServerInterceptor,
+	stream grpc.StreamServerInterceptor,
+) healthpb.HealthClient {
+	t.Helper()
+
+	lis := bufconn.Listen(1 << 20)
+
+	var serverOpts []grpc.ServerOption
+	if unary != nil {
+		serverOpts = append(serverOpts, grpc.UnaryInterceptor(unary))
+	}
+
+	if stream != nil {
+		serverOpts = append(serverOpts, grpc.StreamInterceptor(stream))
+	}
+
+	srv := grpc.NewServer(serverOpts...)
+	healthpb.RegisterHealthServer(srv, health.NewServer())
+
+	go func() { _ = srv.Serve(lis) }()
+
+	conn, err := grpc.NewClient(
+		"passthrough:///bufnet",
+		grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
+			return lis.DialContext(ctx)
+		}),
+		grpc.WithTransportCredentials(insecure.NewCredentials()),
+	)
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		_ = conn.Close()
+		srv.Stop()
+		_ = lis.Close()
+	})
+
+	return healthpb.NewHealthClient(conn)
+}
+
+// --- fakes mirroring the core test doubles ------------------------------
+
+type fakePrincipal struct{ sub string }
+
+func (p fakePrincipal) Subject() string { return p.sub }
+
+type fakeAuth struct {
+	pr            security.Principal
+	authorities   []string
+	authenticated bool
+}
+
+func newAuth(sub string, authorities ...string) fakeAuth {
+	return fakeAuth{pr: fakePrincipal{sub: sub}, authorities: authorities, authenticated: true}
+}
+
+func (a fakeAuth) Principal() security.Principal { return a.pr }
+func (a fakeAuth) Credentials() any              { return nil }
+func (a fakeAuth) Authorities() []string         { return a.authorities }
+func (a fakeAuth) IsAuthenticated() bool         { return a.authenticated }
+func (a fakeAuth) Name() string                  { return a.pr.Subject() }
+
+// tokenExtractor reads the "authorization" metadata key and produces a
+// pending bearer-like authentication carrying the raw token.
+type tokenExtractor struct{}
+
+func (tokenExtractor) Extract(_ context.Context, c security.Carrier) (security.Authentication, error) {
+	v := c.Get("authorization")
+	if v == "" {
+		return nil, nil
+	}
+
+	const prefix = "Bearer "
+	if len(v) <= len(prefix) {
+		return nil, nil
+	}
+
+	return pendingAuth{token: v[len(prefix):]}, nil
+}
+
+// pendingAuth is the un-validated authentication produced by tokenExtractor.
+type pendingAuth struct{ token string }
+
+func (a pendingAuth) Principal() security.Principal { return security.AnonymousPrincipal }
+func (a pendingAuth) Credentials() any              { return a.token }
+func (a pendingAuth) Authorities() []string         { return nil }
+func (a pendingAuth) IsAuthenticated() bool         { return false }
+func (a pendingAuth) Name() string                  { return "pending" }
+
+// tokenAuthenticator accepts the magic token "letmein" and rejects the rest.
+type tokenAuthenticator struct{ authorities []string }
+
+func (tokenAuthenticator) Supports(a security.Authentication) bool {
+	_, ok := a.(pendingAuth)
+
+	return ok
+}
+
+func (ta tokenAuthenticator) Authenticate(_ context.Context, a security.Authentication) (security.Authentication, error) {
+	p, ok := a.(pendingAuth)
+	if !ok {
+		return a, security.ErrUnsupportedCredential
+	}
+
+	if p.token != "letmein" {
+		return a, security.ErrInvalidCredentials
+	}
+
+	return newAuth("alice", ta.authorities...), nil
+}
diff --git a/http/authorize.go b/http/authorize.go
new file mode 100644
index 0000000..c534bd9
--- /dev/null
+++ b/http/authorize.go
@@ -0,0 +1,49 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+import (
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Authorize returns a middleware that asks an [security.AccessDecisionManager]
+// to decide whether the request may proceed. It MUST be installed AFTER
+// [Middleware] so that the request context carries an [security.Authentication].
+//
+// On grant, the next handler runs. On deny, the configured [ErrorMapper]
+// writes a response — typically 403 Forbidden. If the request never went
+// through [Middleware] (no Authentication in context), the anonymous value
+// is presented to the ADM, which generally denies.
+func Authorize(adm security.AccessDecisionManager, attrs ...security.Attribute) func(http.Handler) http.Handler {
+	return AuthorizeWith(adm, DefaultErrorMapper("Bearer", ""), attrs...)
+}
+
+// AuthorizeWith is the explicit-mapper variant of [Authorize] — useful for
+// authoritative servers that want a structured error body.
+func AuthorizeWith(
+	adm security.AccessDecisionManager,
+	mapper ErrorMapper,
+	attrs ...security.Attribute,
+) func(http.Handler) http.Handler {
+	if mapper == nil {
+		mapper = DefaultErrorMapper("Bearer", "")
+	}
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			auth, _ := security.FromContext(r.Context())
+
+			if err := adm.Decide(r.Context(), auth, attrs); err != nil {
+				mapper.Map(w, r, err)
+
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
diff --git a/http/authorize_test.go b/http/authorize_test.go
new file mode 100644
index 0000000..4beaeb0
--- /dev/null
+++ b/http/authorize_test.go
@@ -0,0 +1,84 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAuthorizeGrantsLetsNextRun(t *testing.T) {
+	t.Parallel()
+
+	called := false
+	h := httpsec.Authorize(scriptedADM{}, fakeAttr("scope:read"))(
+		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			called = true
+			w.WriteHeader(http.StatusOK)
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req = req.WithContext(security.WithAuthentication(req.Context(), newAuth("alice").verified()))
+
+	h.ServeHTTP(rec, req)
+
+	assert.True(t, called)
+	assert.Equal(t, http.StatusOK, rec.Result().StatusCode)
+}
+
+func TestAuthorizeDeniesWithForbidden(t *testing.T) {
+	t.Parallel()
+
+	h := httpsec.Authorize(scriptedADM{err: security.ErrAccessDenied}, fakeAttr("scope:read"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req = req.WithContext(security.WithAuthentication(req.Context(), newAuth("alice").verified()))
+
+	h.ServeHTTP(rec, req)
+	assert.Equal(t, http.StatusForbidden, rec.Result().StatusCode)
+}
+
+func TestAuthorizeInsufficientScopeIncludesOAuthErrorParam(t *testing.T) {
+	t.Parallel()
+
+	h := httpsec.Authorize(scriptedADM{err: security.ErrInsufficientScope}, fakeAttr("scope:write"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req = req.WithContext(security.WithAuthentication(req.Context(), newAuth("alice").verified()))
+
+	h.ServeHTTP(rec, req)
+	assert.Equal(t, http.StatusForbidden, rec.Result().StatusCode)
+
+	ww := rec.Header().Get("WWW-Authenticate")
+	assert.Contains(t, ww, `error="insufficient_scope"`)
+	assert.Contains(t, ww, `error_description="The request requires higher privileges than provided by the access token."`)
+}
+
+func TestAuthorizeUsesAnonymousWhenNoAuthInContext(t *testing.T) {
+	t.Parallel()
+
+	// scriptedADM deny -> Authorize must surface 403 even without a prior
+	// Middleware step (Authentication == Anonymous).
+	h := httpsec.Authorize(scriptedADM{err: security.ErrAccessDenied}, fakeAttr("scope:read"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	)
+
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+	assert.Equal(t, http.StatusForbidden, rec.Result().StatusCode)
+}
diff --git a/http/carrier.go b/http/carrier.go
new file mode 100644
index 0000000..ef2aa2b
--- /dev/null
+++ b/http/carrier.go
@@ -0,0 +1,104 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+import (
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Carrier adapts an *http.Request / http.ResponseWriter pair to
+// [security.Carrier]. Reads consult headers first, then cookies, then query
+// parameters, so header-borne credentials take precedence over URL-borne ones
+// (an important defense against credentials leaking through access logs).
+//
+// Writes go to the response writer's header — useful for issuing
+// WWW-Authenticate challenges or refreshing a session cookie.
+//
+// Carrier is NOT safe for concurrent use; one instance per request.
+type Carrier struct {
+	req *http.Request
+	rw  http.ResponseWriter
+}
+
+// NewCarrier wraps the request/response pair. Either argument MAY be nil:
+//   - a nil request makes every Get/Values/Cookie return "" / nil;
+//   - a nil response writer makes every Set/Add a no-op (useful in tests).
+func NewCarrier(rw http.ResponseWriter, req *http.Request) *Carrier {
+	return &Carrier{req: req, rw: rw}
+}
+
+// Request returns the wrapped *http.Request. Middlewares wishing to
+// propagate context updates SHOULD prefer Carrier.WithContext().
+func (c *Carrier) Request() *http.Request { return c.req }
+
+// WithContext returns a new Carrier whose underlying request carries ctx.
+// The ResponseWriter is shared (write-side state lives in the writer).
+func (c *Carrier) WithContext(req *http.Request) *Carrier {
+	return &Carrier{req: req, rw: c.rw}
+}
+
+// Get implements [security.Carrier]. Lookup order: header > cookie > query.
+func (c *Carrier) Get(key string) string {
+	if c.req == nil {
+		return ""
+	}
+
+	if v := c.req.Header.Get(key); v != "" {
+		return v
+	}
+
+	if ck, err := c.req.Cookie(key); err == nil {
+		return ck.Value
+	}
+
+	return c.req.URL.Query().Get(key)
+}
+
+// Values implements [security.Carrier]. Header multi-values take precedence;
+// when none are present, cookies (single value) then query parameters
+// (multi-value) are consulted in that order.
+func (c *Carrier) Values(key string) []string {
+	if c.req == nil {
+		return nil
+	}
+
+	if vs := c.req.Header.Values(key); len(vs) > 0 {
+		return vs
+	}
+
+	if ck, err := c.req.Cookie(key); err == nil {
+		return []string{ck.Value}
+	}
+
+	if vs := c.req.URL.Query()[key]; len(vs) > 0 {
+		return vs
+	}
+
+	return nil
+}
+
+// Set implements [security.Carrier]. It writes to the ResponseWriter's
+// header, which controls outbound HTTP responses (e.g. WWW-Authenticate).
+func (c *Carrier) Set(key, value string) {
+	if c.rw == nil {
+		return
+	}
+
+	c.rw.Header().Set(key, value)
+}
+
+// Add implements [security.Carrier]. Appends to the response header.
+func (c *Carrier) Add(key, value string) {
+	if c.rw == nil {
+		return
+	}
+
+	c.rw.Header().Add(key, value)
+}
+
+// Compile-time check that Carrier implements security.Carrier.
+var _ security.Carrier = (*Carrier)(nil)
diff --git a/http/carrier_test.go b/http/carrier_test.go
new file mode 100644
index 0000000..373e4d8
--- /dev/null
+++ b/http/carrier_test.go
@@ -0,0 +1,104 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCarrierLookupOrderIsHeaderThenCookieThenQuery(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/?Authorization=q", nil)
+	req.Header.Set("Authorization", "h")
+	req.AddCookie(&http.Cookie{Name: "Authorization", Value: "c"})
+
+	c := httpsec.NewCarrier(httptest.NewRecorder(), req)
+	assert.Equal(t, "h", c.Get("Authorization"), "header wins")
+
+	// Drop header -> cookie wins
+	req.Header.Del("Authorization")
+	c = httpsec.NewCarrier(httptest.NewRecorder(), req)
+	assert.Equal(t, "c", c.Get("Authorization"))
+
+	// Drop cookie too -> query wins
+	req2 := httptest.NewRequest(http.MethodGet, "/?Authorization=q", nil)
+	c = httpsec.NewCarrier(httptest.NewRecorder(), req2)
+	assert.Equal(t, "q", c.Get("Authorization"))
+}
+
+func TestCarrierValuesPrefersHeaderMultiValues(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/?X-Foo=q1&X-Foo=q2", nil)
+	req.Header.Add("X-Foo", "h1")
+	req.Header.Add("X-Foo", "h2")
+
+	c := httpsec.NewCarrier(httptest.NewRecorder(), req)
+	assert.Equal(t, []string{"h1", "h2"}, c.Values("X-Foo"))
+}
+
+func TestCarrierSetWritesToResponseHeader(t *testing.T) {
+	t.Parallel()
+
+	rec := httptest.NewRecorder()
+	c := httpsec.NewCarrier(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	c.Set("WWW-Authenticate", "Bearer")
+	c.Add("WWW-Authenticate", "Basic")
+
+	require.Equal(t, []string{"Bearer", "Basic"}, rec.Header().Values("WWW-Authenticate"))
+}
+
+func TestCarrierWithNilRequestAndWriterIsSafe(t *testing.T) {
+	t.Parallel()
+
+	c := httpsec.NewCarrier(nil, nil)
+
+	assert.Equal(t, "", c.Get("anything"))
+	assert.Nil(t, c.Values("anything"))
+	c.Set("X", "Y") // must not panic
+	c.Add("X", "Y") // must not panic
+}
+
+func TestCarrierExposesUnderlyingRequest(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	c := httpsec.NewCarrier(httptest.NewRecorder(), req)
+	assert.Same(t, req, c.Request())
+}
+
+func TestExtractAuthorizationValueIsCaseInsensitive(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name, scheme, header, want string
+		ok                         bool
+	}{
+		{"bearer_lower", "Bearer", "bearer abc", "abc", true},
+		{"bearer_upper", "Bearer", "BEARER abc", "abc", true},
+		{"basic", "Basic", "Basic Zm9vOmJhcg==", "Zm9vOmJhcg==", true},
+		{"wrong_scheme", "Basic", "Bearer xyz", "", false},
+		{"too_short", "Bearer", "Bea", "", false},
+		{"empty", "Bearer", "", "", false},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, ok := httpsec.ExtractAuthorizationValue(c.scheme, c.header)
+			assert.Equal(t, c.want, got)
+			assert.Equal(t, c.ok, ok)
+		})
+	}
+}
diff --git a/http/doc.go b/http/doc.go
new file mode 100644
index 0000000..e3ba13a
--- /dev/null
+++ b/http/doc.go
@@ -0,0 +1,20 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package httpsec is the net/http transport adapter for the security core.
+//
+// It wires the transport-agnostic primitives of the core (Carrier, Extractor,
+// Authenticator, Engine, AccessDecisionManager) into standard net/http
+// middleware chains. The middleware can be plugged into any router that
+// accepts http.Handler — net/http.ServeMux, chi, gorilla/mux, gin's http
+// adapter, etc.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - go.opentelemetry.io/otel
+//   - stdlib only
+//
+// Forbidden dependencies: gRPC, any HTTP router (the package is router-
+// agnostic), any concrete logger.
+package httpsec
diff --git a/http/error_mapper.go b/http/error_mapper.go
new file mode 100644
index 0000000..7f075ba
--- /dev/null
+++ b/http/error_mapper.go
@@ -0,0 +1,131 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// defaultChallengeScheme is the WWW-Authenticate scheme used when none is
+// configured — RFC 6750 bearer tokens.
+const defaultChallengeScheme = "Bearer"
+
+// ErrorMapper translates a security error into an HTTP response. Custom
+// mappers can produce structured (JSON, ProtoBuf) error bodies or emit
+// transport-specific challenges.
+//
+// Implementations MUST be safe for concurrent use and MUST write the
+// response status before any body bytes.
+type ErrorMapper interface {
+	Map(w http.ResponseWriter, r *http.Request, err error)
+}
+
+// DefaultErrorMapper returns the canonical mapper used by the [Middleware]
+// when WithErrorMapper is not supplied. It produces:
+//
+//   - 400 Bad Request          for [security.ErrUnsupportedCredential]
+//   - 401 Unauthorized         for ErrInvalidCredentials, ErrClientSecretMismatch,
+//     ErrTokenExpired, ErrTokenNotFound,
+//     ErrAuthenticatorRefused, and any other
+//     non-classified error
+//   - 403 Forbidden            for ErrAccessDenied
+//   - 403 Forbidden with `error="insufficient_scope"` for ErrInsufficientScope
+//
+// 401 and 403 responses carry a WWW-Authenticate header following RFC 7235
+// (challenge scheme + realm) and RFC 6750 §3 (error / error_description for
+// OAuth2 bearer flows). The error_description is a fixed, generic string per
+// RFC 6750 error code — the underlying error chain is never reflected into
+// the header, so internal wrapping context cannot leak to clients.
+func DefaultErrorMapper(scheme, realm string) ErrorMapper {
+	if scheme == "" {
+		scheme = defaultChallengeScheme
+	}
+
+	return &defaultErrorMapper{scheme: scheme, realm: realm}
+}
+
+type defaultErrorMapper struct {
+	scheme string
+	realm  string
+}
+
+// Map implements [ErrorMapper].
+func (m *defaultErrorMapper) Map(w http.ResponseWriter, _ *http.Request, err error) {
+	status, oauthErr, desc := classify(err)
+
+	if status == http.StatusUnauthorized || status == http.StatusForbidden {
+		w.Header().Set("WWW-Authenticate", m.challenge(oauthErr, desc))
+	}
+
+	http.Error(w, http.StatusText(status), status)
+}
+
+// challenge formats an RFC 7235 / RFC 6750 challenge string. oauthErr, when
+// non-empty, populates the `error` parameter so OAuth2 clients can react
+// programmatically (typical values: "invalid_token", "insufficient_scope").
+// desc is a fixed, generic description: it is never derived from the error
+// chain, so internal wrapping context cannot leak into the header.
+func (m *defaultErrorMapper) challenge(oauthErr, desc string) string {
+	out := m.scheme
+
+	if m.realm != "" {
+		out += fmt.Sprintf(" realm=%q", m.realm)
+	}
+
+	if oauthErr != "" {
+		sep := " "
+		if m.realm != "" {
+			sep = ", "
+		}
+
+		out += sep + fmt.Sprintf("error=%q", oauthErr)
+
+		if desc != "" {
+			out += fmt.Sprintf(`, error_description=%q`, desc)
+		}
+	}
+
+	return out
+}
+
+// RFC 6750 §3.1 error_description strings. These are intentionally fixed and
+// generic: a verbatim error message would leak internal wrapping context
+// (timestamps, package names, consumer-supplied store errors) to the client.
+const (
+	descInvalidToken      = "The access token is invalid or has expired."
+	descInsufficientScope = "The request requires higher privileges than provided by the access token."
+)
+
+// classify maps an error to (httpStatus, oauthErrorCode, errorDescription).
+// The oauthErrorCode and errorDescription are populated only for the cases
+// RFC 6750 §3.1 calls out; errorDescription is always a fixed string.
+func classify(err error) (int, string, string) {
+	switch {
+	case errors.Is(err, security.ErrUnsupportedCredential):
+		return http.StatusBadRequest, "", ""
+
+	case errors.Is(err, security.ErrAccessDenied):
+		return http.StatusForbidden, "", ""
+
+	case errors.Is(err, security.ErrInsufficientScope):
+		return http.StatusForbidden, "insufficient_scope", descInsufficientScope
+
+	case errors.Is(err, security.ErrTokenExpired),
+		errors.Is(err, security.ErrTokenNotFound):
+		return http.StatusUnauthorized, "invalid_token", descInvalidToken
+
+	case errors.Is(err, security.ErrInvalidCredentials),
+		errors.Is(err, security.ErrClientSecretMismatch),
+		errors.Is(err, security.ErrAuthenticatorRefused):
+		return http.StatusUnauthorized, "", ""
+
+	default:
+		return http.StatusUnauthorized, "", ""
+	}
+}
diff --git a/http/example_test.go b/http/example_test.go
new file mode 100644
index 0000000..c66203e
--- /dev/null
+++ b/http/example_test.go
@@ -0,0 +1,104 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/hyperscale-stack/security"
+	httpsec "github.com/hyperscale-stack/security/http"
+)
+
+// ExampleMiddleware shows wiring a [security.Engine] into a net/http server
+// with a header-based extractor and a stub authenticator that hands back an
+// authenticated value when the magic token is presented.
+func ExampleMiddleware() {
+	extractor := exExtractor{}
+	authn := exAuthn{}
+
+	engine := security.NewEngine(security.NewManager(authn), extractor)
+
+	handler := httpsec.Middleware(engine, httpsec.WithRealm("demo"))(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			auth, _ := security.FromContext(r.Context())
+			_, _ = fmt.Fprintf(w, "hello %s\n", auth.Principal().Subject())
+		}),
+	)
+
+	for _, token := range []string{"", "bad", "letmein"} {
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		if token != "" {
+			req.Header.Set("Authorization", "Bearer "+token)
+		}
+
+		rec := httptest.NewRecorder()
+		handler.ServeHTTP(rec, req)
+
+		body, _ := io.ReadAll(rec.Result().Body)
+		_ = rec.Result().Body.Close()
+		fmt.Printf("status=%d body=%s\n", rec.Result().StatusCode, strings.TrimSpace(string(body)))
+	}
+	// Output:
+	// status=401 body=Unauthorized
+	// status=401 body=Unauthorized
+	// status=200 body=hello alice
+}
+
+type exExtractor struct{}
+
+func (exExtractor) Extract(_ context.Context, c security.Carrier) (security.Authentication, error) {
+	v := c.Get("Authorization")
+	if v == "" {
+		return nil, nil
+	}
+
+	tok, ok := httpsec.ExtractAuthorizationValue("Bearer", v)
+	if !ok {
+		return nil, nil
+	}
+
+	return demoAuth{token: tok}, nil
+}
+
+type exAuthn struct{}
+
+func (exAuthn) Supports(a security.Authentication) bool {
+	_, ok := a.(demoAuth)
+
+	return ok
+}
+
+func (exAuthn) Authenticate(_ context.Context, a security.Authentication) (security.Authentication, error) {
+	d := a.(demoAuth)
+	if d.token != "letmein" {
+		return a, security.ErrInvalidCredentials
+	}
+
+	return demoAuth{token: d.token, name: "alice", authed: true}, nil
+}
+
+type demoAuth struct {
+	token  string
+	name   string
+	authed bool
+}
+
+func (d demoAuth) Principal() security.Principal {
+	return demoPrincipal{sub: d.name}
+}
+
+func (d demoAuth) Credentials() any      { return d.token }
+func (d demoAuth) Authorities() []string { return nil }
+func (d demoAuth) IsAuthenticated() bool { return d.authed }
+func (d demoAuth) Name() string          { return d.name }
+
+type demoPrincipal struct{ sub string }
+
+func (p demoPrincipal) Subject() string { return p.sub }
diff --git a/http/extra_test.go b/http/extra_test.go
new file mode 100644
index 0000000..c722ddc
--- /dev/null
+++ b/http/extra_test.go
@@ -0,0 +1,50 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCarrierWithContext(t *testing.T) {
+	t.Parallel()
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	carrier := httpsec.NewCarrier(httptest.NewRecorder(), req)
+
+	type ctxKey struct{}
+
+	enriched := req.WithContext(context.WithValue(req.Context(), ctxKey{}, "v"))
+	next := carrier.WithContext(enriched)
+
+	assert.Equal(t, "v", next.Request().Context().Value(ctxKey{}))
+	// The original carrier is left untouched.
+	assert.Nil(t, carrier.Request().Context().Value(ctxKey{}))
+}
+
+// TestWithChallengeScheme checks that the option changes the scheme
+// advertised in the WWW-Authenticate header on a 401.
+func TestWithChallengeScheme(t *testing.T) {
+	t.Parallel()
+
+	engine := security.NewEngine(security.NewManager())
+
+	handler := httpsec.Middleware(engine, httpsec.WithChallengeScheme("Basic"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), "Basic")
+}
diff --git a/http/go.mod b/http/go.mod
new file mode 100644
index 0000000..122cb48
--- /dev/null
+++ b/http/go.mod
@@ -0,0 +1,23 @@
+module github.com/hyperscale-stack/security/http
+
+go 1.26
+
+replace github.com/hyperscale-stack/security => ../
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	go.opentelemetry.io/otel v1.43.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
diff --git a/http/go.sum b/http/go.sum
new file mode 100644
index 0000000..56bdaa2
--- /dev/null
+++ b/http/go.sum
@@ -0,0 +1,40 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/http/header.go b/http/header.go
new file mode 100644
index 0000000..5514b5c
--- /dev/null
+++ b/http/header.go
@@ -0,0 +1,25 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+import "strings"
+
+// ExtractAuthorizationValue parses an "Authorization" header value of the
+// form "<scheme> <value>" and returns the (value, true) pair when scheme
+// matches case-insensitively. It returns ("", false) when the input does
+// not start with the expected scheme — the canonical fast-path for
+// scheme-specific extractors (Basic, Bearer, etc.).
+//
+// Scheme-specific extractors (basic, bearer) carry their own copy of this
+// helper to stay free of an httpsec dependency; this exported version is
+// the one application code should reach for.
+func ExtractAuthorizationValue(scheme, header string) (string, bool) {
+	prefix := scheme + " "
+	if len(header) < len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+		return "", false
+	}
+
+	return header[len(prefix):], true
+}
diff --git a/http/header/extract_authorization.go b/http/header/extract_authorization.go
deleted file mode 100644
index 88641bf..0000000
--- a/http/header/extract_authorization.go
+++ /dev/null
@@ -1,20 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package header
-
-import (
-	"strings"
-)
-
-// ExtractAuthorizationValue returns the value without t.
-func ExtractAuthorizationValue(t string, value string) (string, bool) {
-	prefix := t + " "
-
-	if len(value) < len(prefix) || !strings.EqualFold(value[:len(prefix)], prefix) {
-		return "", false
-	}
-
-	return value[len(prefix):], true
-}
diff --git a/http/header/extract_authorization_test.go b/http/header/extract_authorization_test.go
deleted file mode 100644
index 058a5c9..0000000
--- a/http/header/extract_authorization_test.go
+++ /dev/null
@@ -1,30 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package header
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestExtractAuthorizationValue(t *testing.T) {
-	creds, ok := ExtractAuthorizationValue("Basic", "Basic Zm9vOnBhc3M=")
-	assert.True(t, ok)
-	assert.Equal(t, "Zm9vOnBhc3M=", creds)
-}
-
-func TestExtractAuthorizationValueWithBadType(t *testing.T) {
-	creds, ok := ExtractAuthorizationValue("Digest", "Basic Zm9vOnBhc3M=")
-	assert.False(t, ok)
-	assert.Empty(t, creds)
-}
-
-func BenchmarkExtractAuthorizationValue(b *testing.B) {
-	// run the Fib function b.N times
-	for n := 0; n < b.N; n++ {
-		ExtractAuthorizationValue("Basic", "Basic Zm9vOnBhc3M=")
-	}
-}
diff --git a/http/middleware.go b/http/middleware.go
new file mode 100644
index 0000000..8bcc167
--- /dev/null
+++ b/http/middleware.go
@@ -0,0 +1,112 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	"github.com/hyperscale-stack/security"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+const tracerName = "github.com/hyperscale-stack/security/http"
+
+// Attribute keys emitted by the HTTP middleware. The "security." prefix
+// keeps the namespace aligned with the core; the few HTTP-specific facts
+// (method, route) reuse the OpenTelemetry semantic conventions.
+const (
+	attrHTTPMethod      = attribute.Key("http.method")
+	attrHTTPRoute       = attribute.Key("http.route")
+	attrSecurityHandled = attribute.Key("security.handled")
+)
+
+// Middleware wires a [security.Engine] into the net/http pipeline.
+//
+// On success the next handler runs with the request context enriched via
+// [security.WithAuthentication]. On failure the configured [ErrorMapper]
+// writes the response and the next handler is NOT invoked.
+//
+// When no extractor finds any credential the behavior depends on
+// [WithAnonymousFallback]: by default the request is rejected with
+// 401 Unauthorized, so applications fail closed.
+func Middleware(engine security.Engine, opts ...Option) func(http.Handler) http.Handler {
+	cfg := buildConfig(opts...)
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			ctx, span := otel.Tracer(tracerName).Start(r.Context(), "httpsec.Middleware")
+			defer span.End()
+
+			span.SetAttributes(
+				attrHTTPMethod.String(r.Method),
+				attrHTTPRoute.String(routeFromContext(ctx, r)),
+			)
+
+			carrier := NewCarrier(w, r.WithContext(ctx))
+
+			newCtx, auth, err := engine.Process(ctx, carrier)
+			if err != nil && !isNoCredential(err, cfg) {
+				cfg.errorMapper.Map(w, r, err)
+
+				return
+			}
+
+			if !auth.IsAuthenticated() && !cfg.anonymousFallback {
+				cfg.errorMapper.Map(w, r, security.ErrInvalidCredentials)
+
+				return
+			}
+
+			span.SetAttributes(attrSecurityHandled.Bool(true))
+
+			next.ServeHTTP(w, r.WithContext(newCtx))
+		})
+	}
+}
+
+// buildConfig applies opts to a default config — a Bearer challenge with
+// an empty realm and no anonymous fallback (deny-by-default).
+func buildConfig(opts ...Option) *config {
+	cfg := &config{
+		challengeScheme: defaultChallengeScheme,
+	}
+
+	for _, o := range opts {
+		o(cfg)
+	}
+
+	if cfg.errorMapper == nil {
+		cfg.errorMapper = DefaultErrorMapper(cfg.challengeScheme, cfg.realm)
+	}
+
+	return cfg
+}
+
+// isNoCredential reports whether err means "no credential found" — the
+// engine returns ErrNoExtractor for that. We treat it the same way as a
+// successful anonymous extraction so callers needing to fail open can set
+// WithAnonymousFallback without also having to filter on this error.
+func isNoCredential(err error, cfg *config) bool {
+	if !errors.Is(err, security.ErrNoExtractor) {
+		return false
+	}
+
+	return cfg.anonymousFallback
+}
+
+// routeFromContext returns the http.route attribute. The stdlib mux does not
+// publish a route abstraction, so we fall back to the URL path. Adapters for
+// chi / gorilla / gin can install a context value under the same private
+// type to override this.
+func routeFromContext(_ context.Context, r *http.Request) string {
+	if r == nil || r.URL == nil {
+		return ""
+	}
+
+	return r.URL.Path
+}
diff --git a/http/middleware_bench_test.go b/http/middleware_bench_test.go
new file mode 100644
index 0000000..ef6337b
--- /dev/null
+++ b/http/middleware_bench_test.go
@@ -0,0 +1,39 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	httpsec "github.com/hyperscale-stack/security/http"
+)
+
+// BenchmarkMiddleware measures the overhead introduced by the
+// Engine -> Carrier -> ErrorMapper pipeline on a hot path. It does NOT
+// exercise the OTel exporter so numbers reflect the no-export case.
+func BenchmarkMiddleware(b *testing.B) {
+	authed := newAuth("alice").verified()
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "x", result: authed}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	mw := httpsec.Middleware(engine)(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rec := httptest.NewRecorder()
+
+	b.ReportAllocs()
+	b.ResetTimer()
+
+	for b.Loop() {
+		mw.ServeHTTP(rec, req)
+	}
+}
diff --git a/http/middleware_test.go b/http/middleware_test.go
new file mode 100644
index 0000000..a284d74
--- /dev/null
+++ b/http/middleware_test.go
@@ -0,0 +1,238 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestMiddlewareSuccessStoresAuthInContext(t *testing.T) {
+	t.Parallel()
+
+	authed := newAuth("alice").verified()
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "test", result: authed}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	var seen security.Authentication
+
+	next := http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+		seen, _ = security.FromContext(r.Context())
+	})
+
+	rec := httptest.NewRecorder()
+	httpsec.Middleware(engine)(next).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	require.NotNil(t, seen)
+	assert.True(t, seen.IsAuthenticated())
+	assert.Equal(t, "alice", seen.Principal().Subject())
+	assert.Equal(t, http.StatusOK, rec.Result().StatusCode)
+}
+
+func TestMiddlewareDeniesAnonymousByDefault(t *testing.T) {
+	t.Parallel()
+
+	engine := security.NewEngine(security.NewManager(), scriptedExtractor{})
+
+	rec := httptest.NewRecorder()
+	httpsec.Middleware(engine)(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+		t.Fatal("next must not run")
+	})).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Result().StatusCode)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), "Bearer")
+}
+
+func TestMiddlewareLetsAnonymousThroughWhenOptedIn(t *testing.T) {
+	t.Parallel()
+
+	engine := security.NewEngine(security.NewManager(), scriptedExtractor{})
+
+	rec := httptest.NewRecorder()
+	called := false
+	httpsec.Middleware(engine, httpsec.WithAnonymousFallback(true))(
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			called = true
+			auth, _ := security.FromContext(r.Context())
+			assert.False(t, auth.IsAuthenticated(), "anonymous is unauthenticated")
+			w.WriteHeader(http.StatusTeapot)
+		}),
+	).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	assert.True(t, called)
+	assert.Equal(t, http.StatusTeapot, rec.Result().StatusCode)
+}
+
+func TestMiddlewareErrorMappingShortCircuits(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		err  error
+		want int
+	}{
+		{"unsupported", security.ErrUnsupportedCredential, http.StatusBadRequest},
+		{"invalid", security.ErrInvalidCredentials, http.StatusUnauthorized},
+		{"expired", security.ErrTokenExpired, http.StatusUnauthorized},
+		{"not_found", security.ErrTokenNotFound, http.StatusUnauthorized},
+		{"unknown", errors.New("boom"), http.StatusUnauthorized},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			engine := security.NewEngine(
+				security.NewManager(&scriptedAuthn{name: "x", err: c.err}),
+				scriptedExtractor{auth: newAuth("alice")},
+			)
+
+			rec := httptest.NewRecorder()
+			httpsec.Middleware(engine)(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+				t.Fatal("next must not run on auth error")
+			})).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+			assert.Equal(t, c.want, rec.Result().StatusCode)
+		})
+	}
+}
+
+func TestMiddlewareWWWAuthenticateIncludesRealm(t *testing.T) {
+	t.Parallel()
+
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "x", err: security.ErrTokenExpired}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	rec := httptest.NewRecorder()
+	httpsec.Middleware(engine, httpsec.WithRealm("hyperscale"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	ww := rec.Header().Get("WWW-Authenticate")
+	assert.True(t, strings.Contains(ww, `realm="hyperscale"`),
+		"realm must be included; got %q", ww)
+	assert.True(t, strings.Contains(ww, `error="invalid_token"`),
+		"OAuth2 error parameter must be present for token expiry; got %q", ww)
+	assert.True(t, strings.Contains(ww, `error_description="The access token is invalid or has expired."`),
+		"error_description must be the fixed RFC 6750 string; got %q", ww)
+}
+
+// TestMiddlewareWWWAuthenticateDoesNotLeakErrorDetail ensures the challenge
+// never reflects the wrapped error chain — only a fixed RFC 6750 description.
+// A custom TokenVerifier may wrap a sensitive value (token, DSN, DB error)
+// while still wrapping a core sentinel; that context must not reach the header.
+func TestMiddlewareWWWAuthenticateDoesNotLeakErrorDetail(t *testing.T) {
+	t.Parallel()
+
+	const secret = "tok_S3CRET-do-not-leak"
+	leaky := fmt.Errorf("redis GET %q failed: %w", secret, security.ErrTokenExpired)
+
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "x", err: leaky}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	rec := httptest.NewRecorder()
+	httpsec.Middleware(engine, httpsec.WithRealm("hyperscale"))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	ww := rec.Header().Get("WWW-Authenticate")
+	assert.NotContains(t, ww, secret, "wrapped error detail must not leak into the header")
+	assert.NotContains(t, ww, "redis GET", "wrapped error context must not leak into the header")
+	assert.Contains(t, ww, `error="invalid_token"`)
+	assert.Contains(t, ww, `error_description="The access token is invalid or has expired."`)
+}
+
+func TestMiddlewareCustomErrorMapperIsHonored(t *testing.T) {
+	t.Parallel()
+
+	custom := &customMapper{}
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "x", err: security.ErrInvalidCredentials}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	rec := httptest.NewRecorder()
+	httpsec.Middleware(engine, httpsec.WithErrorMapper(custom))(
+		http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("must not run") }),
+	).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+	assert.True(t, custom.invoked.Load())
+}
+
+type customMapper struct{ invoked atomicBool }
+
+func (m *customMapper) Map(w http.ResponseWriter, _ *http.Request, _ error) {
+	m.invoked.Store(true)
+	w.WriteHeader(http.StatusTeapot)
+}
+
+// atomicBool is a tiny race-safe boolean used by tests; std atomic.Bool
+// would do as well but is only available in modern Go versions.
+type atomicBool struct {
+	v sync.Mutex
+	s bool
+}
+
+func (a *atomicBool) Store(b bool) {
+	a.v.Lock()
+	defer a.v.Unlock()
+	a.s = b
+}
+
+func (a *atomicBool) Load() bool {
+	a.v.Lock()
+	defer a.v.Unlock()
+	return a.s
+}
+
+func TestMiddlewareIsRaceSafeUnderConcurrentRequests(t *testing.T) {
+	t.Parallel()
+
+	authed := newAuth("alice").verified()
+	engine := security.NewEngine(
+		security.NewManager(&scriptedAuthn{name: "x", result: authed}),
+		scriptedExtractor{auth: newAuth("alice")},
+	)
+
+	mw := httpsec.Middleware(engine)(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = io.WriteString(w, "ok")
+	}))
+
+	var wg sync.WaitGroup
+
+	for range 100 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			rec := httptest.NewRecorder()
+			mw.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
+
+			if rec.Result().StatusCode != http.StatusOK {
+				t.Errorf("got %d", rec.Result().StatusCode)
+			}
+		}()
+	}
+
+	wg.Wait()
+}
diff --git a/http/options.go b/http/options.go
new file mode 100644
index 0000000..3fc8f96
--- /dev/null
+++ b/http/options.go
@@ -0,0 +1,47 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec
+
+// config is the consolidated configuration of a [Middleware]. It is built up
+// by applying [Option] values to a zero value carrying sensible defaults.
+type config struct {
+	errorMapper       ErrorMapper
+	realm             string
+	challengeScheme   string
+	anonymousFallback bool
+}
+
+// Option configures a [Middleware]. Options compose via Middleware([options...]).
+type Option func(*config)
+
+// WithErrorMapper overrides the [ErrorMapper] used to translate security
+// errors into HTTP responses. The default mapper produces RFC 7235-compliant
+// 401/403/400 responses with a configurable challenge scheme.
+func WithErrorMapper(m ErrorMapper) Option {
+	return func(c *config) { c.errorMapper = m }
+}
+
+// WithRealm sets the "realm" parameter of WWW-Authenticate challenges sent by
+// the default [ErrorMapper]. RFC 7235 §2.2 allows realm to be any quoted
+// string; consumers MUST NOT rely on its value for authorisation decisions.
+func WithRealm(realm string) Option {
+	return func(c *config) { c.realm = realm }
+}
+
+// WithChallengeScheme overrides the authentication scheme advertised by the
+// default [ErrorMapper] (e.g. "Bearer", "Basic"). Default: "Bearer".
+func WithChallengeScheme(scheme string) Option {
+	return func(c *config) { c.challengeScheme = scheme }
+}
+
+// WithAnonymousFallback controls what happens when no extractor finds any
+// credential. When set to true, the middleware lets the request through with
+// the anonymous [security.Authentication]; downstream code (e.g.
+// [Authorize]) is responsible for the rejection.
+//
+// Default: false (strict — return 401 immediately).
+func WithAnonymousFallback(allow bool) Option {
+	return func(c *config) { c.anonymousFallback = allow }
+}
diff --git a/http/testing_helpers_test.go b/http/testing_helpers_test.go
new file mode 100644
index 0000000..c18054c
--- /dev/null
+++ b/http/testing_helpers_test.go
@@ -0,0 +1,78 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package httpsec_test
+
+import (
+	"context"
+	"sync/atomic"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// fakePrincipal/fakeAuth mirror the helpers used by the core tests; copied
+// here to avoid cross-module test imports.
+type fakePrincipal struct{ sub string }
+
+func (p fakePrincipal) Subject() string { return p.sub }
+
+type fakeAuth struct {
+	pr            security.Principal
+	creds         any
+	authorities   []string
+	authenticated bool
+}
+
+func newAuth(sub string, authorities ...string) fakeAuth {
+	return fakeAuth{pr: fakePrincipal{sub: sub}, authorities: authorities}
+}
+
+func (a fakeAuth) Principal() security.Principal { return a.pr }
+func (a fakeAuth) Credentials() any              { return a.creds }
+func (a fakeAuth) Authorities() []string         { return a.authorities }
+func (a fakeAuth) IsAuthenticated() bool         { return a.authenticated }
+func (a fakeAuth) Name() string                  { return a.pr.Subject() }
+
+func (a fakeAuth) verified() fakeAuth { a.authenticated = true; return a }
+
+// scriptedExtractor returns a fixed (auth, err) tuple.
+type scriptedExtractor struct {
+	auth security.Authentication
+	err  error
+}
+
+func (s scriptedExtractor) Extract(_ context.Context, _ security.Carrier) (security.Authentication, error) {
+	return s.auth, s.err
+}
+
+// scriptedAuthn validates by returning the configured result with race-safe
+// invocation counter.
+type scriptedAuthn struct {
+	name   string
+	result security.Authentication
+	err    error
+	calls  atomic.Int32
+}
+
+func (s *scriptedAuthn) AuthenticatorName() string         { return s.name }
+func (s *scriptedAuthn) Supports(security.Authentication) bool { return true }
+func (s *scriptedAuthn) Authenticate(_ context.Context, _ security.Authentication) (security.Authentication, error) {
+	s.calls.Add(1)
+
+	return s.result, s.err
+}
+
+// scriptedADM lets tests force a verdict without running real voters.
+type scriptedADM struct {
+	err error
+}
+
+func (s scriptedADM) Decide(_ context.Context, _ security.Authentication, _ []security.Attribute) error {
+	return s.err
+}
+
+// fakeAttr is the smallest Attribute implementation.
+type fakeAttr string
+
+func (a fakeAttr) String() string { return string(a) }
diff --git a/internal/integrations/go.mod b/internal/integrations/go.mod
new file mode 100644
index 0000000..28e93e2
--- /dev/null
+++ b/internal/integrations/go.mod
@@ -0,0 +1,32 @@
+module github.com/hyperscale-stack/security/internal/integrations
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/bearer v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/http v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/oauth2 v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../../
+
+replace github.com/hyperscale-stack/security/bearer => ../../bearer
+
+replace github.com/hyperscale-stack/security/http => ../../http
+
+replace github.com/hyperscale-stack/security/oauth2 => ../../oauth2
diff --git a/internal/integrations/go.sum b/internal/integrations/go.sum
new file mode 100644
index 0000000..56bdaa2
--- /dev/null
+++ b/internal/integrations/go.sum
@@ -0,0 +1,40 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/integrations/oauth2_auth_by_access_token_test.go b/internal/integrations/oauth2_auth_by_access_token_test.go
deleted file mode 100644
index 392b271..0000000
--- a/internal/integrations/oauth2_auth_by_access_token_test.go
+++ /dev/null
@@ -1,207 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package integrations
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-	"time"
-
-	"github.com/gilcrest/alice"
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/credential"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/storage"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token/random"
-	"github.com/hyperscale-stack/security/authorization"
-	"github.com/hyperscale-stack/security/user"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestOauth2AuthByAccessTokenWithNoAuthHeader(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	client := &oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	storageProvider.SaveClient(client)
-
-	storageProvider.SaveAccess(&oauth2.AccessInfo{
-		Client:      client,
-		AccessToken: "I3SoKTVXi6QzMZAmDW2Fgw2MLX0msPGRN58bCDLDFthJmy6Qoy8FH5v10dbewR6PfAV3brKhepjnTJVhDplSHFe6qbF3J4YDkI5EzXG0S8X7snSoB6FtrPNFMmISuEmU",
-		UserData:    "8c87a032-755d-42f6-be96-0421948f6e94",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewAccessTokenFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-
-	userProvider.AssertNotCalled(t, "LoadUser")
-}
-
-func TestOauth2AuthByAccessTokenWithBadToken(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	client := &oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	storageProvider.SaveClient(client)
-
-	storageProvider.SaveAccess(&oauth2.AccessInfo{
-		Client:      client,
-		AccessToken: "I3SoKTVXi6QzMZAmDW2Fgw2MLX0msPGRN58bCDLDFthJmy6Qoy8FH5v10dbewR6PfAV3brKhepjnTJVhDplSHFe6qbF3J4YDkI5EzXG0S8X7snSoB6FtrPNFMmISuEmU",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewBearerFilter(),
-			authentication.NewAccessTokenFilter(),
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	req.Header.Set("Authorization", "Bearer bad")
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestOauth2AuthByAccessToken(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userMock := &user.MockUser{}
-
-	userMock.On("GetRoles").Return([]string{"ROLE_USER"})
-	userMock.On("GetUsername").Return("euskadi31")
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	userProvider.On("LoadUser", "8c87a032-755d-42f6-be96-0421948f6e94").Return(userMock, nil)
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	client := &oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	}
-
-	storageProvider.SaveClient(client)
-
-	storageProvider.SaveAccess(&oauth2.AccessInfo{
-		Client:      client,
-		AccessToken: "I3SoKTVXi6QzMZAmDW2Fgw2MLX0msPGRN58bCDLDFthJmy6Qoy8FH5v10dbewR6PfAV3brKhepjnTJVhDplSHFe6qbF3J4YDkI5EzXG0S8X7snSoB6FtrPNFMmISuEmU",
-		ExpiresIn:   60,
-		CreatedAt:   time.Now(),
-		UserData:    "8c87a032-755d-42f6-be96-0421948f6e94",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewBearerFilter(),
-			authentication.NewAccessTokenFilter(),
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-
-		ctx := r.Context()
-
-		token := oauth2.AccessTokenFromContext(ctx)
-		assert.NotNil(t, token)
-
-		user := credential.FromContext(ctx)
-		assert.NotNil(t, user)
-
-		assert.Equal(t, "euskadi31", user.GetUser().GetUsername())
-		assert.Equal(t, []string{"ROLE_USER"}, user.GetUser().GetRoles())
-
-		err := json.NewEncoder(w).Encode(token)
-		assert.NoError(t, err)
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	req.Header.Set("Authorization", "Bearer I3SoKTVXi6QzMZAmDW2Fgw2MLX0msPGRN58bCDLDFthJmy6Qoy8FH5v10dbewR6PfAV3brKhepjnTJVhDplSHFe6qbF3J4YDkI5EzXG0S8X7snSoB6FtrPNFMmISuEmU")
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	token := struct {
-		Client struct {
-			ID     string
-			Secret string
-		}
-		AccessToken string
-	}{}
-
-	err := json.NewDecoder(resp.Body).Decode(&token)
-	assert.NoError(t, err)
-
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	assert.Equal(t, "I3SoKTVXi6QzMZAmDW2Fgw2MLX0msPGRN58bCDLDFthJmy6Qoy8FH5v10dbewR6PfAV3brKhepjnTJVhDplSHFe6qbF3J4YDkI5EzXG0S8X7snSoB6FtrPNFMmISuEmU", token.AccessToken)
-
-	assert.Equal(t, "5cc06c3b-5755-4229-958c-a515a245aaeb", token.Client.ID)
-	assert.Equal(t, "WTvuAztPD2XBauomleRzGFYuZawS07Ym", token.Client.Secret)
-
-	userProvider.AssertExpectations(t)
-	userMock.AssertExpectations(t)
-}
diff --git a/internal/integrations/oauth2_auth_by_client_test.go b/internal/integrations/oauth2_auth_by_client_test.go
deleted file mode 100644
index 06b0f16..0000000
--- a/internal/integrations/oauth2_auth_by_client_test.go
+++ /dev/null
@@ -1,194 +0,0 @@
-// Copyright 2021 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package integrations
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/gilcrest/alice"
-	"github.com/hyperscale-stack/security/authentication"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/storage"
-	"github.com/hyperscale-stack/security/authentication/provider/oauth2/token/random"
-	"github.com/hyperscale-stack/security/authorization"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestOauth2AuthByClientWithNoAuthHeader(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	storageProvider.SaveClient(&oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestOauth2AuthByClientWithBadClientID(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	storageProvider.SaveClient(&oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewBearerFilter(),
-			authentication.NewAccessTokenFilter(),
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	req.SetBasicAuth("bad", "foo")
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestOauth2AuthByClientWithBadPassword(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	storageProvider.SaveClient(&oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewBearerFilter(),
-			authentication.NewAccessTokenFilter(),
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	req.SetBasicAuth("5cc06c3b-5755-4229-958c-a515a245aaeb", "bad")
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
-}
-
-func TestOauth2AuthByClient(t *testing.T) {
-	tokenGenerator := random.NewTokenGenerator(&random.Configuration{})
-
-	userProvider := &oauth2.MockUserProvider{}
-
-	storageProvider := storage.NewInMemoryStorage()
-
-	storageProvider.SaveClient(&oauth2.DefaultClient{
-		ID:          "5cc06c3b-5755-4229-958c-a515a245aaeb",
-		Secret:      "WTvuAztPD2XBauomleRzGFYuZawS07Ym",
-		RedirectURI: "https://connect.myservice.tld",
-	})
-
-	private := alice.New(
-		authentication.FilterHandler(
-			authentication.NewBearerFilter(),
-			authentication.NewAccessTokenFilter(),
-			authentication.NewHTTPBasicFilter(),
-		),
-		authentication.Handler(
-			oauth2.NewOAuth2AuthenticationProvider(tokenGenerator, userProvider, storageProvider, storageProvider, storageProvider, storageProvider),
-		),
-		authorization.AuthorizeHandler(),
-	)
-
-	handler := private.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
-		// private route
-
-		client := oauth2.ClientFromContext(r.Context())
-		assert.NotNil(t, client)
-
-		err := json.NewEncoder(w).Encode(client)
-		assert.NoError(t, err)
-	})
-
-	req := httptest.NewRequest("GET", "http://example.com/foo", nil)
-	req.SetBasicAuth("5cc06c3b-5755-4229-958c-a515a245aaeb", "WTvuAztPD2XBauomleRzGFYuZawS07Ym")
-	w := httptest.NewRecorder()
-
-	handler.ServeHTTP(w, req)
-
-	resp := w.Result()
-
-	client := struct {
-		ID     string
-		Secret string
-	}{}
-
-	err := json.NewDecoder(resp.Body).Decode(&client)
-	assert.NoError(t, err)
-
-	assert.Equal(t, http.StatusOK, resp.StatusCode)
-
-	assert.Equal(t, "5cc06c3b-5755-4229-958c-a515a245aaeb", client.ID)
-	assert.Equal(t, "WTvuAztPD2XBauomleRzGFYuZawS07Ym", client.Secret)
-}
diff --git a/internal/integrations/oauth2_endpoints_test.go b/internal/integrations/oauth2_endpoints_test.go
new file mode 100644
index 0000000..d922f7a
--- /dev/null
+++ b/internal/integrations/oauth2_endpoints_test.go
@@ -0,0 +1,226 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package integrations_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/clientauth"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// legacyStubGrant registers a "password" grant_type without pulling in any
+// implementation — it only needs to be present for NewServer's profile
+// check to trip.
+type legacyStubGrant struct{ typ string }
+
+func (g legacyStubGrant) Type() string { return g.typ }
+func (g legacyStubGrant) Handle(context.Context, oauth2.GrantRequest) (*oauth2.GrantResponse, error) {
+	return nil, oauth2.ErrServerError
+}
+
+func TestTokenEndpointMissingGrantType(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(url.Values{}.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, oauth2.CodeInvalidRequest, body["error"])
+}
+
+func TestTokenEndpointUnsupportedGrantType(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("grant_type", "password") // not registered
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, oauth2.CodeUnsupportedGrantType, body["error"])
+}
+
+func TestTokenEndpointGetIsRejected(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/oauth2/token", nil))
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
+func TestMetadataEndpointAdvertisesConfiguration(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	rec := httptest.NewRecorder()
+	srv.MetadataHandler().ServeHTTP(rec,
+		httptest.NewRequest(http.MethodGet, "/.well-known/oauth-authorization-server", nil))
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, "https://auth.example", body["issuer"])
+
+	grants, _ := body["grant_types_supported"].([]any)
+	assert.Len(t, grants, 2, "client_credentials + refresh_token")
+
+	methods, _ := body["token_endpoint_auth_methods_supported"].([]any)
+	assert.Contains(t, methods, "client_secret_basic")
+	assert.Contains(t, methods, "client_secret_post")
+
+	pkce, _ := body["code_challenge_methods_supported"].([]any)
+	assert.Equal(t, []any{"S256"}, pkce, "BCP profile mandates S256-only PKCE")
+}
+
+func TestRevokeEndpointAlwaysReturns200(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("token", "whatever-token-even-if-unknown")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/revoke", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.RevokeHandler().ServeHTTP(rec, req)
+
+	// RFC 7009 §2.2: the response MUST NOT reveal whether the token existed.
+	assert.Equal(t, http.StatusOK, rec.Code)
+}
+
+func TestIntrospectEndpointReportsInactiveForUnknownToken(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("token", "definitely-not-a-real-token")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/introspect", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.IntrospectHandler().ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, false, body["active"])
+}
+
+// TestProfileBCPRefusesLegacyGrantsAtBoot asserts that NewServer refuses to
+// register the legacy password / implicit grants under the BCP profile.
+func TestProfileBCPRefusesLegacyGrantsAtBoot(t *testing.T) {
+	t.Parallel()
+
+	store := memory.New()
+	clients := &staticClientStore{clients: map[string]oauth2.Client{
+		clientID: &oauth2.DefaultClient{IDValue: clientID, Secret: clientSecret},
+	}}
+
+	_, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile:        oauth2.Profile20BCP,
+		Storage:        store,
+		ClientStore:    clients,
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		Grants:         []oauth2.Grant{legacyStubGrant{typ: "password"}},
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "password")
+}
+
+// clientForm builds a POST form request authenticated as the demo client.
+func clientForm(path string, form url.Values) *http.Request {
+	req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	return req
+}
+
+// TestIntrospectAndRevokeOnIssuedTokens proves the token-hashing fix: a
+// token minted by a grant is found by /introspect and /revoke — issuance
+// and the lookup endpoints hash the token the same way.
+func TestIntrospectAndRevokeOnIssuedTokens(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	// Mint an access token over client_credentials.
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, clientForm("/oauth2/token",
+		url.Values{"grant_type": {"client_credentials"}, "scope": {"api:read"}}))
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var issued map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &issued))
+	accessToken, _ := issued["access_token"].(string)
+	require.NotEmpty(t, accessToken)
+
+	introspect := func(t *testing.T) bool {
+		t.Helper()
+
+		rec := httptest.NewRecorder()
+		srv.IntrospectHandler().ServeHTTP(rec, clientForm("/oauth2/introspect",
+			url.Values{"token": {accessToken}}))
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var body map[string]any
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+		active, _ := body["active"].(bool)
+
+		return active
+	}
+
+	// The freshly issued token introspects as active.
+	assert.True(t, introspect(t), "a grant-issued token must be introspectable")
+
+	// Revoking it then makes it introspect as inactive.
+	rec = httptest.NewRecorder()
+	srv.RevokeHandler().ServeHTTP(rec, clientForm("/oauth2/revoke", url.Values{"token": {accessToken}}))
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	assert.False(t, introspect(t), "a revoked token must introspect as inactive")
+}
diff --git a/internal/integrations/oauth2_token_test.go b/internal/integrations/oauth2_token_test.go
new file mode 100644
index 0000000..c95f2bf
--- /dev/null
+++ b/internal/integrations/oauth2_token_test.go
@@ -0,0 +1,180 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package integrations holds end-to-end tests that wire the whole stack
+// (transport adapters + grants + storage) together. They are NOT part of
+// the public API; they live behind an internal/ boundary so external
+// consumers cannot import them.
+package integrations_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/clientauth"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	clientID     = "5cc06c3b-5755-4229-958c-a515a245aaeb"
+	clientSecret = "WTvuAztPD2XBauomleRzGFYuZawS07Ym"
+)
+
+// staticClientStore is a tiny [oauth2.ClientStore] used by the integration
+// tests. Mirrors the in-memory store used by the legacy MVP.
+type staticClientStore struct{ clients map[string]oauth2.Client }
+
+func (s *staticClientStore) LoadClient(_ context.Context, id string) (oauth2.Client, error) {
+	c, ok := s.clients[id]
+	if !ok {
+		return nil, nil
+	}
+
+	return c, nil
+}
+
+func newServer(t *testing.T) (*oauth2.Server, *memory.Store) {
+	t.Helper()
+
+	store := memory.New()
+	client := &oauth2.DefaultClient{
+		IDValue:           clientID,
+		Secret:            clientSecret,
+		TypeValue:         oauth2.ClientConfidential,
+		RedirectURIValues: []string{"https://connect.myservice.tld"},
+		ScopeValues:       []string{"api:read"},
+	}
+	clients := &staticClientStore{clients: map[string]oauth2.Client{clientID: client}}
+
+	cfg := grant.Config{
+		Storage:       store,
+		AccessTokens:  token.NewOpaque(32),
+		RefreshTokens: token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)},
+		AccessTTL:     time.Hour,
+		RefreshTTL:    24 * time.Hour,
+		RotateRefreshTokens: true,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile:        oauth2.Profile20BCP,
+		Storage:        store,
+		ClientStore:    clients,
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		Grants:         []oauth2.Grant{grant.NewClientCredentials(cfg), grant.NewRefreshToken(cfg)},
+		ClientAuth: []oauth2.ClientAuthenticator{
+			clientauth.NewBasic(),
+			clientauth.NewPost(),
+		},
+	})
+	require.NoError(t, err)
+
+	return srv, store
+}
+
+// TestOAuth2ClientCredentialsViaTokenEndpoint is the modern equivalent of
+// the legacy TestOauth2AuthByClient: a confidential client authenticates
+// over HTTP Basic and obtains an access token from /token.
+func TestOAuth2ClientCredentialsViaTokenEndpoint(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+	form.Set("scope", "api:read")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.NotEmpty(t, body["access_token"], "must mint an access token")
+	assert.Equal(t, "Bearer", body["token_type"])
+	assert.Equal(t, "api:read", body["scope"])
+	_, hasRefresh := body["refresh_token"]
+	assert.False(t, hasRefresh, "client_credentials MUST NOT issue refresh tokens (RFC 6749 §4.4.3)")
+}
+
+// TestOAuth2ClientCredentialsBadSecret is the modern equivalent of the
+// legacy TestOauth2AuthByClientWithBadPassword: wrong secret returns
+// 401 invalid_client with WWW-Authenticate.
+func TestOAuth2ClientCredentialsBadSecret(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, "wrong-secret")
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), "Basic")
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, oauth2.CodeInvalidClient, body["error"])
+}
+
+// TestOAuth2ClientCredentialsUnknownClient is the modern equivalent of the
+// legacy TestOauth2AuthByClientWithBadClientID.
+func TestOAuth2ClientCredentialsUnknownClient(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth("unknown-client", "whatever")
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+}
+
+// TestOAuth2ClientCredentialsNoAuthHeader is the modern equivalent of the
+// legacy TestOauth2AuthByClientWithNoAuthHeader: no client credentials
+// returns 401 invalid_client.
+func TestOAuth2ClientCredentialsNoAuthHeader(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newServer(t)
+
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+}
diff --git a/internal/integrations/resource_server_test.go b/internal/integrations/resource_server_test.go
new file mode 100644
index 0000000..5732406
--- /dev/null
+++ b/internal/integrations/resource_server_test.go
@@ -0,0 +1,119 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package integrations_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+	httpsec "github.com/hyperscale-stack/security/http"
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// localIntrospectVerifier is a [bearer.TokenVerifier] that resolves opaque
+// access tokens by hashing them and consulting the [oauth2.AccessTokenStore]
+// directly. It is the in-process equivalent of an RFC 7662 introspection
+// call — the canonical way to validate opaque tokens when the authorization
+// server and the resource server share an address space (single binary or
+// shared storage).
+type localIntrospectVerifier struct {
+	store oauth2.AccessTokenStore
+}
+
+// Verify implements [bearer.TokenVerifier]. It hashes the raw token,
+// looks it up in storage, and returns an authenticated
+// [bearer.Authentication] on success.
+func (v *localIntrospectVerifier) Verify(ctx context.Context, token string) (security.Authentication, error) {
+	hash := oauth2.HashToken(nil, token)
+
+	at, err := v.store.LookupAccessToken(ctx, hash)
+	if err != nil {
+		return nil, security.ErrTokenNotFound
+	}
+
+	if at.IsExpired(time.Now()) {
+		return nil, security.ErrTokenExpired
+	}
+
+	return bearer.New(token).WithAuthenticated(tokenPrincipal{sub: at.Subject}, nil, at.Subject), nil
+}
+
+type tokenPrincipal struct{ sub string }
+
+func (p tokenPrincipal) Subject() string { return p.sub }
+
+// TestResourceServerHappyPath issues a token via /token, then calls a
+// resource server guarded by httpsec.Middleware + bearer.Authenticator.
+// The opaque token is validated against the shared storage via the
+// in-process introspection verifier.
+func TestResourceServerHappyPath(t *testing.T) {
+	t.Parallel()
+
+	srv, store := newServer(t)
+
+	// 1. Authorization server hands us an access token via /token.
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+	form.Set("scope", "api:read")
+
+	req := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.SetBasicAuth(clientID, clientSecret)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	accessToken, _ := body["access_token"].(string)
+	require.NotEmpty(t, accessToken)
+
+	// 2. Resource server.
+	verifier := &localIntrospectVerifier{store: store}
+	engine := security.NewEngine(
+		security.NewManager(bearer.NewAuthenticator(verifier)),
+		bearer.NewExtractor(),
+	)
+
+	resource := httpsec.Middleware(engine)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth, _ := security.FromContext(r.Context())
+		_, _ = io.WriteString(w, "hello "+auth.Principal().Subject())
+	}))
+
+	// 3. Authenticated call -> 200 OK.
+	probe := httptest.NewRequest(http.MethodGet, "/api/me", nil)
+	probe.Header.Set("Authorization", "Bearer "+accessToken)
+
+	rec = httptest.NewRecorder()
+	resource.ServeHTTP(rec, probe)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "hello "+clientID, rec.Body.String())
+
+	// 4. Bad token -> 401.
+	probe = httptest.NewRequest(http.MethodGet, "/api/me", nil)
+	probe.Header.Set("Authorization", "Bearer not-a-real-token")
+
+	rec = httptest.NewRecorder()
+	resource.ServeHTTP(rec, probe)
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+
+	// 5. No token at all -> 401 (deny-by-default).
+	rec = httptest.NewRecorder()
+	resource.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/me", nil))
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+}
diff --git a/jwt/algorithm.go b/jwt/algorithm.go
new file mode 100644
index 0000000..483c1b9
--- /dev/null
+++ b/jwt/algorithm.go
@@ -0,0 +1,51 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import jose "github.com/go-jose/go-jose/v4"
+
+// Algorithm is a typed alias around the JOSE algorithm identifier so the
+// security API stays self-contained: callers do not need to import go-jose
+// for the common case (configuring an allowlist).
+type Algorithm string
+
+// Supported signature algorithms. The list is deliberately curated: every
+// algorithm here is either an RSA-PSS / ECDSA / EdDSA scheme (asymmetric)
+// or HS256 (symmetric, hidden by default).
+//
+// "none" is not exported: rejecting it unconditionally defeats the canonical
+// JWT family of "alg=none" attacks.
+const (
+	RS256 Algorithm = "RS256"
+	RS384 Algorithm = "RS384"
+	RS512 Algorithm = "RS512"
+	PS256 Algorithm = "PS256"
+	PS384 Algorithm = "PS384"
+	PS512 Algorithm = "PS512"
+	ES256 Algorithm = "ES256"
+	ES384 Algorithm = "ES384"
+	ES512 Algorithm = "ES512"
+	EdDSA Algorithm = "EdDSA"
+	// HS256 is symmetric. It is enabled only when [WithAllowedAlgorithms]
+	// includes it explicitly — the default allowlist excludes it to prevent
+	// the well-known "RSA public key used as HMAC secret" key-confusion
+	// attack.
+	HS256 Algorithm = "HS256"
+	HS384 Algorithm = "HS384"
+	HS512 Algorithm = "HS512"
+)
+
+// String makes Algorithm implement fmt.Stringer; identical to the underlying
+// alg identifier so logs match JOSE conventions.
+func (a Algorithm) String() string { return string(a) }
+
+// joseAlg converts Algorithm to the JOSE library's typed identifier.
+func (a Algorithm) joseAlg() jose.SignatureAlgorithm {
+	return jose.SignatureAlgorithm(a)
+}
+
+// defaultAllowedAlgorithms is the strict baseline applied when the user does
+// not call WithAllowedAlgorithms. It deliberately excludes HMAC algorithms.
+var defaultAllowedAlgorithms = []Algorithm{RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA}
diff --git a/jwt/bearer_adapter.go b/jwt/bearer_adapter.go
new file mode 100644
index 0000000..46f24ef
--- /dev/null
+++ b/jwt/bearer_adapter.go
@@ -0,0 +1,95 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/bearer"
+)
+
+// AuthorityResolver maps the parsed standard claims to the authorities
+// attached to the resulting [security.Authentication]. The default resolver
+// (when none is provided) splits StandardClaims.Scope on spaces and prefixes
+// each entry with "scope:" so the voter package recognizes them.
+type AuthorityResolver func(claims *StandardClaims) []string
+
+// BearerVerifier adapts a JWT [Verifier] to the [bearer.TokenVerifier]
+// contract. The returned TokenVerifier produces an authenticated
+// [bearer.Authentication] whose principal is the JWT `sub` claim and whose
+// authorities are the values returned by the resolver.
+//
+// When resolver is nil, [DefaultAuthorityResolver] is used.
+func BearerVerifier(v Verifier, resolver AuthorityResolver) bearer.TokenVerifier {
+	if resolver == nil {
+		resolver = DefaultAuthorityResolver
+	}
+
+	return bearer.VerifierFunc(func(ctx context.Context, token string) (security.Authentication, error) {
+		claims, err := v.Verify(ctx, token, nil)
+		if err != nil {
+			return nil, err //nolint:wrapcheck // verifier already wraps with sentinels
+		}
+
+		principal := claimPrincipal{sub: claims.Subject}
+		authorities := resolver(claims)
+
+		return bearer.New(token).WithAuthenticated(principal, authorities, claims.Subject), nil
+	})
+}
+
+// DefaultAuthorityResolver materializes authorities from the OAuth2 `scope`
+// claim. Each space-separated scope is prefixed with "scope:" so the voter
+// package recognizes it via [security.ScopeAttribute].
+func DefaultAuthorityResolver(claims *StandardClaims) []string {
+	if claims.Scope == "" {
+		return nil
+	}
+
+	out := make([]string, 0, 4)
+
+	for s := range splitFields(claims.Scope) {
+		out = append(out, "scope:"+s)
+	}
+
+	return out
+}
+
+// splitFields yields the space-separated fields of s without allocating an
+// intermediate slice. Mirrors strings.Fields in iterator form.
+func splitFields(s string) func(yield func(string) bool) {
+	return func(yield func(string) bool) {
+		start := -1
+
+		for i, r := range s {
+			if r == ' ' || r == '\t' {
+				if start >= 0 {
+					if !yield(s[start:i]) {
+						return
+					}
+
+					start = -1
+				}
+
+				continue
+			}
+
+			if start < 0 {
+				start = i
+			}
+		}
+
+		if start >= 0 {
+			_ = yield(s[start:])
+		}
+	}
+}
+
+// claimPrincipal is the [security.Principal] returned by BearerVerifier.
+type claimPrincipal struct{ sub string }
+
+// Subject implements [security.Principal].
+func (p claimPrincipal) Subject() string { return p.sub }
diff --git a/jwt/bearer_adapter_test.go b/jwt/bearer_adapter_test.go
new file mode 100644
index 0000000..6f9b2ef
--- /dev/null
+++ b/jwt/bearer_adapter_test.go
@@ -0,0 +1,75 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBearerVerifierDefaultResolverExposesScopesAsAuthorities(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}))
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		Scope:     "read:mail write:mail admin",
+		ExpiresAt: jwtsec.NewNumericDate(time.Now().Add(time.Hour)),
+	})
+
+	tv := jwtsec.BearerVerifier(verifier, nil)
+	got, err := tv.Verify(context.Background(), token)
+	require.NoError(t, err)
+	assert.True(t, got.IsAuthenticated())
+	assert.Equal(t, "alice", got.Principal().Subject())
+	assert.ElementsMatch(t,
+		[]string{"scope:read:mail", "scope:write:mail", "scope:admin"},
+		got.Authorities(),
+	)
+}
+
+func TestBearerVerifierCustomResolver(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}))
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		ExpiresAt: jwtsec.NewNumericDate(time.Now().Add(time.Hour)),
+	})
+
+	tv := jwtsec.BearerVerifier(verifier, func(c *jwtsec.StandardClaims) []string {
+		return []string{"ROLE_" + c.Subject}
+	})
+
+	got, err := tv.Verify(context.Background(), token)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"ROLE_alice"}, got.Authorities())
+}
+
+func TestBearerVerifierPropagatesVerifierError(t *testing.T) {
+	t.Parallel()
+
+	priv, _ := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	// Verifier with no keys -> ErrInvalidSignature.
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS(nil))
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{Subject: "alice"})
+
+	tv := jwtsec.BearerVerifier(verifier, nil)
+	_, err := tv.Verify(context.Background(), token)
+	assert.ErrorIs(t, err, jwtsec.ErrInvalidSignature)
+}
diff --git a/jwt/claims.go b/jwt/claims.go
new file mode 100644
index 0000000..d60fff6
--- /dev/null
+++ b/jwt/claims.go
@@ -0,0 +1,134 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// StandardClaims maps the RFC 7519 registered claims plus the OAuth2-friendly
+// `scope` claim (RFC 9068 §2.2.3). Custom claims belong in caller-defined
+// structs that embed StandardClaims.
+type StandardClaims struct {
+	// Issuer is the `iss` claim — who minted the token.
+	Issuer string `json:"iss,omitempty"`
+	// Subject is the `sub` claim — the principal the token represents.
+	Subject string `json:"sub,omitempty"`
+	// Audience is the `aud` claim. Per RFC 7519 §4.1.3 it is either a
+	// string or an array of strings; we always (de)serialize it as a
+	// slice for predictability.
+	Audience Audience `json:"aud,omitempty"`
+	// ExpiresAt is the `exp` claim — token expiry.
+	ExpiresAt *NumericDate `json:"exp,omitempty"`
+	// NotBefore is the `nbf` claim — earliest valid timestamp.
+	NotBefore *NumericDate `json:"nbf,omitempty"`
+	// IssuedAt is the `iat` claim — issuance timestamp.
+	IssuedAt *NumericDate `json:"iat,omitempty"`
+	// JWTID is the `jti` claim — unique token identifier.
+	JWTID string `json:"jti,omitempty"`
+	// Scope is the OAuth2 scope claim, space-separated per RFC 9068 §2.2.3.
+	Scope string `json:"scope,omitempty"`
+}
+
+// Audience is a flexible JSON representation of the `aud` claim. It marshals
+// as a string when single-valued and as an array otherwise; unmarshaling
+// accepts both shapes.
+type Audience []string
+
+// MarshalJSON implements [json.Marshaler].
+func (a Audience) MarshalJSON() ([]byte, error) {
+	switch len(a) {
+	case 0:
+		return []byte("null"), nil
+	case 1:
+		b, err := json.Marshal(a[0])
+		if err != nil {
+			return nil, fmt.Errorf("jwt: marshal audience: %w", err)
+		}
+
+		return b, nil
+	default:
+		b, err := json.Marshal([]string(a))
+		if err != nil {
+			return nil, fmt.Errorf("jwt: marshal audience: %w", err)
+		}
+
+		return b, nil
+	}
+}
+
+// UnmarshalJSON implements [json.Unmarshaler]; accepts string or []string.
+func (a *Audience) UnmarshalJSON(b []byte) error {
+	if len(b) == 0 {
+		return nil
+	}
+
+	if b[0] == '"' {
+		var s string
+		if err := json.Unmarshal(b, &s); err != nil {
+			return err //nolint:wrapcheck // pass-through json error
+		}
+
+		*a = Audience{s}
+
+		return nil
+	}
+
+	var s []string
+	if err := json.Unmarshal(b, &s); err != nil {
+		return err //nolint:wrapcheck // pass-through json error
+	}
+
+	*a = Audience(s)
+
+	return nil
+}
+
+// NumericDate wraps a UNIX timestamp encoded as a JSON number per RFC 7519
+// §2. The pointer-wrapped form on StandardClaims lets callers distinguish
+// "no claim" from "claim = 0" (epoch).
+type NumericDate time.Time
+
+// NewNumericDate constructs a NumericDate from a time.Time, truncating to
+// second precision per RFC 7519.
+func NewNumericDate(t time.Time) *NumericDate {
+	n := NumericDate(t.Truncate(time.Second))
+
+	return &n
+}
+
+// Time returns the underlying time.Time value.
+func (n *NumericDate) Time() time.Time {
+	if n == nil {
+		return time.Time{}
+	}
+
+	return time.Time(*n)
+}
+
+// MarshalJSON implements [json.Marshaler]; emits a UNIX integer.
+func (n NumericDate) MarshalJSON() ([]byte, error) {
+	b, err := json.Marshal(time.Time(n).Unix())
+	if err != nil {
+		return nil, fmt.Errorf("jwt: marshal numeric date: %w", err)
+	}
+
+	return b, nil
+}
+
+// UnmarshalJSON implements [json.Unmarshaler]; accepts integer or float.
+func (n *NumericDate) UnmarshalJSON(b []byte) error {
+	var f float64
+	if err := json.Unmarshal(b, &f); err != nil {
+		return err //nolint:wrapcheck // pass-through json error
+	}
+
+	sec, nsec := int64(f), int64((f-float64(int64(f)))*1e9)
+	*n = NumericDate(time.Unix(sec, nsec).UTC())
+
+	return nil
+}
diff --git a/jwt/doc.go b/jwt/doc.go
new file mode 100644
index 0000000..c491fe2
--- /dev/null
+++ b/jwt/doc.go
@@ -0,0 +1,23 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package jwtsec provides JWT signing and verification with JWKS support and
+// key rotation, usable standalone (as a Bearer TokenVerifier) or as the
+// signer behind the OAuth2 server's JWT access-token format.
+//
+// Security defaults:
+//   - "alg=none" is rejected unconditionally.
+//   - The allowed-algorithm list defaults to the asymmetric schemes
+//     (RSA, RSA-PSS, ECDSA, EdDSA); HMAC algorithms are accepted only on
+//     explicit opt-in via WithAllowedAlgorithms, to avoid key confusion.
+//   - Issuer and audience checks are opt-in via WithIssuer / WithAudience.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - github.com/hyperscale-stack/security/bearer (TokenVerifier adapter)
+//   - github.com/hyperscale-stack/security/oauth2 (access-token signer adapter)
+//   - github.com/go-jose/go-jose/v4 (JOSE primitives)
+//   - go.opentelemetry.io/otel
+//   - stdlib only
+package jwtsec
diff --git a/jwt/errors.go b/jwt/errors.go
new file mode 100644
index 0000000..c4892be
--- /dev/null
+++ b/jwt/errors.go
@@ -0,0 +1,84 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Sentinel errors. Every JWT validation failure wraps one of these so the
+// HTTP / gRPC error mappers can produce the right RFC 6750 / RFC 7519
+// status code without parsing message strings.
+var (
+	// ErrInvalidSignature signals that the JWS signature did not match the
+	// payload (corrupted token, wrong key). Wraps [security.ErrInvalidCredentials].
+	ErrInvalidSignature = newJWTError("invalid signature", security.ErrInvalidCredentials)
+
+	// ErrInvalidIssuer signals that the `iss` claim does not match the
+	// configured allowlist.
+	ErrInvalidIssuer = newJWTError("invalid issuer", security.ErrInvalidCredentials)
+
+	// ErrInvalidAudience signals that none of the `aud` values match the
+	// configured allowlist.
+	ErrInvalidAudience = newJWTError("invalid audience", security.ErrInvalidCredentials)
+
+	// ErrTokenExpired signals that the `exp` claim is in the past
+	// (allowing for the configured clock skew). Wraps
+	// [security.ErrTokenExpired].
+	ErrTokenExpired = newJWTError("token expired", security.ErrTokenExpired)
+
+	// ErrMissingExpiry signals that the token carries no `exp` claim while
+	// the verifier requires one — the default; see [WithOptionalExpiry].
+	// Wraps [security.ErrTokenExpired] so transport mappers classify a
+	// non-expiring token like any other temporally-invalid token.
+	ErrMissingExpiry = newJWTError("missing exp claim", security.ErrTokenExpired)
+
+	// ErrTokenNotYetValid signals that the `nbf` claim is in the future
+	// (allowing for the configured clock skew).
+	ErrTokenNotYetValid = newJWTError("token not yet valid", security.ErrInvalidCredentials)
+
+	// ErrAlgorithmNotAllowed signals that the token's `alg` header is not in
+	// the configured allowlist. The canonical defense against the "alg=none"
+	// and "RSA public key as HMAC secret" key-confusion attacks.
+	ErrAlgorithmNotAllowed = newJWTError("algorithm not allowed", security.ErrInvalidCredentials)
+
+	// ErrMalformedToken signals that the input string is not a parseable
+	// JWS structure (wrong dot count, bad base64, ...).
+	ErrMalformedToken = newJWTError("malformed token", security.ErrInvalidCredentials)
+)
+
+// newJWTError builds a sentinel that wraps a core security sentinel via
+// fmt.Errorf %w so errors.Is bridges both layers transparently.
+func newJWTError(msg string, parent error) error {
+	return fmt.Errorf("jwt: %s: %w", msg, parent)
+}
+
+// errAlgorithmDisallowed augments [ErrAlgorithmNotAllowed] with the offending
+// algorithm so server-side telemetry can pinpoint suspicious clients without
+// surfacing the value to the response.
+type errAlgorithmDisallowed struct {
+	alg string
+}
+
+func (e *errAlgorithmDisallowed) Error() string {
+	return fmt.Sprintf("jwt: algorithm %q not allowed", e.alg)
+}
+
+// Unwrap exposes the sentinel chain for errors.Is.
+func (e *errAlgorithmDisallowed) Unwrap() error { return ErrAlgorithmNotAllowed }
+
+// AsAlgorithmName extracts the disallowed algorithm name from err, returning
+// (name, true) when err is a [errAlgorithmDisallowed] instance.
+func AsAlgorithmName(err error) (string, bool) {
+	var e *errAlgorithmDisallowed
+	if errors.As(err, &e) {
+		return e.alg, true
+	}
+
+	return "", false
+}
diff --git a/jwt/errors_internal_test.go b/jwt/errors_internal_test.go
new file mode 100644
index 0000000..5700171
--- /dev/null
+++ b/jwt/errors_internal_test.go
@@ -0,0 +1,43 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestErrAlgorithmDisallowed(t *testing.T) {
+	t.Parallel()
+
+	err := &errAlgorithmDisallowed{alg: "HS256"}
+
+	assert.Equal(t, `jwt: algorithm "HS256" not allowed`, err.Error())
+	// The sentinel chain bridges to ErrAlgorithmNotAllowed.
+	assert.ErrorIs(t, err, ErrAlgorithmNotAllowed)
+}
+
+func TestAsAlgorithmName(t *testing.T) {
+	t.Parallel()
+
+	// A direct errAlgorithmDisallowed yields its algorithm name.
+	name, ok := AsAlgorithmName(&errAlgorithmDisallowed{alg: "ES512"})
+	assert.True(t, ok)
+	assert.Equal(t, "ES512", name)
+
+	// A wrapped one is still found via errors.As.
+	wrapped := fmt.Errorf("verify failed: %w", &errAlgorithmDisallowed{alg: "none"})
+	name, ok = AsAlgorithmName(wrapped)
+	assert.True(t, ok)
+	assert.Equal(t, "none", name)
+
+	// An unrelated error yields ("", false).
+	name, ok = AsAlgorithmName(errors.New("something else"))
+	assert.False(t, ok)
+	assert.Empty(t, name)
+}
diff --git a/jwt/example_test.go b/jwt/example_test.go
new file mode 100644
index 0000000..f69bf36
--- /dev/null
+++ b/jwt/example_test.go
@@ -0,0 +1,61 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"fmt"
+	"time"
+
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+)
+
+// Example shows the canonical sign-then-verify flow used by an
+// authorization server emitting RFC 9068-style JWT access tokens.
+func Example() {
+	// Operator: generate an ES256 key pair once at provisioning time.
+	priv, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	signing := jwtsec.PrivateKey{KeyID: "k-1", Algorithm: jwtsec.ES256, Key: priv}
+	verify := jwtsec.PublicKey{KeyID: "k-1", Algorithm: jwtsec.ES256, Key: &priv.PublicKey}
+
+	// Authorization server side.
+	signer := jwtsec.NewSigner(signing)
+
+	now := time.Now()
+	token, err := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Issuer:    "https://auth.example",
+		Subject:   "alice",
+		Audience:  jwtsec.Audience{"api"},
+		Scope:     "read:mail",
+		IssuedAt:  jwtsec.NewNumericDate(now),
+		ExpiresAt: jwtsec.NewNumericDate(now.Add(time.Hour)),
+	})
+	if err != nil {
+		fmt.Println("sign:", err)
+
+		return
+	}
+
+	// Resource server side (e.g. behind an httpsec.Middleware).
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{verify}),
+		jwtsec.WithIssuer("https://auth.example"),
+		jwtsec.WithAudience("api"),
+	)
+
+	claims, err := verifier.Verify(context.Background(), token, nil)
+	if err != nil {
+		fmt.Println("verify:", err)
+
+		return
+	}
+
+	fmt.Println("sub:", claims.Subject, "scope:", claims.Scope)
+	// Output:
+	// sub: alice scope: read:mail
+}
diff --git a/jwt/go.mod b/jwt/go.mod
new file mode 100644
index 0000000..a7899ff
--- /dev/null
+++ b/jwt/go.mod
@@ -0,0 +1,30 @@
+module github.com/hyperscale-stack/security/jwt
+
+go 1.26
+
+replace github.com/hyperscale-stack/security => ../
+
+replace github.com/hyperscale-stack/security/bearer => ../bearer
+
+replace github.com/hyperscale-stack/security/oauth2 => ../oauth2
+
+require (
+	github.com/go-jose/go-jose/v4 v4.1.4
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/bearer v0.0.0-00010101000000-000000000000
+	github.com/hyperscale-stack/security/oauth2 v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	go.opentelemetry.io/otel v1.43.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
diff --git a/jwt/go.sum b/jwt/go.sum
new file mode 100644
index 0000000..a2af3b7
--- /dev/null
+++ b/jwt/go.sum
@@ -0,0 +1,42 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/jwt/jwks.go b/jwt/jwks.go
new file mode 100644
index 0000000..ba2c7d6
--- /dev/null
+++ b/jwt/jwks.go
@@ -0,0 +1,142 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"sync"
+	"time"
+
+	jose "github.com/go-jose/go-jose/v4"
+)
+
+// remoteJWKS fetches a JSON Web Key Set from an HTTP endpoint with TTL-based
+// caching and best-effort refresh on unknown kid. Concurrent fetches for the
+// same endpoint are deduplicated via a sync.Mutex.
+type remoteJWKS struct {
+	url     string
+	client  *http.Client
+	ttl     time.Duration
+	mu      sync.Mutex
+	cache   *staticKeySet
+	expires time.Time
+}
+
+// RemoteOption configures a remote JWKS provider.
+type RemoteOption func(*remoteJWKS)
+
+// WithHTTPClient overrides the http.Client used to fetch the JWKS document.
+// Default: http.DefaultClient with a 10s timeout.
+func WithHTTPClient(c *http.Client) RemoteOption {
+	return func(r *remoteJWKS) { r.client = c }
+}
+
+// WithCacheTTL overrides the time after which a cached key set is refreshed
+// proactively. Default: 5 minutes.
+func WithCacheTTL(d time.Duration) RemoteOption {
+	return func(r *remoteJWKS) { r.ttl = d }
+}
+
+// NewRemoteJWKS returns a [JWKSProvider] that fetches the JSON Web Key Set
+// hosted at url, caches it for the configured TTL, and refreshes on demand
+// whenever a verifier asks for a kid that is not in the current snapshot.
+//
+// The provider is safe for concurrent use; concurrent KeySet calls that
+// trigger a refresh are serialized via an internal mutex.
+func NewRemoteJWKS(url string, opts ...RemoteOption) JWKSProvider {
+	r := &remoteJWKS{
+		url:    url,
+		client: &http.Client{Timeout: 10 * time.Second},
+		ttl:    5 * time.Minute,
+	}
+
+	for _, o := range opts {
+		o(r)
+	}
+
+	return r
+}
+
+// KeySet implements [JWKSProvider].
+func (r *remoteJWKS) KeySet(ctx context.Context) (KeySet, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if r.cache != nil && time.Now().Before(r.expires) {
+		return r.cache, nil
+	}
+
+	keys, err := r.fetch(ctx)
+	if err != nil {
+		if r.cache != nil {
+			// Return the stale snapshot rather than failing closed when
+			// the upstream is briefly unavailable — verifiers will still
+			// reject tokens whose kid is missing.
+			return r.cache, nil
+		}
+
+		return nil, fmt.Errorf("jwt: fetch jwks: %w", err)
+	}
+
+	r.cache = keys
+	r.expires = time.Now().Add(r.ttl)
+
+	return keys, nil
+}
+
+func (r *remoteJWKS) fetch(ctx context.Context) (*staticKeySet, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, r.url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+
+	// The URL was set at construction time by the operator, not by user
+	// input; G704's SSRF heuristic cannot prove that and flags this call.
+	resp, err := r.client.Do(req) //nolint:gosec // URL is operator-controlled
+	if err != nil {
+		return nil, fmt.Errorf("do request: %w", err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+
+	var raw jose.JSONWebKeySet
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("parse jwks: %w", err)
+	}
+
+	out := &staticKeySet{publics: make([]PublicKey, 0, len(raw.Keys))}
+
+	for _, k := range raw.Keys {
+		if k.Use != "" && k.Use != keyUseSignature {
+			continue
+		}
+
+		out.publics = append(out.publics, PublicKey{
+			KeyID:     k.KeyID,
+			Algorithm: Algorithm(k.Algorithm),
+			Key:       k.Key,
+		})
+	}
+
+	if len(out.publics) == 0 {
+		return nil, errors.New("no signing keys")
+	}
+
+	return out, nil
+}
diff --git a/jwt/jwks_more_test.go b/jwt/jwks_more_test.go
new file mode 100644
index 0000000..113c567
--- /dev/null
+++ b/jwt/jwks_more_test.go
@@ -0,0 +1,279 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	jose "github.com/go-jose/go-jose/v4"
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// jwksJSON marshals the public keys into an RFC 7517 JWKS document.
+func jwksJSON(t *testing.T, keys ...jose.JSONWebKey) []byte {
+	t.Helper()
+
+	b, err := json.Marshal(jose.JSONWebKeySet{Keys: keys})
+	require.NoError(t, err)
+
+	return b
+}
+
+func sigKey(pub jwtsec.PublicKey) jose.JSONWebKey {
+	return jose.JSONWebKey{Key: pub.Key, KeyID: pub.KeyID, Algorithm: string(pub.Algorithm), Use: "sig"}
+}
+
+func TestRemoteJWKSFetchAndCache(t *testing.T) {
+	t.Parallel()
+
+	_, pub := genRSA(t)
+	doc := jwksJSON(t, sigKey(pub))
+
+	var hits atomic.Int32
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		hits.Add(1)
+		_, _ = w.Write(doc)
+	}))
+	t.Cleanup(srv.Close)
+
+	provider := jwtsec.NewRemoteJWKS(srv.URL, jwtsec.WithCacheTTL(time.Hour))
+
+	// First call fetches.
+	set, err := provider.KeySet(context.Background())
+	require.NoError(t, err)
+
+	got, ok := set.ByKeyID(pub.KeyID)
+	require.True(t, ok)
+	assert.Equal(t, pub.KeyID, got.KeyID)
+
+	// Second call within the TTL is served from cache — no extra HTTP hit.
+	_, err = provider.KeySet(context.Background())
+	require.NoError(t, err)
+	assert.Equal(t, int32(1), hits.Load(), "second KeySet must hit the cache")
+}
+
+func TestRemoteJWKSWithHTTPClient(t *testing.T) {
+	t.Parallel()
+
+	_, pub := genEd25519(t)
+	doc := jwksJSON(t, sigKey(pub))
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write(doc)
+	}))
+	t.Cleanup(srv.Close)
+
+	provider := jwtsec.NewRemoteJWKS(srv.URL,
+		jwtsec.WithHTTPClient(&http.Client{Timeout: 5 * time.Second}))
+
+	set, err := provider.KeySet(context.Background())
+	require.NoError(t, err)
+
+	_, ok := set.ByKeyID(pub.KeyID)
+	assert.True(t, ok)
+}
+
+func TestRemoteJWKSFiltersNonSigningKeys(t *testing.T) {
+	t.Parallel()
+
+	_, sig := genRSA(t)
+	_, enc := genECDSA(t)
+
+	encKey := sigKey(enc)
+	encKey.Use = "enc" // not a signing key — must be skipped
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write(jwksJSON(t, sigKey(sig), encKey))
+	}))
+	t.Cleanup(srv.Close)
+
+	set, err := jwtsec.NewRemoteJWKS(srv.URL).KeySet(context.Background())
+	require.NoError(t, err)
+
+	_, ok := set.ByKeyID(sig.KeyID)
+	assert.True(t, ok, "sig key kept")
+
+	_, ok = set.ByKeyID(enc.KeyID)
+	assert.False(t, ok, "enc key filtered out")
+}
+
+func TestRemoteJWKSErrors(t *testing.T) {
+	t.Parallel()
+
+	t.Run("http error with no cache fails", func(t *testing.T) {
+		t.Parallel()
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusInternalServerError)
+		}))
+		t.Cleanup(srv.Close)
+
+		_, err := jwtsec.NewRemoteJWKS(srv.URL).KeySet(context.Background())
+		require.Error(t, err)
+	})
+
+	t.Run("malformed JSON fails", func(t *testing.T) {
+		t.Parallel()
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte("not json"))
+		}))
+		t.Cleanup(srv.Close)
+
+		_, err := jwtsec.NewRemoteJWKS(srv.URL).KeySet(context.Background())
+		require.Error(t, err)
+	})
+
+	t.Run("empty key set fails", func(t *testing.T) {
+		t.Parallel()
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte(`{"keys":[]}`))
+		}))
+		t.Cleanup(srv.Close)
+
+		_, err := jwtsec.NewRemoteJWKS(srv.URL).KeySet(context.Background())
+		require.Error(t, err)
+	})
+}
+
+func TestRemoteJWKSStaleCacheFallback(t *testing.T) {
+	t.Parallel()
+
+	_, pub := genRSA(t)
+	doc := jwksJSON(t, sigKey(pub))
+
+	var fail atomic.Bool
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if fail.Load() {
+			w.WriteHeader(http.StatusBadGateway)
+
+			return
+		}
+
+		_, _ = w.Write(doc)
+	}))
+	t.Cleanup(srv.Close)
+
+	// TTL 0 forces a refetch on every call.
+	provider := jwtsec.NewRemoteJWKS(srv.URL, jwtsec.WithCacheTTL(0))
+
+	// Prime the cache.
+	_, err := provider.KeySet(context.Background())
+	require.NoError(t, err)
+
+	// Upstream now fails — the stale snapshot must still be returned.
+	fail.Store(true)
+
+	set, err := provider.KeySet(context.Background())
+	require.NoError(t, err, "stale cache must be served when upstream is down")
+
+	_, ok := set.ByKeyID(pub.KeyID)
+	assert.True(t, ok)
+}
+
+func TestSignerAccessors(t *testing.T) {
+	t.Parallel()
+
+	priv, _ := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+
+	assert.Equal(t, jwtsec.ES256, signer.Algorithm())
+	assert.Equal(t, "ec-1", signer.KeyID())
+}
+
+func TestAlgorithmString(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "RS256", jwtsec.RS256.String())
+	assert.Equal(t, "EdDSA", jwtsec.EdDSA.String())
+}
+
+func TestStaticJWKSActive(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genRSA(t)
+
+	withSigner, err := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}, priv).KeySet(context.Background())
+	require.NoError(t, err)
+
+	active, ok := withSigner.Active()
+	require.True(t, ok)
+	assert.Equal(t, priv.KeyID, active.KeyID)
+
+	// A verifier-only key set has no active signing key.
+	verifierOnly, err := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}).KeySet(context.Background())
+	require.NoError(t, err)
+
+	_, ok = verifierOnly.Active()
+	assert.False(t, ok)
+}
+
+func TestWithAllowedAlgorithmsPanicsOnEmpty(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() { jwtsec.WithAllowedAlgorithms() })
+}
+
+func TestAudienceJSON(t *testing.T) {
+	t.Parallel()
+
+	marshal := func(a jwtsec.Audience) string {
+		b, err := a.MarshalJSON()
+		require.NoError(t, err)
+
+		return string(b)
+	}
+
+	assert.Equal(t, "null", marshal(jwtsec.Audience{}))
+	assert.Equal(t, `"solo"`, marshal(jwtsec.Audience{"solo"}))
+	assert.Equal(t, `["a","b"]`, marshal(jwtsec.Audience{"a", "b"}))
+
+	var single jwtsec.Audience
+	require.NoError(t, single.UnmarshalJSON([]byte(`"one"`)))
+	assert.Equal(t, jwtsec.Audience{"one"}, single)
+
+	var multi jwtsec.Audience
+	require.NoError(t, multi.UnmarshalJSON([]byte(`["x","y"]`)))
+	assert.Equal(t, jwtsec.Audience{"x", "y"}, multi)
+
+	var empty jwtsec.Audience
+	require.NoError(t, empty.UnmarshalJSON(nil))
+	assert.Nil(t, empty)
+
+	var bad jwtsec.Audience
+	assert.Error(t, bad.UnmarshalJSON([]byte(`{bad`)))
+}
+
+func TestNumericDate(t *testing.T) {
+	t.Parallel()
+
+	// A nil NumericDate yields the zero time.
+	var nilDate *jwtsec.NumericDate
+	assert.True(t, nilDate.Time().IsZero())
+
+	ts := time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC)
+	assert.Equal(t, ts, jwtsec.NewNumericDate(ts).Time())
+
+	// JSON round trip through an integer UNIX timestamp.
+	b, err := jwtsec.NewNumericDate(ts).MarshalJSON()
+	require.NoError(t, err)
+
+	var decoded jwtsec.NumericDate
+	require.NoError(t, decoded.UnmarshalJSON(b))
+	assert.Equal(t, ts.Unix(), decoded.Time().Unix())
+
+	assert.Error(t, decoded.UnmarshalJSON([]byte(`"not-a-number"`)))
+}
diff --git a/jwt/keyset.go b/jwt/keyset.go
new file mode 100644
index 0000000..a76c6b6
--- /dev/null
+++ b/jwt/keyset.go
@@ -0,0 +1,138 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+	"crypto"
+	"sync"
+
+	jose "github.com/go-jose/go-jose/v4"
+)
+
+// PublicKey is a verification key paired with its kid. The package wraps
+// crypto.PublicKey instead of jose.JSONWebKey to keep the API minimal; the
+// JSONWebKey form is reconstructed internally when calling go-jose.
+type PublicKey struct {
+	// KeyID is the JWS "kid" header value identifying this key. Required
+	// when the verifier serves more than one key.
+	KeyID string
+	// Algorithm is the JOSE alg this key was issued for. Required for
+	// signers; verifiers fall back to the token header when it is empty.
+	Algorithm Algorithm
+	// Key is the underlying crypto.PublicKey (rsa.PublicKey, ecdsa.PublicKey,
+	// ed25519.PublicKey, or []byte for HMAC).
+	Key crypto.PublicKey
+}
+
+// PrivateKey is the signing-key counterpart to [PublicKey].
+type PrivateKey struct {
+	// KeyID identifies this key in the published JWKS.
+	KeyID string
+	// Algorithm is the JOSE alg this key signs with.
+	Algorithm Algorithm
+	// Key is the underlying crypto.PrivateKey.
+	Key crypto.PrivateKey
+}
+
+// KeySet abstracts a snapshot of verification keys with optional active
+// signing key. Implementations are returned by [JWKSProvider.KeySet] and
+// MUST be safe for concurrent use.
+type KeySet interface {
+	// ByKeyID returns the verification key identified by kid, or (zero,
+	// false) when the kid is not present. An empty kid argument MAY match
+	// the single key in a single-key set; verifiers SHOULD always set kid
+	// to remove ambiguity once they rotate.
+	ByKeyID(kid string) (PublicKey, bool)
+
+	// Active returns the key currently preferred for SIGNING. Verifiers do
+	// not need it; signers do. (PrivateKey{}, false) when no active key is
+	// available.
+	Active() (PrivateKey, bool)
+}
+
+// JWKSProvider returns a [KeySet] snapshot. Implementations span:
+//
+//   - in-process key holders ([NewStaticJWKS]);
+//   - HTTP fetchers backed by the canonical RFC 7517 "jwks_uri" endpoint
+//     ([NewRemoteJWKS], in jwks.go).
+//
+// The KeySet contract gives implementations leeway to refresh in the
+// background without coordinating with callers.
+type JWKSProvider interface {
+	KeySet(ctx context.Context) (KeySet, error)
+}
+
+// NewStaticJWKS returns a [JWKSProvider] backed by a fixed list of public
+// keys (verifier-side) and an optional list of private keys (signer-side,
+// first one wins for Active()). Calls to KeySet are safe for concurrent
+// use and never return an error.
+func NewStaticJWKS(publicKeys []PublicKey, privateKeys ...PrivateKey) JWKSProvider {
+	keys := &staticKeySet{
+		publics: append([]PublicKey(nil), publicKeys...),
+	}
+
+	if len(privateKeys) > 0 {
+		k := privateKeys[0]
+		keys.active = &k
+	}
+
+	return staticProvider{set: keys}
+}
+
+type staticProvider struct{ set *staticKeySet }
+
+func (p staticProvider) KeySet(context.Context) (KeySet, error) { return p.set, nil }
+
+type staticKeySet struct {
+	mu      sync.RWMutex
+	publics []PublicKey
+	active  *PrivateKey
+}
+
+// ByKeyID implements [KeySet].
+func (s *staticKeySet) ByKeyID(kid string) (PublicKey, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if kid == "" && len(s.publics) == 1 {
+		return s.publics[0], true
+	}
+
+	for _, k := range s.publics {
+		if k.KeyID == kid {
+			return k, true
+		}
+	}
+
+	return PublicKey{}, false
+}
+
+// Active implements [KeySet].
+func (s *staticKeySet) Active() (PrivateKey, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if s.active == nil {
+		return PrivateKey{}, false
+	}
+
+	return *s.active, true
+}
+
+// keyUseSignature is the RFC 7517 §4.2 "use" parameter value for keys
+// intended for digital signatures.
+const keyUseSignature = "sig"
+
+// toJOSE returns the go-jose JSONWebKey form of the public key. Internal
+// helper used by the verifier.
+func (k PublicKey) toJOSE() jose.JSONWebKey {
+	return jose.JSONWebKey{Key: k.Key, KeyID: k.KeyID, Algorithm: string(k.Algorithm), Use: keyUseSignature}
+}
+
+// toJOSE returns the go-jose JSONWebKey form of the private key.
+func (k PrivateKey) toJOSE() jose.JSONWebKey {
+	return jose.JSONWebKey{Key: k.Key, KeyID: k.KeyID, Algorithm: string(k.Algorithm), Use: keyUseSignature}
+}
diff --git a/jwt/oauth2_adapter.go b/jwt/oauth2_adapter.go
new file mode 100644
index 0000000..98e1c7a
--- /dev/null
+++ b/jwt/oauth2_adapter.go
@@ -0,0 +1,69 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// OAuth2AccessTokenSigner adapts a JWT [Signer] to the
+// [oauth2/token.AccessTokenSigner] contract, producing RFC 9068
+// ("JWT Profile for OAuth 2.0 Access Tokens") tokens.
+//
+// The adapter projects [token.AccessTokenClaims] onto a [StandardClaims]
+// value: Issuer / Subject / Audience / Scope / IssuedAt / ExpiresAt map
+// one-to-one; the OAuth2 ClientID is carried in the "client_id" claim
+// (RFC 9068 §2.2.1) via a small payload type that embeds StandardClaims.
+type OAuth2AccessTokenSigner struct {
+	signer Signer
+}
+
+// NewOAuth2AccessTokenSigner wraps signer for OAuth2 use. The signer's
+// algorithm and kid are reused as-is; callers needing per-token control
+// can construct multiple signers and dispatch at the call site.
+func NewOAuth2AccessTokenSigner(signer Signer) *OAuth2AccessTokenSigner {
+	if signer == nil {
+		panic("jwtsec.NewOAuth2AccessTokenSigner: nil Signer")
+	}
+
+	return &OAuth2AccessTokenSigner{signer: signer}
+}
+
+// SignAccessToken implements [oauth2/token.AccessTokenSigner].
+func (s *OAuth2AccessTokenSigner) SignAccessToken(ctx context.Context, claims token.AccessTokenClaims) (string, error) {
+	payload := oauth2AccessClaims{
+		StandardClaims: StandardClaims{
+			Issuer:    claims.Issuer,
+			Subject:   claims.Subject,
+			Audience:  Audience{claims.Audience},
+			Scope:     claims.Scope,
+			IssuedAt:  NewNumericDate(claims.IssuedAt),
+			ExpiresAt: NewNumericDate(claims.ExpiresAt),
+		},
+		ClientID: claims.ClientID,
+	}
+
+	out, err := s.signer.Sign(ctx, payload)
+	if err != nil {
+		return "", fmt.Errorf("jwtsec: sign access token: %w", err)
+	}
+
+	return out, nil
+}
+
+// oauth2AccessClaims is the on-wire payload of an RFC 9068 access token.
+// "client_id" is the only extension over the standard claim set.
+type oauth2AccessClaims struct {
+	StandardClaims
+
+	ClientID string `json:"client_id,omitempty"`
+}
+
+// Compile-time interface check (defensive; the import path makes the
+// dependency explicit).
+var _ token.AccessTokenSigner = (*OAuth2AccessTokenSigner)(nil)
diff --git a/jwt/oauth2_adapter_test.go b/jwt/oauth2_adapter_test.go
new file mode 100644
index 0000000..cebf018
--- /dev/null
+++ b/jwt/oauth2_adapter_test.go
@@ -0,0 +1,64 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestOAuth2AccessTokenSignerProducesRFC9068Token(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	adapter := jwtsec.NewOAuth2AccessTokenSigner(signer)
+
+	issued := time.Now().Truncate(time.Second)
+	expires := issued.Add(time.Hour)
+
+	jws, err := adapter.SignAccessToken(context.Background(), token.AccessTokenClaims{
+		Issuer:    "https://auth.example",
+		Subject:   "alice",
+		Audience:  "api",
+		ClientID:  "my-client",
+		Scope:     "read:mail",
+		IssuedAt:  issued,
+		ExpiresAt: expires,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, 2, strings.Count(jws, "."), "compact JWS has 3 segments")
+
+	// Verify the token round-trips through the verifier.
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithIssuer("https://auth.example"),
+		jwtsec.WithAudience("api"),
+	)
+
+	var got struct {
+		jwtsec.StandardClaims
+		ClientID string `json:"client_id"`
+	}
+
+	_, err = verifier.Verify(context.Background(), jws, &got)
+	require.NoError(t, err)
+	assert.Equal(t, "alice", got.Subject)
+	assert.Equal(t, "my-client", got.ClientID)
+	assert.Equal(t, "read:mail", got.Scope)
+}
+
+func TestNewOAuth2AccessTokenSignerPanicsOnNilSigner(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() { jwtsec.NewOAuth2AccessTokenSigner(nil) })
+}
diff --git a/jwt/options.go b/jwt/options.go
new file mode 100644
index 0000000..d8a479e
--- /dev/null
+++ b/jwt/options.go
@@ -0,0 +1,99 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"slices"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Option configures a [Signer] or a [Verifier].
+type Option func(*config)
+
+type config struct {
+	allowed       []Algorithm
+	issuer        string
+	audiences     []string
+	skew          time.Duration
+	clock         security.Clock
+	requireExpiry bool
+}
+
+// defaults seeds the verifier configuration with the strict baseline:
+// asymmetric algorithms only, no issuer / audience restriction (the user
+// MUST opt-in), zero clock skew, and a mandatory `exp` claim.
+func defaults() *config {
+	return &config{
+		allowed:       slices.Clone(defaultAllowedAlgorithms),
+		clock:         security.DefaultClock,
+		requireExpiry: true,
+	}
+}
+
+// WithAllowedAlgorithms overrides the algorithm allowlist. Passing zero
+// algorithms is invalid and panics at construction time: a verifier that
+// accepts every algorithm is the gateway to the "alg=none" family of
+// attacks.
+func WithAllowedAlgorithms(algs ...Algorithm) Option {
+	if len(algs) == 0 {
+		panic("jwtsec.WithAllowedAlgorithms: empty list")
+	}
+
+	return func(c *config) { c.allowed = slices.Clone(algs) }
+}
+
+// WithIssuer pins the expected `iss` claim. Empty issuer disables the check
+// (the default), which is acceptable only when the verifier sits behind a
+// trust boundary that already authenticates the issuer.
+func WithIssuer(iss string) Option {
+	return func(c *config) { c.issuer = iss }
+}
+
+// WithAudience pins the expected `aud` claim values. At verification time
+// the token is accepted when AT LEAST ONE of its audiences is in the list.
+// Passing zero audiences disables the check.
+func WithAudience(aud ...string) Option {
+	return func(c *config) { c.audiences = slices.Clone(aud) }
+}
+
+// WithClockSkew tolerates the given amount of clock drift on `exp` and
+// `nbf` comparisons. Recommended values: 30s–2min for inter-service hops.
+func WithClockSkew(d time.Duration) Option {
+	return func(c *config) {
+		if d < 0 {
+			d = 0
+		}
+
+		c.skew = d
+	}
+}
+
+// WithClock injects a clock for deterministic tests. Defaults to
+// [security.DefaultClock] (wall clock).
+func WithClock(c security.Clock) Option {
+	return func(cfg *config) {
+		if c != nil {
+			cfg.clock = c
+		}
+	}
+}
+
+// WithOptionalExpiry allows tokens without an `exp` claim. By default the
+// verifier rejects them with [ErrMissingExpiry] (fail-closed): a token that
+// never expires cannot be invalidated by time and, if leaked, stays valid
+// forever. RFC 9068 §2.2 also makes `exp` REQUIRED for JWT access tokens.
+//
+// Enable this only for general-purpose JWT verification where non-expiring
+// assertions are an expected, deliberate part of the design.
+func WithOptionalExpiry() Option {
+	return func(c *config) { c.requireExpiry = false }
+}
+
+// algorithmAllowed reports whether alg appears in the allowlist.
+func (c *config) algorithmAllowed(alg Algorithm) bool {
+	return slices.Contains(c.allowed, alg)
+}
diff --git a/jwt/otel.go b/jwt/otel.go
new file mode 100644
index 0000000..ca87f40
--- /dev/null
+++ b/jwt/otel.go
@@ -0,0 +1,10 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+// tracerName is the OTel instrumentation scope used by this module's
+// span emissions. Per the project's OTel-direct policy, every signer /
+// verifier call opens a span here.
+const tracerName = "github.com/hyperscale-stack/security/jwt"
diff --git a/jwt/sign_verify_test.go b/jwt/sign_verify_test.go
new file mode 100644
index 0000000..9769826
--- /dev/null
+++ b/jwt/sign_verify_test.go
@@ -0,0 +1,308 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSignVerifyRoundTripPerAlgorithm(t *testing.T) {
+	t.Parallel()
+
+	clk := newFixedClock(time.Date(2026, 5, 19, 12, 0, 0, 0, time.UTC))
+
+	cases := []struct {
+		name string
+		gen  func(*testing.T) (jwtsec.PrivateKey, jwtsec.PublicKey)
+	}{
+		{"RS256", genRSA},
+		{"ES256", genECDSA},
+		{"EdDSA", genEd25519},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			priv, pub := c.gen(t)
+
+			signer := jwtsec.NewSigner(priv)
+			provider := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub})
+			verifier := jwtsec.NewVerifier(provider,
+				jwtsec.WithIssuer("https://issuer.example"),
+				jwtsec.WithAudience("api"),
+				jwtsec.WithClock(clk),
+			)
+
+			claims := &jwtsec.StandardClaims{
+				Issuer:    "https://issuer.example",
+				Subject:   "alice",
+				Audience:  jwtsec.Audience{"api"},
+				ExpiresAt: jwtsec.NewNumericDate(clk.Now().Add(time.Hour)),
+				IssuedAt:  jwtsec.NewNumericDate(clk.Now()),
+			}
+
+			token, err := signer.Sign(context.Background(), claims)
+			require.NoError(t, err)
+			assert.Equal(t, 2, strings.Count(token, "."), "JWT compact serialization has 3 segments")
+
+			got, err := verifier.Verify(context.Background(), token, nil)
+			require.NoError(t, err)
+			assert.Equal(t, "alice", got.Subject)
+			assert.Equal(t, "https://issuer.example", got.Issuer)
+		})
+	}
+}
+
+func TestVerifyRejectsAlgNone(t *testing.T) {
+	t.Parallel()
+
+	_, pub := genRSA(t)
+	provider := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub})
+	verifier := jwtsec.NewVerifier(provider)
+
+	// "alg=none" canonical attack token: header={"alg":"none"}, payload empty, no signature.
+	// header b64 ("eyJhbGciOiJub25lIn0") . payload b64 ("e30") . empty
+	none := "eyJhbGciOiJub25lIn0.e30."
+
+	_, err := verifier.Verify(context.Background(), none, nil)
+	require.Error(t, err)
+	// go-jose's ParseSignedCompact already refuses unknown algs, so any error
+	// from this path is a valid defense (either ErrAlgorithmNotAllowed or
+	// ErrMalformedToken). The key fact is that it is REFUSED.
+	assert.NotEqual(t, "", err.Error())
+}
+
+func TestVerifyRejectsKeyConfusion(t *testing.T) {
+	t.Parallel()
+
+	// Classic key-confusion attack: signer uses HS256 with the verifier's
+	// public RSA key as the HMAC secret. With HS256 NOT in the allowlist,
+	// the verifier must reject the token before reading any key material.
+	rsaPriv, rsaPub := genRSA(t)
+	provider := jwtsec.NewStaticJWKS([]jwtsec.PublicKey{rsaPub})
+
+	verifier := jwtsec.NewVerifier(provider) // default allowlist excludes HS*
+
+	// Sign with HS256 — we'd need raw bytes of the RSA public key as the
+	// shared secret, but a legitimately signed RS256 token suffices to
+	// prove the verifier accepts RS256 while rejecting HS256 even when
+	// configured with the same key material:
+	rsSigner := jwtsec.NewSigner(rsaPriv)
+	good, err := rsSigner.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		ExpiresAt: jwtsec.NewNumericDate(time.Now().Add(time.Hour)),
+	})
+	require.NoError(t, err)
+	_, err = verifier.Verify(context.Background(), good, nil)
+	require.NoError(t, err, "RS256 allowed by default")
+
+	// Now construct a verifier that has HS256 in the allowlist but whose
+	// JWKS still ships the RSA public key. Even then, the kid lookup must
+	// fail because the attacker token uses a different kid (none). We
+	// can't easily fake an HS256 token here without rebuilding go-jose's
+	// internals, so we settle for the allowlist proof above as the canonical
+	// defense; the AlgorithmAllowed test below covers the alg-driven path.
+}
+
+func TestVerifyRejectsExpired(t *testing.T) {
+	t.Parallel()
+
+	clk := newFixedClock(time.Date(2026, 5, 19, 12, 0, 0, 0, time.UTC))
+	priv, pub := genECDSA(t)
+
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithClock(clk),
+	)
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		ExpiresAt: jwtsec.NewNumericDate(clk.Now().Add(-time.Hour)),
+	})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, jwtsec.ErrTokenExpired)
+}
+
+func TestVerifyClockSkewToleratesNearMissExpiry(t *testing.T) {
+	t.Parallel()
+
+	clk := newFixedClock(time.Date(2026, 5, 19, 12, 0, 0, 0, time.UTC))
+	priv, pub := genECDSA(t)
+
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithClock(clk),
+		jwtsec.WithClockSkew(30*time.Second),
+	)
+
+	// Token expired 10s ago, within the 30s skew window.
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		ExpiresAt: jwtsec.NewNumericDate(clk.Now().Add(-10 * time.Second)),
+	})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.NoError(t, err, "skew window must tolerate near-miss expiries")
+}
+
+func TestVerifyRejectsMissingExpiryByDefault(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}))
+
+	// A validly-signed token with no `exp` claim — a token that never
+	// expires. RFC 9068 §2.2 forbids this for access tokens.
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{Subject: "alice"})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, jwtsec.ErrMissingExpiry)
+	// Bridges to the core sentinel so transport mappers classify it.
+	assert.ErrorIs(t, err, security.ErrTokenExpired)
+}
+
+func TestVerifyOptionalExpiryAllowsMissingExp(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithOptionalExpiry(),
+	)
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{Subject: "alice"})
+
+	claims, err := verifier.Verify(context.Background(), token, nil)
+	require.NoError(t, err, "WithOptionalExpiry must accept a token without exp")
+	assert.Equal(t, "alice", claims.Subject)
+}
+
+func TestVerifyRejectsBadIssuer(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithIssuer("https://issuer.example"),
+	)
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Issuer:  "https://malicious.example",
+		Subject: "alice",
+	})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, jwtsec.ErrInvalidIssuer)
+}
+
+func TestVerifyRejectsBadAudience(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithAudience("api-1", "api-2"),
+	)
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:  "alice",
+		Audience: jwtsec.Audience{"api-3"},
+	})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, jwtsec.ErrInvalidAudience)
+}
+
+func TestVerifyAcceptsAnyMatchingAudience(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(
+		jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}),
+		jwtsec.WithAudience("api-1", "api-2"),
+	)
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{
+		Subject:   "alice",
+		Audience:  jwtsec.Audience{"other", "api-2"},
+		ExpiresAt: jwtsec.NewNumericDate(time.Now().Add(time.Hour)),
+	})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.NoError(t, err)
+}
+
+func TestVerifyRejectsUnknownKid(t *testing.T) {
+	t.Parallel()
+
+	priv1, _ := genECDSA(t)
+	// Verifier has a different key set.
+	_, pub2 := genECDSA(t)
+
+	signer := jwtsec.NewSigner(priv1)
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub2}))
+
+	token, _ := signer.Sign(context.Background(), &jwtsec.StandardClaims{Subject: "alice"})
+
+	_, err := verifier.Verify(context.Background(), token, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, jwtsec.ErrInvalidSignature)
+}
+
+func TestVerifyCustomClaimsUnmarshal(t *testing.T) {
+	t.Parallel()
+
+	priv, pub := genECDSA(t)
+	signer := jwtsec.NewSigner(priv)
+	verifier := jwtsec.NewVerifier(jwtsec.NewStaticJWKS([]jwtsec.PublicKey{pub}))
+
+	type custom struct {
+		jwtsec.StandardClaims
+		Tenant string `json:"tenant"`
+	}
+
+	token, _ := signer.Sign(context.Background(), custom{
+		StandardClaims: jwtsec.StandardClaims{
+			Subject:   "alice",
+			ExpiresAt: jwtsec.NewNumericDate(time.Now().Add(time.Hour)),
+		},
+		Tenant: "acme",
+	})
+
+	var got custom
+	_, err := verifier.Verify(context.Background(), token, &got)
+	require.NoError(t, err)
+	assert.Equal(t, "alice", got.Subject)
+	assert.Equal(t, "acme", got.Tenant)
+}
+
+func TestSignerPanicsOnInvalidKey(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() {
+		jwtsec.NewSigner(jwtsec.PrivateKey{}) // empty alg
+	})
+}
diff --git a/jwt/signer.go b/jwt/signer.go
new file mode 100644
index 0000000..8384f33
--- /dev/null
+++ b/jwt/signer.go
@@ -0,0 +1,97 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	jose "github.com/go-jose/go-jose/v4"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+// Signer produces signed JWS tokens.
+type Signer interface {
+	// Sign serializes claims to JSON and signs them with the active key
+	// configured at construction time. claims MAY be a [StandardClaims]
+	// value, a struct embedding it, or any json-marshalable type.
+	Sign(ctx context.Context, claims any) (string, error)
+
+	// Algorithm returns the JOSE alg used by this signer.
+	Algorithm() Algorithm
+
+	// KeyID returns the kid attached to the active key (if any). Verifiers
+	// rely on the header kid to select the right key from a JWKS.
+	KeyID() string
+}
+
+// NewSigner returns a Signer using the supplied PrivateKey. The key's
+// Algorithm MUST be non-empty; the function panics otherwise to refuse a
+// silently-misconfigured signer.
+func NewSigner(active PrivateKey, _ ...Option) Signer {
+	if active.Algorithm == "" {
+		panic("jwtsec.NewSigner: PrivateKey.Algorithm is required")
+	}
+
+	if active.Key == nil {
+		panic("jwtsec.NewSigner: PrivateKey.Key is required")
+	}
+
+	return &signer{key: active}
+}
+
+type signer struct {
+	key PrivateKey
+}
+
+// Algorithm implements [Signer].
+func (s *signer) Algorithm() Algorithm { return s.key.Algorithm }
+
+// KeyID implements [Signer].
+func (s *signer) KeyID() string { return s.key.KeyID }
+
+// Sign implements [Signer].
+func (s *signer) Sign(ctx context.Context, claims any) (string, error) {
+	ctx, span := otel.Tracer(tracerName).Start(ctx, "jwtsec.Signer.Sign")
+	defer span.End()
+
+	span.SetAttributes(
+		attribute.String("jwt.alg", string(s.key.Algorithm)),
+		attribute.String("jwt.kid", s.key.KeyID),
+	)
+
+	if err := ctx.Err(); err != nil {
+		return "", fmt.Errorf("jwt: context canceled: %w", err)
+	}
+
+	payload, err := json.Marshal(claims)
+	if err != nil {
+		return "", fmt.Errorf("jwt: marshal claims: %w", err)
+	}
+
+	jwk := s.key.toJOSE()
+
+	jws, err := jose.NewSigner(
+		jose.SigningKey{Algorithm: s.key.Algorithm.joseAlg(), Key: jwk},
+		(&jose.SignerOptions{}).WithType("JWT"),
+	)
+	if err != nil {
+		return "", fmt.Errorf("jwt: new signer: %w", err)
+	}
+
+	signed, err := jws.Sign(payload)
+	if err != nil {
+		return "", fmt.Errorf("jwt: sign: %w", err)
+	}
+
+	out, err := signed.CompactSerialize()
+	if err != nil {
+		return "", fmt.Errorf("jwt: serialize: %w", err)
+	}
+
+	return out, nil
+}
diff --git a/jwt/testing_helpers_test.go b/jwt/testing_helpers_test.go
new file mode 100644
index 0000000..78f70e4
--- /dev/null
+++ b/jwt/testing_helpers_test.go
@@ -0,0 +1,60 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec_test
+
+import (
+	"crypto/ecdsa"
+	"crypto/ed25519"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+
+	jwtsec "github.com/hyperscale-stack/security/jwt"
+	"github.com/stretchr/testify/require"
+)
+
+// genRSA generates a fresh 2048-bit RSA key pair for tests. RSA is the
+// slowest of the supported algorithms; use sparingly.
+func genRSA(t *testing.T) (jwtsec.PrivateKey, jwtsec.PublicKey) {
+	t.Helper()
+
+	priv, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	return jwtsec.PrivateKey{KeyID: "rsa-1", Algorithm: jwtsec.RS256, Key: priv},
+		jwtsec.PublicKey{KeyID: "rsa-1", Algorithm: jwtsec.RS256, Key: &priv.PublicKey}
+}
+
+// genECDSA generates a fresh P-256 key pair.
+func genECDSA(t *testing.T) (jwtsec.PrivateKey, jwtsec.PublicKey) {
+	t.Helper()
+
+	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+
+	return jwtsec.PrivateKey{KeyID: "ec-1", Algorithm: jwtsec.ES256, Key: priv},
+		jwtsec.PublicKey{KeyID: "ec-1", Algorithm: jwtsec.ES256, Key: &priv.PublicKey}
+}
+
+// genEd25519 generates a fresh Ed25519 key pair.
+func genEd25519(t *testing.T) (jwtsec.PrivateKey, jwtsec.PublicKey) {
+	t.Helper()
+
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	require.NoError(t, err)
+
+	return jwtsec.PrivateKey{KeyID: "ed-1", Algorithm: jwtsec.EdDSA, Key: priv},
+		jwtsec.PublicKey{KeyID: "ed-1", Algorithm: jwtsec.EdDSA, Key: pub}
+}
+
+// fixedClock is a [security.Clock] returning a static time, used to make
+// expiry / not-before / issued-at tests deterministic.
+type fixedClock struct{ now time.Time }
+
+func newFixedClock(now time.Time) fixedClock { return fixedClock{now: now} }
+
+func (c fixedClock) Now() time.Time { return c.now }
diff --git a/jwt/validator.go b/jwt/validator.go
new file mode 100644
index 0000000..baf008c
--- /dev/null
+++ b/jwt/validator.go
@@ -0,0 +1,75 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"fmt"
+	"slices"
+	"time"
+)
+
+// validateStandardClaims runs the issuer / audience / exp / nbf checks per
+// RFC 7519 §4.1, observing the configured clock skew. iat is informational
+// (no rejection) but tokens with iat in the future beyond the skew window
+// are refused as a defense against tokens forged with a tampered clock.
+//
+// An `exp` claim is mandatory unless the verifier opted into
+// [WithOptionalExpiry]: a token that never expires is rejected fail-closed.
+func validateStandardClaims(c *config, claims *StandardClaims) error {
+	now := c.clock.Now()
+
+	if c.issuer != "" && claims.Issuer != c.issuer {
+		return fmt.Errorf("%w: have %q, want %q", ErrInvalidIssuer, claims.Issuer, c.issuer)
+	}
+
+	if len(c.audiences) > 0 {
+		if !audienceMatches(c.audiences, claims.Audience) {
+			return fmt.Errorf("%w: have %v, want one of %v",
+				ErrInvalidAudience, []string(claims.Audience), c.audiences)
+		}
+	}
+
+	if claims.ExpiresAt == nil {
+		if c.requireExpiry {
+			return ErrMissingExpiry
+		}
+	} else {
+		exp := claims.ExpiresAt.Time()
+		if !exp.IsZero() && now.After(exp.Add(c.skew)) {
+			return fmt.Errorf("%w (now=%s exp=%s)", ErrTokenExpired,
+				now.Format(time.RFC3339), exp.Format(time.RFC3339))
+		}
+	}
+
+	if claims.NotBefore != nil {
+		nbf := claims.NotBefore.Time()
+		if !nbf.IsZero() && now.Before(nbf.Add(-c.skew)) {
+			return fmt.Errorf("%w (now=%s nbf=%s)", ErrTokenNotYetValid,
+				now.Format(time.RFC3339), nbf.Format(time.RFC3339))
+		}
+	}
+
+	if claims.IssuedAt != nil {
+		iat := claims.IssuedAt.Time()
+		if !iat.IsZero() && iat.After(now.Add(c.skew)) {
+			return fmt.Errorf("%w (now=%s iat=%s)", ErrTokenNotYetValid,
+				now.Format(time.RFC3339), iat.Format(time.RFC3339))
+		}
+	}
+
+	return nil
+}
+
+// audienceMatches reports whether at least one element of the token's aud
+// matches one of the configured audiences.
+func audienceMatches(configured []string, token Audience) bool {
+	for _, a := range token {
+		if slices.Contains(configured, a) {
+			return true
+		}
+	}
+
+	return false
+}
diff --git a/jwt/verifier.go b/jwt/verifier.go
new file mode 100644
index 0000000..4c35b5c
--- /dev/null
+++ b/jwt/verifier.go
@@ -0,0 +1,145 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package jwtsec
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"slices"
+
+	jose "github.com/go-jose/go-jose/v4"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+)
+
+// Verifier parses and validates a compact-serialized JWT, returning the
+// decoded standard claims plus the raw payload for caller-specific claim
+// decoding.
+type Verifier interface {
+	// Verify parses token, validates the signature against the JWKS, runs
+	// the iss/aud/exp/nbf checks per the configured Options, and
+	// unmarshals the payload into claimsOut. claimsOut MAY be nil when the
+	// caller only needs the standard claims (returned separately).
+	Verify(ctx context.Context, token string, claimsOut any) (*StandardClaims, error)
+}
+
+// NewVerifier returns a Verifier sourcing keys from provider. Defaults:
+// asymmetric algorithm allowlist (HS* opt-in only), no issuer / audience
+// pinning, no clock skew, wall clock.
+func NewVerifier(provider JWKSProvider, opts ...Option) Verifier {
+	cfg := defaults()
+	for _, o := range opts {
+		o(cfg)
+	}
+
+	return &verifier{provider: provider, cfg: cfg}
+}
+
+type verifier struct {
+	provider JWKSProvider
+	cfg      *config
+}
+
+// Verify implements [Verifier].
+func (v *verifier) Verify(ctx context.Context, token string, claimsOut any) (*StandardClaims, error) {
+	ctx, span := otel.Tracer(tracerName).Start(ctx, "jwtsec.Verifier.Verify")
+	defer span.End()
+
+	parsed, err := jose.ParseSignedCompact(token, joseAllowed(v.cfg.allowed))
+	if err != nil {
+		span.SetStatus(codes.Error, "parse")
+		span.RecordError(err)
+
+		return nil, fmt.Errorf("%w: %w", ErrMalformedToken, err)
+	}
+
+	if len(parsed.Signatures) != 1 {
+		err := fmt.Errorf("%w: expected exactly one signature", ErrMalformedToken)
+
+		span.SetStatus(codes.Error, "multi-sig")
+
+		return nil, err
+	}
+
+	header := parsed.Signatures[0].Header
+	alg := Algorithm(header.Algorithm)
+	span.SetAttributes(
+		attribute.String("jwt.alg", string(alg)),
+		attribute.String("jwt.kid", header.KeyID),
+	)
+
+	if !v.cfg.algorithmAllowed(alg) {
+		// errAlgorithmDisallowed wraps ErrAlgorithmNotAllowed and keeps the
+		// offending alg reachable via AsAlgorithmName for telemetry.
+		err := &errAlgorithmDisallowed{alg: string(alg)}
+
+		span.SetStatus(codes.Error, "alg")
+		span.RecordError(err)
+
+		return nil, err
+	}
+
+	keys, err := v.provider.KeySet(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("jwt: load JWKS: %w", err)
+	}
+
+	pub, ok := keys.ByKeyID(header.KeyID)
+	if !ok {
+		err := fmt.Errorf("%w: unknown kid %q", ErrInvalidSignature, header.KeyID)
+
+		span.SetStatus(codes.Error, "kid")
+		span.RecordError(err)
+
+		return nil, err
+	}
+
+	payload, err := parsed.Verify(pub.toJOSE())
+	if err != nil {
+		span.SetStatus(codes.Error, "signature")
+		span.RecordError(err)
+
+		return nil, fmt.Errorf("%w: %w", ErrInvalidSignature, err)
+	}
+
+	var std StandardClaims
+	if err := json.Unmarshal(payload, &std); err != nil {
+		span.SetStatus(codes.Error, "unmarshal")
+
+		return nil, fmt.Errorf("%w: %w", ErrMalformedToken, err)
+	}
+
+	if err := validateStandardClaims(v.cfg, &std); err != nil {
+		span.SetStatus(codes.Error, err.Error())
+		span.RecordError(err)
+
+		return nil, err
+	}
+
+	if claimsOut != nil {
+		if err := json.Unmarshal(payload, claimsOut); err != nil {
+			return nil, fmt.Errorf("%w: %w", ErrMalformedToken, err)
+		}
+	}
+
+	span.SetAttributes(attribute.String("jwt.iss", std.Issuer))
+
+	return &std, nil
+}
+
+// joseAllowed converts the typed allowlist to go-jose's SignatureAlgorithm
+// slice so ParseSignedCompact rejects unknown algs without consulting the
+// underlying key.
+func joseAllowed(in []Algorithm) []jose.SignatureAlgorithm {
+	out := make([]jose.SignatureAlgorithm, 0, len(in))
+
+	for _, a := range slices.Clone(in) {
+		out = append(out, a.joseAlg())
+	}
+
+	return out
+}
diff --git a/manager.go b/manager.go
new file mode 100644
index 0000000..aa11587
--- /dev/null
+++ b/manager.go
@@ -0,0 +1,104 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"go.opentelemetry.io/otel/codes"
+)
+
+// Manager orchestrates a chain of [Authenticator]s with first-success-wins
+// semantics:
+//
+//   - Authenticators are consulted in registration order.
+//   - The first authenticator whose Supports() returns true is invoked.
+//   - On success, the resulting Authentication is returned immediately;
+//     subsequent authenticators are NOT consulted.
+//   - On error, the next supporting authenticator is tried; if every one
+//     fails, the joined error is wrapped in [ErrAuthenticatorRefused].
+//   - If no authenticator supports the credential, [ErrUnsupportedCredential]
+//     is returned. The [Engine] then surfaces it as a 400 in the HTTP adapter.
+//
+// Manager is safe for concurrent use.
+type Manager interface {
+	Authenticate(ctx context.Context, auth Authentication) (Authentication, error)
+}
+
+// NewManager returns a [Manager] consulting the given authenticators in
+// order. Passing zero authenticators is allowed; the returned manager will
+// always return [ErrUnsupportedCredential].
+func NewManager(authenticators ...Authenticator) Manager {
+	cp := make([]Authenticator, len(authenticators))
+	copy(cp, authenticators)
+
+	return &manager{authenticators: cp}
+}
+
+type manager struct {
+	authenticators []Authenticator
+}
+
+// Authenticate implements [Manager].
+func (m *manager) Authenticate(ctx context.Context, auth Authentication) (Authentication, error) {
+	ctx, span := tracer().Start(ctx, "security.Manager.Authenticate")
+	defer span.End()
+
+	span.SetAttributes(AttrAuthenticatorsCount.Int(len(m.authenticators)))
+
+	var (
+		anySupported bool
+		errs         []error
+	)
+
+	for _, a := range m.authenticators {
+		if !a.Supports(auth) {
+			continue
+		}
+
+		anySupported = true
+		name := authenticatorName(a)
+		span.AddEvent("authenticator.try", trAttrName(name))
+
+		result, err := a.Authenticate(ctx, auth)
+		if err == nil {
+			span.SetAttributes(
+				AttrAuthenticated.Bool(true),
+				AttrAuthenticatorName.String(name),
+			)
+
+			return result, nil
+		}
+
+		errs = append(errs, fmt.Errorf("%s: %w", name, err))
+	}
+
+	if !anySupported {
+		err := ErrUnsupportedCredential
+		span.SetStatus(codes.Error, err.Error())
+		span.RecordError(err)
+
+		return auth, err
+	}
+
+	joined := errors.Join(errs...)
+	err := fmt.Errorf("%w: %w", ErrAuthenticatorRefused, joined)
+	span.SetStatus(codes.Error, ErrAuthenticatorRefused.Error())
+	span.RecordError(err)
+
+	return auth, err
+}
+
+// authenticatorName returns the [NamedAuthenticator] name if implemented, or
+// the Go type name as a fallback.
+func authenticatorName(a Authenticator) string {
+	if n, ok := a.(NamedAuthenticator); ok {
+		return n.AuthenticatorName()
+	}
+
+	return fmt.Sprintf("%T", a)
+}
diff --git a/manager_test.go b/manager_test.go
new file mode 100644
index 0000000..9de0bd8
--- /dev/null
+++ b/manager_test.go
@@ -0,0 +1,148 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestManagerReturnsUnsupportedWhenNoAuthenticator(t *testing.T) {
+	m := security.NewManager()
+	auth := newFakeAuth("alice")
+
+	got, err := m.Authenticate(context.Background(), auth)
+
+	assert.ErrorIs(t, err, security.ErrUnsupportedCredential)
+	assert.Equal(t, Authentication(auth), got, "input MUST flow through on failure")
+}
+
+func TestManagerReturnsUnsupportedWhenNoAuthenticatorSupports(t *testing.T) {
+	a := &scriptedAuthenticator{
+		name:     "noop",
+		supports: func(Authentication) bool { return false },
+	}
+	m := security.NewManager(a)
+
+	_, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+
+	assert.ErrorIs(t, err, security.ErrUnsupportedCredential)
+	assert.Zero(t, a.calls(), "Authenticate must not be called when Supports is false")
+}
+
+func TestManagerFirstSuccessWins(t *testing.T) {
+	authenticated := newFakeAuth("alice").withAuthenticated()
+
+	first := &scriptedAuthenticator{name: "first", result: authenticated}
+	second := &scriptedAuthenticator{name: "second", result: newFakeAuth("bob").withAuthenticated()}
+
+	m := security.NewManager(first, second)
+
+	got, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+
+	require.NoError(t, err)
+	assert.Equal(t, Authentication(authenticated), got)
+	assert.Equal(t, 1, first.calls())
+	assert.Zero(t, second.calls(), "second authenticator MUST NOT be consulted after success")
+}
+
+func TestManagerFailoverWhenSupportingAuthenticatorRefuses(t *testing.T) {
+	winning := newFakeAuth("alice").withAuthenticated()
+	first := &scriptedAuthenticator{name: "first", err: security.ErrInvalidCredentials}
+	second := &scriptedAuthenticator{name: "second", result: winning}
+
+	m := security.NewManager(first, second)
+
+	got, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+
+	require.NoError(t, err)
+	assert.Equal(t, Authentication(winning), got)
+	assert.Equal(t, 1, first.calls())
+	assert.Equal(t, 1, second.calls())
+}
+
+func TestManagerAggregatesErrorsWhenAllRefuse(t *testing.T) {
+	first := &scriptedAuthenticator{name: "first", err: security.ErrInvalidCredentials}
+	second := &scriptedAuthenticator{name: "second", err: security.ErrTokenExpired}
+
+	m := security.NewManager(first, second)
+
+	_, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrAuthenticatorRefused)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+	assert.ErrorIs(t, err, security.ErrTokenExpired)
+}
+
+func TestManagerSpanCarriesAuthenticatorName(t *testing.T) {
+	winning := newFakeAuth("alice").withAuthenticated()
+	a := &scriptedAuthenticator{name: "winner", result: winning}
+
+	m := security.NewManager(a)
+
+	spans := spanRecorder(func() {
+		_, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+		require.NoError(t, err)
+	})
+
+	require.Len(t, spans, 1)
+	span := spans[0]
+
+	assert.Equal(t, "security.Manager.Authenticate", span.Name())
+	assert.Equal(t, "true", findAttr(span.Attributes(), security.AttrAuthenticated))
+	assert.Equal(t, "winner", findAttr(span.Attributes(), security.AttrAuthenticatorName))
+}
+
+func TestManagerSpanRecordsErrorOnRefuseAll(t *testing.T) {
+	a := &scriptedAuthenticator{name: "x", err: errors.New("boom")}
+
+	m := security.NewManager(a)
+
+	spans := spanRecorder(func() {
+		_, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+		assert.Error(t, err)
+	})
+
+	require.Len(t, spans, 1)
+	assert.Equal(t, "Error", spans[0].Status().Code.String())
+}
+
+func TestManagerSafeForConcurrentUse(t *testing.T) {
+	winning := newFakeAuth("alice").withAuthenticated()
+	a := &scriptedAuthenticator{name: "winner", result: winning}
+	m := security.NewManager(a)
+
+	var (
+		wg     sync.WaitGroup
+		errors = make(chan error, 50)
+	)
+
+	for range 50 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			_, err := m.Authenticate(context.Background(), newFakeAuth("alice"))
+			if err != nil {
+				errors <- err
+			}
+		}()
+	}
+
+	wg.Wait()
+	close(errors)
+
+	for err := range errors {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
diff --git a/oauth2/authorize_endpoint.go b/oauth2/authorize_endpoint.go
new file mode 100644
index 0000000..fdc25fd
--- /dev/null
+++ b/oauth2/authorize_endpoint.go
@@ -0,0 +1,556 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+)
+
+// Authorization-endpoint defaults applied when the matching
+// [AuthorizeConfig] field is left zero.
+const (
+	// defaultAuthCodeTTL caps the authorization-code lifetime (RFC 6749
+	// §4.1.2 recommends 10 minutes maximum).
+	defaultAuthCodeTTL = 10 * time.Minute
+	// defaultImplicitTTL is the implicit-flow access-token lifetime.
+	defaultImplicitTTL = time.Hour
+)
+
+// RFC 6749 §3.1.1 response_type values handled by the authorization
+// endpoint: "code" is the authorization-code flow, "token" the legacy
+// implicit flow.
+const (
+	responseTypeCode  = "code"
+	responseTypeToken = "token"
+)
+
+// authorizeFlow identifies which /authorize flow a request runs.
+type authorizeFlow int
+
+const (
+	flowCode     authorizeFlow = iota // response_type=code
+	flowImplicit                      // response_type=token (legacy)
+)
+
+// OpaqueTokenGenerator mints opaque tokens — a raw value plus the storage
+// hash. The token sub-package's OpaqueRefreshAdapter and OpaqueCodeAdapter
+// satisfy it; it is the type the implicit flow uses to issue access tokens.
+type OpaqueTokenGenerator interface {
+	Generate(ctx context.Context) (raw, hash string, err error)
+}
+
+// AuthorizeRequest is the parsed and validated /authorize request handed to
+// a [ConsentFunc]. By the time the ConsentFunc sees it, the client and the
+// redirect URI are already verified.
+type AuthorizeRequest struct {
+	// Client is the resolved, registered client.
+	Client Client
+	// ResponseType is the requested response type ("code" or "token").
+	ResponseType string
+	// RedirectURI is the validated redirect URI (exact-matched against the
+	// client registration).
+	RedirectURI string
+	// Scope is the requested scope, already checked against the client's
+	// allowed scopes.
+	Scope string
+	// State is the opaque client state echoed back on the redirect.
+	State string
+	// CodeChallenge / CodeChallengeMethod carry the PKCE parameters
+	// (RFC 7636). Empty when the request carries no PKCE; unused by the
+	// implicit flow.
+	CodeChallenge       string
+	CodeChallengeMethod string
+	// Nonce echoes the OIDC nonce parameter, when present.
+	Nonce string
+}
+
+// Consent is the resource-owner decision returned by a [ConsentFunc].
+type Consent struct {
+	// Approved reports whether the resource owner granted the request.
+	Approved bool
+	// Subject is the authenticated resource-owner identifier. It is
+	// required when Approved is true.
+	Subject string
+	// Scope is the granted scope. Empty means "exactly what was requested";
+	// a non-empty value MUST be a subset of [AuthorizeRequest.Scope] — the
+	// consent step may narrow the grant but never broaden it.
+	Scope string
+}
+
+// ConsentFunc is the application hook invoked by [Server.AuthorizeHandler]
+// once the /authorize request is validated. The application authenticates
+// the resource owner, renders its own login / consent UI, and returns the
+// decision.
+//
+// Return contract:
+//   - (consent, nil): the handler proceeds — it mints the authorization
+//     code (or implicit token) and redirects to the client's redirect URI.
+//   - (nil, nil): the ConsentFunc has already written a response to w
+//     (typically the login / consent page on the initial GET); the handler
+//     does nothing more.
+//   - (nil, err): the handler redirects to the client with a server_error.
+type ConsentFunc func(w http.ResponseWriter, r *http.Request, ar *AuthorizeRequest) (*Consent, error)
+
+// AuthorizeConfig configures the /authorize endpoint.
+type AuthorizeConfig struct {
+	// CodeTTL is the authorization-code lifetime. Defaults to 10 minutes
+	// (RFC 6749 §4.1.2) when zero.
+	CodeTTL time.Duration
+	// AllowImplicit enables the legacy implicit flow (response_type=token).
+	//
+	// LEGACY — discouraged: the access token is returned in the redirect
+	// fragment, exposed to the browser. The OAuth 2.0 Security BCP and
+	// OAuth 2.1 drop the implicit flow; [Server.AuthorizeHandler] panics if
+	// AllowImplicit is set on a server whose profile is not [Profile20].
+	// Opt-in only.
+	AllowImplicit bool
+	// ImplicitTokens mints the opaque access tokens returned by the
+	// implicit flow. Required when AllowImplicit is set.
+	ImplicitTokens OpaqueTokenGenerator
+	// ImplicitTTL is the implicit access-token lifetime. Defaults to 1h.
+	ImplicitTTL time.Duration
+}
+
+// AuthorizeHandler returns the http.Handler for the RFC 6749 §3.1
+// authorization endpoint. It serves the authorization-code flow and,
+// when [AuthorizeConfig.AllowImplicit] is set, the legacy implicit flow.
+//
+// The handler validates the request (client, redirect URI, response type,
+// scope, PKCE) and then calls consent. The library owns the protocol
+// plumbing — request validation, code / token minting, the redirect —
+// while the application owns the login and consent UI through the
+// [ConsentFunc].
+//
+// Errors that occur before the redirect URI is trusted (unknown client,
+// unregistered redirect URI) are returned directly with a 400 status and
+// are NOT redirected, per RFC 6749 §4.1.2.1 (open-redirector protection).
+// Every later error is redirected back to the client — in the query string
+// for the code flow, in the fragment for the implicit flow.
+//
+// AuthorizeHandler panics on a nil consent, and on an implicit-flow
+// misconfiguration (AllowImplicit on a non-Profile20 server, or without an
+// ImplicitTokens generator).
+func (s *Server) AuthorizeHandler(cfg AuthorizeConfig, consent ConsentFunc) http.Handler {
+	if consent == nil {
+		panic("oauth2: AuthorizeHandler: nil ConsentFunc")
+	}
+
+	if cfg.AllowImplicit {
+		if !s.cfg.Profile.AllowsLegacyGrant() {
+			panic("oauth2: AuthorizeHandler: AllowImplicit requires Profile20")
+		}
+
+		if cfg.ImplicitTokens == nil {
+			panic("oauth2: AuthorizeHandler: AllowImplicit requires an ImplicitTokens generator")
+		}
+	}
+
+	if cfg.CodeTTL <= 0 {
+		cfg.CodeTTL = defaultAuthCodeTTL
+	}
+
+	if cfg.ImplicitTTL <= 0 {
+		cfg.ImplicitTTL = defaultImplicitTTL
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		s.serveAuthorize(cfg, consent, w, r)
+	})
+}
+
+func (s *Server) serveAuthorize(cfg AuthorizeConfig, consent ConsentFunc, w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodPost {
+		http.Error(w, "oauth2: /authorize requires GET or POST", http.StatusMethodNotAllowed)
+
+		return
+	}
+
+	if err := r.ParseForm(); err != nil {
+		http.Error(w, "oauth2: malformed authorization request", http.StatusBadRequest)
+
+		return
+	}
+
+	// Client and redirect URI come first: a failure here MUST NOT redirect
+	// (the redirect target is not yet trusted).
+	client, err := s.cfg.ClientStore.LoadClient(r.Context(), r.FormValue("client_id"))
+	if err != nil || client == nil {
+		http.Error(w, "oauth2: unknown or invalid client", http.StatusBadRequest)
+
+		return
+	}
+
+	redirectURI, ok := resolveRedirectURI(client, r.FormValue("redirect_uri"))
+	if !ok {
+		http.Error(w, "oauth2: missing or unregistered redirect_uri", http.StatusBadRequest)
+
+		return
+	}
+
+	state := r.FormValue("state")
+
+	// From here on the redirect URI is trusted: errors travel back to the
+	// client as a redirect.
+	flow, oerr := resolveFlow(cfg, r.FormValue("response_type"))
+	if oerr != nil {
+		// The response type is unknown — default to a query-string error.
+		redirectAuthorizeError(w, r, redirectURI, state, oerr, false)
+
+		return
+	}
+
+	useFragment := flow == flowImplicit
+
+	ar, oerr := s.parseAuthorizeRequest(r, client, redirectURI, flow)
+	if oerr != nil {
+		redirectAuthorizeError(w, r, redirectURI, state, oerr, useFragment)
+
+		return
+	}
+
+	decision, err := consent(w, r, ar)
+	if err != nil {
+		redirectAuthorizeError(w, r, redirectURI, ar.State,
+			ErrServerError.WithDescription("consent handler failed"), useFragment)
+
+		return
+	}
+
+	if decision == nil {
+		// The ConsentFunc rendered its own response (login / consent page).
+		return
+	}
+
+	if !decision.Approved {
+		redirectAuthorizeError(w, r, redirectURI, ar.State,
+			ErrAccessDenied.WithDescription("the resource owner denied the request"), useFragment)
+
+		return
+	}
+
+	if flow == flowImplicit {
+		s.issueImplicitToken(cfg, w, r, ar, decision)
+
+		return
+	}
+
+	s.issueAuthorizationCode(cfg, w, r, ar, decision)
+}
+
+// resolveFlow maps the response_type parameter to a flow, refusing the
+// implicit flow when it is not enabled.
+func resolveFlow(cfg AuthorizeConfig, responseType string) (authorizeFlow, *Error) {
+	switch responseType {
+	case responseTypeCode:
+		return flowCode, nil
+	case responseTypeToken:
+		if !cfg.AllowImplicit {
+			return 0, ErrUnsupportedResponseType.WithDescription("the implicit flow is not enabled")
+		}
+
+		return flowImplicit, nil
+	default:
+		return 0, ErrUnsupportedResponseType.WithDescription(
+			"response_type " + responseType + " is not supported")
+	}
+}
+
+// parseAuthorizeRequest validates the scope and (for the code flow) the
+// PKCE parameters, returning the [AuthorizeRequest] or an [*Error].
+func (s *Server) parseAuthorizeRequest(r *http.Request, client Client, redirectURI string, flow authorizeFlow) (*AuthorizeRequest, *Error) {
+	scope, err := authorizeScope(r.FormValue("scope"), client.Scopes())
+	if err != nil {
+		return nil, ErrInvalidScope.WithDescription(err.Error())
+	}
+
+	challenge := r.FormValue("code_challenge")
+	method := r.FormValue("code_challenge_method")
+
+	// PKCE applies to the authorization-code flow only.
+	if flow == flowCode {
+		if perr := s.validateAuthorizePKCE(challenge, method); perr != nil {
+			return nil, ErrInvalidRequest.WithDescription(perr.Error())
+		}
+	}
+
+	return &AuthorizeRequest{
+		Client:              client,
+		ResponseType:        r.FormValue("response_type"),
+		RedirectURI:         redirectURI,
+		Scope:               scope,
+		State:               r.FormValue("state"),
+		CodeChallenge:       challenge,
+		CodeChallengeMethod: method,
+		Nonce:               r.FormValue("nonce"),
+	}, nil
+}
+
+// validateAuthorizePKCE enforces the profile's PKCE policy on the
+// /authorize parameters.
+func (s *Server) validateAuthorizePKCE(challenge, method string) error {
+	if challenge == "" {
+		if s.cfg.Profile.RequiresPKCE() {
+			return errors.New("code_challenge is required")
+		}
+
+		return nil
+	}
+
+	switch pkce.Method(method) {
+	case "", pkce.MethodPlain:
+		if !s.cfg.Profile.AllowsPKCEPlain() {
+			return errors.New(`code_challenge_method "plain" is refused by the active profile`)
+		}
+	case pkce.MethodS256:
+		// S256 is always acceptable.
+	default:
+		return fmt.Errorf("unsupported code_challenge_method %q", method)
+	}
+
+	return nil
+}
+
+// issueAuthorizationCode mints the code, persists it, and redirects.
+func (s *Server) issueAuthorizationCode(
+	cfg AuthorizeConfig,
+	w http.ResponseWriter,
+	r *http.Request,
+	ar *AuthorizeRequest,
+	decision *Consent,
+) {
+	granted, err := grantedScope(ar, decision)
+	if err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State,
+			ErrInvalidScope.WithDescription("granted scope exceeds the request"), false)
+
+		return
+	}
+
+	raw, err := randomCode()
+	if err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State, ErrServerError.WithCause(err), false)
+
+		return
+	}
+
+	now := s.cfg.Now()
+	// Authorization codes are stored pepper-free (HashToken(nil, …)); the
+	// authorization_code grant looks them up the same way.
+	code := &AuthorizationCode{
+		Code:                raw,
+		CodeHash:            HashToken(nil, raw),
+		ClientID:            ar.Client.ID(),
+		Subject:             decision.Subject,
+		RedirectURI:         ar.RedirectURI,
+		Scope:               granted,
+		CodeChallenge:       ar.CodeChallenge,
+		CodeChallengeMethod: ar.CodeChallengeMethod,
+		Nonce:               ar.Nonce,
+		IssuedAt:            now,
+		ExpiresAt:           now.Add(cfg.CodeTTL),
+	}
+
+	if err := s.cfg.Storage.SaveAuthorizationCode(r.Context(), code); err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State, ErrServerError.WithCause(err), false)
+
+		return
+	}
+
+	params := url.Values{"code": {raw}}
+	if ar.State != "" {
+		params.Set("state", ar.State)
+	}
+
+	//nolint:gosec // G710: redirectURI is exact-matched against the client's registered URIs by resolveRedirectURI
+	http.Redirect(w, r, authorizeRedirectTarget(ar.RedirectURI, params, false), http.StatusFound)
+}
+
+// issueImplicitToken mints an access token, persists it, and redirects it
+// back in the URL fragment (RFC 6749 §4.2.2).
+func (s *Server) issueImplicitToken(
+	cfg AuthorizeConfig,
+	w http.ResponseWriter,
+	r *http.Request,
+	ar *AuthorizeRequest,
+	decision *Consent,
+) {
+	granted, err := grantedScope(ar, decision)
+	if err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State,
+			ErrInvalidScope.WithDescription("granted scope exceeds the request"), true)
+
+		return
+	}
+
+	_, audience, ierr := s.resolveIssuer(r.Context(), r)
+	if ierr != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State, ErrServerError.WithCause(ierr), true)
+
+		return
+	}
+
+	raw, hash, err := cfg.ImplicitTokens.Generate(r.Context())
+	if err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State, ErrServerError.WithCause(err), true)
+
+		return
+	}
+
+	now := s.cfg.Now()
+	at := &AccessToken{
+		Token:     raw,
+		TokenHash: hash,
+		ClientID:  ar.Client.ID(),
+		Subject:   decision.Subject,
+		Scope:     granted,
+		Audience:  audience,
+		IssuedAt:  now,
+		ExpiresAt: now.Add(cfg.ImplicitTTL),
+	}
+
+	if err := s.cfg.Storage.SaveAccessToken(r.Context(), at); err != nil {
+		redirectAuthorizeError(w, r, ar.RedirectURI, ar.State, ErrServerError.WithCause(err), true)
+
+		return
+	}
+
+	params := url.Values{
+		"access_token": {raw},
+		"token_type":   {TokenTypeBearer},
+		"expires_in":   {strconv.Itoa(int(cfg.ImplicitTTL.Seconds()))},
+	}
+	if granted != "" {
+		params.Set("scope", granted)
+	}
+
+	if ar.State != "" {
+		params.Set("state", ar.State)
+	}
+
+	//nolint:gosec // G710: redirectURI is exact-matched against the client's registered URIs by resolveRedirectURI
+	http.Redirect(w, r, authorizeRedirectTarget(ar.RedirectURI, params, true), http.StatusFound)
+}
+
+// grantedScope resolves the scope to grant: the consent value when it
+// narrows the request, the request scope otherwise. Broadening is refused.
+func grantedScope(ar *AuthorizeRequest, decision *Consent) (string, error) {
+	if decision.Scope == "" {
+		return ar.Scope, nil
+	}
+
+	return authorizeScope(decision.Scope, strings.Fields(ar.Scope))
+}
+
+// resolveRedirectURI returns the redirect URI to use: the requested one
+// when it exactly matches a registered URI, or the sole registered URI
+// when the request omitted the parameter. RFC 6749 §3.1.2.3 mandates the
+// exact match.
+func resolveRedirectURI(client Client, requested string) (string, bool) {
+	registered := client.RedirectURIs()
+
+	if requested == "" {
+		if len(registered) == 1 {
+			return registered[0], true
+		}
+
+		return "", false
+	}
+
+	if slices.Contains(registered, requested) {
+		return requested, true
+	}
+
+	return "", false
+}
+
+// authorizeScope checks that every requested scope is in the allowed set
+// and returns the normalized (space-joined) scope. An empty allowed set
+// means the client carries no scope restriction.
+func authorizeScope(requested string, allowed []string) (string, error) {
+	fields := strings.Fields(requested)
+
+	if len(allowed) == 0 {
+		return strings.Join(fields, " "), nil
+	}
+
+	for _, s := range fields {
+		if !slices.Contains(allowed, s) {
+			return "", fmt.Errorf("scope %q is not allowed for this client", s)
+		}
+	}
+
+	return strings.Join(fields, " "), nil
+}
+
+// redirectAuthorizeError sends an RFC 6749 §4.1.2.1 / §4.2.2.1 error
+// response by redirecting back to the client's redirect URI.
+func redirectAuthorizeError(
+	w http.ResponseWriter,
+	r *http.Request,
+	redirectURI, state string,
+	oerr *Error,
+	useFragment bool,
+) {
+	params := url.Values{"error": {oerr.Code}}
+	if oerr.Description != "" {
+		params.Set("error_description", oerr.Description)
+	}
+
+	if state != "" {
+		params.Set("state", state)
+	}
+
+	//nolint:gosec // G710: redirectURI is exact-matched against the client's registered URIs by resolveRedirectURI
+	http.Redirect(w, r, authorizeRedirectTarget(redirectURI, params, useFragment), http.StatusFound)
+}
+
+// authorizeRedirectTarget builds the redirect URL: params land in the
+// fragment for the implicit flow (RFC 6749 §4.2.2) and in the query string
+// otherwise. A registered redirect URI never carries a fragment, so the
+// implicit case appends one safely.
+func authorizeRedirectTarget(redirectURI string, params url.Values, useFragment bool) string {
+	if useFragment {
+		return redirectURI + "#" + params.Encode()
+	}
+
+	u, err := url.Parse(redirectURI)
+	if err != nil {
+		return redirectURI
+	}
+
+	q := u.Query()
+
+	for k, vs := range params {
+		for _, v := range vs {
+			q.Set(k, v)
+		}
+	}
+
+	u.RawQuery = q.Encode()
+
+	return u.String()
+}
+
+// randomCode returns a 256-bit base64url authorization code.
+func randomCode() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("oauth2: read random: %w", err)
+	}
+
+	return base64.RawURLEncoding.EncodeToString(b), nil
+}
diff --git a/oauth2/authorize_endpoint_test.go b/oauth2/authorize_endpoint_test.go
new file mode 100644
index 0000000..574e0d9
--- /dev/null
+++ b/oauth2/authorize_endpoint_test.go
@@ -0,0 +1,518 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/clientauth"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	redirectURI = "https://app.example/cb"
+	// RFC 7636 Appendix B sample PKCE pair.
+	pkceVerifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+	pkceChallenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+)
+
+// newAuthorizeServer builds a server with the authorization_code grant and a
+// client registered with a redirect URI and two scopes.
+func newAuthorizeServer(t *testing.T, profile oauth2.Profile) *oauth2.Server {
+	t.Helper()
+
+	store := memory.New()
+	clients := &staticClientStore{clients: map[string]oauth2.Client{
+		testClientID: &oauth2.DefaultClient{
+			IDValue:           testClientID,
+			Secret:            testClientSecret,
+			TypeValue:         oauth2.ClientConfidential,
+			RedirectURIValues: []string{redirectURI},
+			ScopeValues:       []string{"read", "write"},
+		},
+	}}
+
+	cfg := grant.Config{
+		Storage:       store,
+		AccessTokens:  token.NewOpaque(32),
+		RefreshTokens: token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)},
+		AccessTTL:     time.Hour,
+		RefreshTTL:    24 * time.Hour,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile:        profile,
+		Storage:        store,
+		ClientStore:    clients,
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		Grants:         []oauth2.Grant{grant.NewAuthorizationCode(cfg)},
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+	})
+	require.NoError(t, err)
+
+	return srv
+}
+
+// authorizeQuery is the canonical valid /authorize query (S256 PKCE).
+func authorizeQuery() url.Values {
+	return url.Values{
+		"response_type":         {"code"},
+		"client_id":             {testClientID},
+		"redirect_uri":          {redirectURI},
+		"scope":                 {"read"},
+		"state":                 {"xyz-state"},
+		"code_challenge":        {pkceChallenge},
+		"code_challenge_method": {"S256"},
+	}
+}
+
+// implicitQuery is a valid /authorize query for the implicit flow.
+func implicitQuery() url.Values {
+	return url.Values{
+		"response_type": {"token"},
+		"client_id":     {testClientID},
+		"redirect_uri":  {redirectURI},
+		"scope":         {"read"},
+		"state":         {"impl-state"},
+	}
+}
+
+// implicitTokens is an OpaqueTokenGenerator for the implicit-flow tests.
+func implicitTokens() oauth2.OpaqueTokenGenerator {
+	return token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)}
+}
+
+// runAuthorizeCfg drives the /authorize handler with an explicit config.
+func runAuthorizeCfg(
+	srv *oauth2.Server,
+	cfg oauth2.AuthorizeConfig,
+	q url.Values,
+	consent oauth2.ConsentFunc,
+) *httptest.ResponseRecorder {
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/authorize?"+q.Encode(), nil)
+	srv.AuthorizeHandler(cfg, consent).ServeHTTP(rec, req)
+
+	return rec
+}
+
+// runAuthorize drives the /authorize handler with the default config.
+func runAuthorize(srv *oauth2.Server, q url.Values, consent oauth2.ConsentFunc) *httptest.ResponseRecorder {
+	return runAuthorizeCfg(srv, oauth2.AuthorizeConfig{}, q, consent)
+}
+
+// approve is a ConsentFunc that always grants, as alice.
+func approve(_ http.ResponseWriter, _ *http.Request, _ *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+	return &oauth2.Consent{Approved: true, Subject: "alice"}, nil
+}
+
+func TestAuthorizeHandlerPanicsOnNilConsent(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+	assert.Panics(t, func() { srv.AuthorizeHandler(oauth2.AuthorizeConfig{}, nil) })
+}
+
+func TestAuthorizeCodeHappyPath(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	var seen *oauth2.AuthorizeRequest
+	rec := runAuthorize(srv, authorizeQuery(),
+		func(_ http.ResponseWriter, _ *http.Request, ar *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			seen = ar
+
+			return &oauth2.Consent{Approved: true, Subject: "alice"}, nil
+		})
+
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	loc, err := url.Parse(rec.Header().Get("Location"))
+	require.NoError(t, err)
+	assert.Equal(t, "https://app.example/cb", loc.Scheme+"://"+loc.Host+loc.Path)
+	assert.NotEmpty(t, loc.Query().Get("code"))
+	assert.Equal(t, "xyz-state", loc.Query().Get("state"))
+	assert.Empty(t, loc.Query().Get("error"))
+
+	// The ConsentFunc saw the validated request.
+	require.NotNil(t, seen)
+	assert.Equal(t, "code", seen.ResponseType)
+	assert.Equal(t, redirectURI, seen.RedirectURI)
+	assert.Equal(t, "read", seen.Scope)
+	assert.Equal(t, pkceChallenge, seen.CodeChallenge)
+}
+
+func TestAuthorizeConsentRendersOwnPage(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	rec := runAuthorize(srv, authorizeQuery(),
+		func(w http.ResponseWriter, _ *http.Request, _ *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte("<consent form>"))
+
+			return nil, nil // "I rendered the page myself"
+		})
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "<consent form>", rec.Body.String())
+	assert.Empty(t, rec.Header().Get("Location"))
+}
+
+func TestAuthorizeConsentDenied(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	rec := runAuthorize(srv, authorizeQuery(),
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return &oauth2.Consent{Approved: false}, nil
+		})
+
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	loc, _ := url.Parse(rec.Header().Get("Location"))
+	assert.Equal(t, oauth2.CodeAccessDenied, loc.Query().Get("error"))
+	assert.Equal(t, "xyz-state", loc.Query().Get("state"))
+}
+
+func TestAuthorizeRejectsBadClientWithoutRedirect(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	t.Run("unknown client", func(t *testing.T) {
+		t.Parallel()
+
+		q := authorizeQuery()
+		q.Set("client_id", "ghost")
+
+		rec := runAuthorize(srv, q, approve)
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+		assert.Empty(t, rec.Header().Get("Location"), "an open redirect MUST NOT happen")
+	})
+
+	t.Run("unregistered redirect_uri", func(t *testing.T) {
+		t.Parallel()
+
+		q := authorizeQuery()
+		q.Set("redirect_uri", "https://attacker.example/steal")
+
+		rec := runAuthorize(srv, q, approve)
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+		assert.Empty(t, rec.Header().Get("Location"))
+	})
+}
+
+func TestAuthorizeRedirectsProtocolErrors(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	cases := []struct {
+		name      string
+		mutate    func(url.Values)
+		wantError string
+	}{
+		{"unsupported response_type", func(q url.Values) { q.Set("response_type", "token") }, oauth2.CodeUnsupportedResponseType},
+		{"invalid scope", func(q url.Values) { q.Set("scope", "admin") }, oauth2.CodeInvalidScope},
+		{"missing PKCE under BCP", func(q url.Values) {
+			q.Del("code_challenge")
+			q.Del("code_challenge_method")
+		}, oauth2.CodeInvalidRequest},
+		{"plain PKCE under BCP", func(q url.Values) { q.Set("code_challenge_method", "plain") }, oauth2.CodeInvalidRequest},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			q := authorizeQuery()
+			tc.mutate(q)
+
+			rec := runAuthorize(srv, q, approve)
+			require.Equal(t, http.StatusFound, rec.Code)
+
+			loc, _ := url.Parse(rec.Header().Get("Location"))
+			assert.Equal(t, "https://app.example/cb", loc.Scheme+"://"+loc.Host+loc.Path)
+			assert.Equal(t, tc.wantError, loc.Query().Get("error"))
+		})
+	}
+}
+
+func TestAuthorizeProfile20AllowsNoPKCEAndPlain(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20)
+
+	t.Run("no PKCE", func(t *testing.T) {
+		t.Parallel()
+
+		q := authorizeQuery()
+		q.Del("code_challenge")
+		q.Del("code_challenge_method")
+
+		rec := runAuthorize(srv, q, approve)
+		require.Equal(t, http.StatusFound, rec.Code)
+
+		loc, _ := url.Parse(rec.Header().Get("Location"))
+		assert.NotEmpty(t, loc.Query().Get("code"))
+		assert.Empty(t, loc.Query().Get("error"))
+	})
+
+	t.Run("plain PKCE", func(t *testing.T) {
+		t.Parallel()
+
+		q := authorizeQuery()
+		q.Set("code_challenge", "a-plain-verifier")
+		q.Set("code_challenge_method", "plain")
+
+		rec := runAuthorize(srv, q, approve)
+		require.Equal(t, http.StatusFound, rec.Code)
+
+		loc, _ := url.Parse(rec.Header().Get("Location"))
+		assert.NotEmpty(t, loc.Query().Get("code"))
+	})
+}
+
+func TestAuthorizeRejectsNonGetPost(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodDelete, "/authorize", nil)
+	srv.AuthorizeHandler(oauth2.AuthorizeConfig{}, approve).ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusMethodNotAllowed, rec.Code)
+}
+
+func TestAuthorizeConsentNarrowsScope(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	q := authorizeQuery()
+	q.Set("scope", "read write")
+
+	// The consent grants only "read" of the requested "read write".
+	rec := runAuthorize(srv, q,
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return &oauth2.Consent{Approved: true, Subject: "alice", Scope: "read"}, nil
+		})
+	require.Equal(t, http.StatusFound, rec.Code)
+	assert.NotEmpty(t, mustLocation(t, rec).Query().Get("code"))
+
+	// Broadening beyond the request is refused.
+	rec = runAuthorize(srv, authorizeQuery(),
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return &oauth2.Consent{Approved: true, Subject: "alice", Scope: "read write"}, nil
+		})
+	require.Equal(t, http.StatusFound, rec.Code)
+	assert.Equal(t, oauth2.CodeInvalidScope, mustLocation(t, rec).Query().Get("error"))
+}
+
+// TestAuthorizeCodeFlowEndToEnd runs the full flow: /authorize mints a code,
+// /token exchanges it (authorization_code + PKCE) for an access token.
+func TestAuthorizeCodeFlowEndToEnd(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	rec := runAuthorize(srv, authorizeQuery(), approve)
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	code := mustLocation(t, rec).Query().Get("code")
+	require.NotEmpty(t, code)
+
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {redirectURI},
+		"code_verifier": {pkceVerifier},
+	}
+
+	tokenRec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(tokenRec, formRequest("/oauth2/token", form, true))
+
+	require.Equal(t, http.StatusOK, tokenRec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(tokenRec.Body.Bytes(), &body))
+	assert.NotEmpty(t, body["access_token"])
+	assert.Equal(t, "Bearer", body["token_type"])
+
+	// The code is single-use: a replay is refused.
+	replay := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(replay, formRequest("/oauth2/token", form, true))
+	assert.Equal(t, http.StatusBadRequest, replay.Code)
+}
+
+func TestAuthorizeConsentError(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	rec := runAuthorize(srv, authorizeQuery(),
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return nil, assertAnError
+		})
+	require.Equal(t, http.StatusFound, rec.Code)
+	assert.Equal(t, oauth2.CodeServerError, mustLocation(t, rec).Query().Get("error"))
+}
+
+func TestAuthorizeOmittedRedirectURIUsesTheRegisteredOne(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	q := authorizeQuery()
+	q.Del("redirect_uri") // the client has exactly one registered URI
+
+	rec := runAuthorize(srv, q, approve)
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	loc := mustLocation(t, rec)
+	assert.Equal(t, "https://app.example/cb", loc.Scheme+"://"+loc.Host+loc.Path)
+	assert.NotEmpty(t, loc.Query().Get("code"))
+}
+
+func TestAuthorizeRejectsUnknownPKCEMethod(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20BCP)
+
+	q := authorizeQuery()
+	q.Set("code_challenge_method", "S512") // not S256 / plain
+
+	rec := runAuthorize(srv, q, approve)
+	require.Equal(t, http.StatusFound, rec.Code)
+	assert.Equal(t, oauth2.CodeInvalidRequest, mustLocation(t, rec).Query().Get("error"))
+}
+
+// assertAnError is a throwaway error for the consent-failure test.
+var assertAnError = errAuthorizeTest("consent backend down")
+
+type errAuthorizeTest string
+
+func (e errAuthorizeTest) Error() string { return string(e) }
+
+// --- implicit flow (legacy, opt-in) -------------------------------------
+
+func TestAuthorizeHandlerPanicsOnImplicitMisconfig(t *testing.T) {
+	t.Parallel()
+
+	t.Run("implicit on a non-Profile20 server", func(t *testing.T) {
+		t.Parallel()
+
+		bcp := newAuthorizeServer(t, oauth2.Profile20BCP)
+		assert.Panics(t, func() {
+			bcp.AuthorizeHandler(
+				oauth2.AuthorizeConfig{AllowImplicit: true, ImplicitTokens: implicitTokens()}, approve)
+		})
+	})
+
+	t.Run("implicit without a token generator", func(t *testing.T) {
+		t.Parallel()
+
+		p20 := newAuthorizeServer(t, oauth2.Profile20)
+		assert.Panics(t, func() {
+			p20.AuthorizeHandler(oauth2.AuthorizeConfig{AllowImplicit: true}, approve)
+		})
+	})
+}
+
+func TestAuthorizeImplicitHappyPath(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20)
+	cfg := oauth2.AuthorizeConfig{AllowImplicit: true, ImplicitTokens: implicitTokens()}
+
+	rec := runAuthorizeCfg(srv, cfg, implicitQuery(), approve)
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	loc := mustLocation(t, rec)
+	assert.Empty(t, loc.RawQuery, "the implicit response uses the fragment, not the query")
+
+	frag, err := url.ParseQuery(loc.Fragment)
+	require.NoError(t, err)
+	assert.NotEmpty(t, frag.Get("access_token"))
+	assert.Equal(t, "Bearer", frag.Get("token_type"))
+	assert.NotEmpty(t, frag.Get("expires_in"))
+	assert.Equal(t, "read", frag.Get("scope"))
+	assert.Equal(t, "impl-state", frag.Get("state"))
+}
+
+func TestAuthorizeImplicitRefusedWhenNotEnabled(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20)
+
+	// The default config leaves AllowImplicit false.
+	rec := runAuthorize(srv, implicitQuery(), approve)
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	loc := mustLocation(t, rec)
+	assert.Equal(t, oauth2.CodeUnsupportedResponseType, loc.Query().Get("error"))
+	assert.Empty(t, loc.Fragment)
+}
+
+func TestAuthorizeImplicitConsentDenied(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20)
+	cfg := oauth2.AuthorizeConfig{AllowImplicit: true, ImplicitTokens: implicitTokens()}
+
+	rec := runAuthorizeCfg(srv, cfg, implicitQuery(),
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return &oauth2.Consent{Approved: false}, nil
+		})
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	// Implicit errors also travel in the fragment (RFC 6749 §4.2.2.1).
+	frag, err := url.ParseQuery(mustLocation(t, rec).Fragment)
+	require.NoError(t, err)
+	assert.Equal(t, oauth2.CodeAccessDenied, frag.Get("error"))
+}
+
+func TestAuthorizeImplicitRejectsBroadenedScope(t *testing.T) {
+	t.Parallel()
+
+	srv := newAuthorizeServer(t, oauth2.Profile20)
+	cfg := oauth2.AuthorizeConfig{AllowImplicit: true, ImplicitTokens: implicitTokens()}
+
+	// implicitQuery requests "read"; the consent tries to grant "read write".
+	rec := runAuthorizeCfg(srv, cfg, implicitQuery(),
+		func(http.ResponseWriter, *http.Request, *oauth2.AuthorizeRequest) (*oauth2.Consent, error) {
+			return &oauth2.Consent{Approved: true, Subject: "alice", Scope: "read write"}, nil
+		})
+	require.Equal(t, http.StatusFound, rec.Code)
+
+	frag, err := url.ParseQuery(mustLocation(t, rec).Fragment)
+	require.NoError(t, err)
+	assert.Equal(t, oauth2.CodeInvalidScope, frag.Get("error"))
+}
+
+// mustLocation parses the Location header of a redirect response.
+func mustLocation(t *testing.T, rec *httptest.ResponseRecorder) *url.URL {
+	t.Helper()
+
+	loc, err := url.Parse(rec.Header().Get("Location"))
+	require.NoError(t, err)
+
+	return loc
+}
diff --git a/oauth2/client.go b/oauth2/client.go
new file mode 100644
index 0000000..ffed074
--- /dev/null
+++ b/oauth2/client.go
@@ -0,0 +1,115 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"crypto/subtle"
+)
+
+// ClientType describes whether an OAuth2 client is capable of safely keeping
+// a secret (confidential) or runs in an environment where it cannot
+// (public). Public clients MUST use PKCE per OAuth 2.0 BCP §2.1.1.
+type ClientType string
+
+const (
+	// ClientConfidential is a client that can keep a secret (server-side
+	// applications, machine-to-machine services).
+	ClientConfidential ClientType = "confidential"
+	// ClientPublic is a client that cannot keep a secret (browser apps,
+	// native mobile apps).
+	ClientPublic ClientType = "public"
+)
+
+// Client is the OAuth2 client record stored in the [ClientStore]. The
+// interface is intentionally small; implementations decide how to source the
+// data (in-memory, database, federated registry).
+type Client interface {
+	// ID is the public client identifier.
+	ID() string
+	// Type reports whether the client is confidential or public.
+	Type() ClientType
+	// RedirectURIs lists the redirect URIs registered by the client.
+	// Authorization code requests MUST match one of these exactly per
+	// RFC 6749 §3.1.2.3 / OAuth 2.0 BCP §2.1.4.
+	RedirectURIs() []string
+	// GrantTypes lists the grant types the client is allowed to use.
+	// Compared with strings.EqualFold; common values are
+	// "authorization_code", "refresh_token", "client_credentials".
+	GrantTypes() []string
+	// Scopes lists the maximum set of scopes the client may request. An
+	// empty list means "no scope restriction" and SHOULD be reserved for
+	// internal clients only.
+	Scopes() []string
+	// AuthMethods lists the client_authentication_method values supported
+	// for this client (see clientauth package). "none" implies a public
+	// client.
+	AuthMethods() []string
+}
+
+// SecretMatcher is the optional capability used by confidential client
+// authentication methods (client_secret_basic, client_secret_post) to
+// verify the registered secret without exposing it. Implementations MUST
+// use constant-time comparison (or a hashed-secret scheme).
+type SecretMatcher interface {
+	// SecretMatches returns true when secret matches the registered one.
+	// Implementations MUST use constant-time comparison.
+	SecretMatches(secret string) bool
+}
+
+// ClientStore loads client records by ID. Implementations are responsible
+// for caching policy; the Server invokes LoadClient once per request that
+// needs client authentication.
+type ClientStore interface {
+	LoadClient(ctx context.Context, id string) (Client, error)
+}
+
+// DefaultClient is a minimal in-memory [Client] implementation handy for
+// tests, examples, and small static deployments. Production deployments
+// SHOULD plug a database-backed Client implementation instead.
+type DefaultClient struct {
+	IDValue string
+	// Secret is the cleartext client secret. DefaultClient stores it
+	// verbatim for dev/test convenience; production deployments wrap a
+	// hashed-secret store and implement SecretMatches themselves.
+	Secret            string //nolint:gosec // dev/test convenience
+	TypeValue         ClientType
+	RedirectURIValues []string
+	GrantTypeValues   []string
+	ScopeValues       []string
+	AuthMethodValues  []string
+}
+
+// ID implements [Client].
+func (c *DefaultClient) ID() string { return c.IDValue }
+
+// Type implements [Client].
+func (c *DefaultClient) Type() ClientType { return c.TypeValue }
+
+// RedirectURIs implements [Client].
+func (c *DefaultClient) RedirectURIs() []string { return c.RedirectURIValues }
+
+// GrantTypes implements [Client].
+func (c *DefaultClient) GrantTypes() []string { return c.GrantTypeValues }
+
+// Scopes implements [Client].
+func (c *DefaultClient) Scopes() []string { return c.ScopeValues }
+
+// AuthMethods implements [Client].
+func (c *DefaultClient) AuthMethods() []string { return c.AuthMethodValues }
+
+// SecretMatches implements [SecretMatcher] using constant-time comparison.
+// The DefaultClient stores secrets in cleartext for development convenience;
+// production deployments SHOULD wrap a hashed-secret store and implement
+// SecretMatches themselves.
+func (c *DefaultClient) SecretMatches(secret string) bool {
+	return subtle.ConstantTimeCompare([]byte(c.Secret), []byte(secret)) == 1
+}
+
+// Compile-time interface checks.
+var (
+	_ Client        = (*DefaultClient)(nil)
+	_ SecretMatcher = (*DefaultClient)(nil)
+)
diff --git a/oauth2/clientauth/basic.go b/oauth2/clientauth/basic.go
new file mode 100644
index 0000000..3969fe4
--- /dev/null
+++ b/oauth2/clientauth/basic.go
@@ -0,0 +1,69 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package clientauth
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// NewBasic returns a client_secret_basic authenticator. The client_id and
+// client_secret are read from the HTTP Basic Authorization header per
+// RFC 6749 §2.3.1.
+func NewBasic() ClientAuthenticator { return basicAuth{} }
+
+type basicAuth struct{}
+
+// Method implements [ClientAuthenticator].
+func (basicAuth) Method() string { return "client_secret_basic" }
+
+// Match implements [ClientAuthenticator].
+func (basicAuth) Match(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+
+	header := r.Header.Get("Authorization")
+	if len(header) < 6 {
+		return false
+	}
+
+	// Case-insensitive prefix check.
+	return header[0] == 'B' || header[0] == 'b'
+}
+
+// Authenticate implements [ClientAuthenticator].
+func (basicAuth) Authenticate(ctx context.Context, r *http.Request, store oauth2.ClientStore) (oauth2.Client, error) {
+	id, secret, ok := decodeBasic(r.Header.Get("Authorization"))
+	if !ok {
+		return nil, oauth2.ErrInvalidClient.WithDescription("malformed Basic Authorization header")
+	}
+
+	client, err := store.LoadClient(ctx, id)
+	if err != nil {
+		return nil, errInvalid(err)
+	}
+
+	if client == nil {
+		return nil, oauth2.ErrInvalidClient.WithDescription("unknown client")
+	}
+
+	if !allowsMethod(client, "client_secret_basic") {
+		return nil, oauth2.ErrInvalidClient.WithDescription("method not allowed for client")
+	}
+
+	matcher, ok := client.(oauth2.SecretMatcher)
+	if !ok {
+		return nil, oauth2.ErrInvalidClient.WithDescription("client cannot verify secret")
+	}
+
+	if !matcher.SecretMatches(secret) {
+		return nil, errInvalid(errSecretMismatch)
+	}
+
+	return client, nil
+}
diff --git a/oauth2/clientauth/clientauth.go b/oauth2/clientauth/clientauth.go
new file mode 100644
index 0000000..caf17d2
--- /dev/null
+++ b/oauth2/clientauth/clientauth.go
@@ -0,0 +1,110 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package clientauth ships the client-authentication methods supported by
+// the OAuth2 server's /token endpoint per RFC 6749 §2.3 and OpenID Connect
+// Core §9.
+//
+// Methods shipped:
+//
+//   - client_secret_basic — RFC 6749 §2.3.1 (HTTP Basic)
+//   - client_secret_post  — RFC 6749 §2.3.1 (form parameters)
+//   - none                — public clients (PKCE-only authentication)
+//
+// Adding private_key_jwt requires the JWT module; it lives behind a small
+// adapter in the jwt sub-module so this package stays JOSE-free.
+package clientauth
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// ClientAuthenticator authenticates the OAuth2 client behind an HTTP
+// request. The server consults the configured methods in order and uses the
+// first one whose Match returns true.
+//
+// Authenticate MUST return:
+//   - (client, nil)                  on success.
+//   - (nil, oauth2.ErrInvalidClient) on credential mismatch.
+//   - (nil, other)                   on storage / unexpected errors.
+type ClientAuthenticator interface {
+	// Method returns the RFC 6749 / OIDC method identifier
+	// ("client_secret_basic", "client_secret_post", "none",
+	// "private_key_jwt"). Used by the server for OTel attribution and
+	// metadata publication.
+	Method() string
+
+	// Match reports whether r looks like a request intended for this
+	// method. Implementations MUST be fast (header inspection); they MUST
+	// NOT perform I/O.
+	Match(r *http.Request) bool
+
+	// Authenticate runs the method against r and returns the client on
+	// success or oauth2.ErrInvalidClient on failure.
+	Authenticate(ctx context.Context, r *http.Request, store oauth2.ClientStore) (oauth2.Client, error)
+}
+
+// Compile-time guard so future ClientAuthenticator additions never grow a
+// nil interface.
+var _ ClientAuthenticator = (*basicAuth)(nil)
+
+// allowsMethod reports whether the client is configured for the method.
+// An empty AuthMethods() list means "any method".
+func allowsMethod(c oauth2.Client, method string) bool {
+	all := c.AuthMethods()
+	if len(all) == 0 {
+		return true
+	}
+
+	for _, m := range all {
+		if strings.EqualFold(m, method) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// errInvalid is a small helper to wrap the storage / matcher error inside
+// oauth2.ErrInvalidClient while preserving the cause for telemetry.
+func errInvalid(cause error) error {
+	if cause == nil {
+		return oauth2.ErrInvalidClient
+	}
+
+	return oauth2.ErrInvalidClient.WithCause(cause)
+}
+
+// decodeBasic decodes a "Basic base64(id:secret)" Authorization header.
+// Returns (id, secret, true) on success, ("", "", false) on any malformed
+// input; the caller decides what error to surface.
+func decodeBasic(header string) (string, string, bool) {
+	const prefix = "Basic "
+	if len(header) < len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+		return "", "", false
+	}
+
+	raw, err := base64.StdEncoding.DecodeString(header[len(prefix):])
+	if err != nil {
+		return "", "", false
+	}
+
+	colon := strings.IndexByte(string(raw), ':')
+	if colon < 0 {
+		return "", "", false
+	}
+
+	return string(raw[:colon]), string(raw[colon+1:]), true
+}
+
+// errSecretMismatch is the typed error returned by secret-matcher
+// implementations on cleartext or hashed-secret mismatch. It is wrapped in
+// oauth2.ErrInvalidClient before being returned to the caller.
+var errSecretMismatch = errors.New("clientauth: secret mismatch")
diff --git a/oauth2/clientauth/clientauth_test.go b/oauth2/clientauth/clientauth_test.go
new file mode 100644
index 0000000..c7e6721
--- /dev/null
+++ b/oauth2/clientauth/clientauth_test.go
@@ -0,0 +1,379 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package clientauth
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// --- test doubles --------------------------------------------------------
+
+type fakeStore struct {
+	clients map[string]oauth2.Client
+	err     error
+}
+
+func (s fakeStore) LoadClient(_ context.Context, id string) (oauth2.Client, error) {
+	if s.err != nil {
+		return nil, s.err
+	}
+
+	return s.clients[id], nil
+}
+
+// noMatcherClient implements oauth2.Client but NOT oauth2.SecretMatcher.
+type noMatcherClient struct {
+	id      string
+	typ     oauth2.ClientType
+	methods []string
+}
+
+func (c noMatcherClient) ID() string             { return c.id }
+func (c noMatcherClient) Type() oauth2.ClientType { return c.typ }
+func (c noMatcherClient) RedirectURIs() []string  { return nil }
+func (c noMatcherClient) GrantTypes() []string    { return nil }
+func (c noMatcherClient) Scopes() []string        { return nil }
+func (c noMatcherClient) AuthMethods() []string   { return c.methods }
+
+func confidentialClient(methods ...string) *oauth2.DefaultClient {
+	return &oauth2.DefaultClient{
+		IDValue:          "c1",
+		Secret:           "s3cr3t",
+		TypeValue:        oauth2.ClientConfidential,
+		AuthMethodValues: methods,
+	}
+}
+
+func basicHeader(id, secret string) string {
+	return "Basic " + base64.StdEncoding.EncodeToString([]byte(id+":"+secret))
+}
+
+// assertInvalidClient asserts err carries the invalid_client OAuth2 code.
+// The authenticators return WithDescription / WithCause copies of the
+// sentinel, so the stable check is the embedded code, not pointer identity.
+func assertInvalidClient(t *testing.T, err error) {
+	t.Helper()
+
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidClient, oauth2.IsCode(err))
+}
+
+func postReq(form url.Values) *http.Request {
+	r := httptest.NewRequest(http.MethodPost, "/oauth2/token", strings.NewReader(form.Encode()))
+	r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	return r
+}
+
+// --- helpers -------------------------------------------------------------
+
+func TestDecodeBasic(t *testing.T) {
+	t.Parallel()
+
+	id, secret, ok := decodeBasic(basicHeader("alice", "pw:with:colons"))
+	require.True(t, ok)
+	assert.Equal(t, "alice", id)
+	assert.Equal(t, "pw:with:colons", secret)
+
+	for _, bad := range []string{
+		"",
+		"Bearer xyz",
+		"Basic !!!not-base64!!!",
+		"Basic " + base64.StdEncoding.EncodeToString([]byte("no-colon")),
+	} {
+		_, _, ok := decodeBasic(bad)
+		assert.False(t, ok, bad)
+	}
+}
+
+func TestAllowsMethod(t *testing.T) {
+	t.Parallel()
+
+	// Empty AuthMethods means "any method".
+	assert.True(t, allowsMethod(confidentialClient(), "client_secret_basic"))
+	// Listed method matches case-insensitively.
+	assert.True(t, allowsMethod(confidentialClient("Client_Secret_Basic"), "client_secret_basic"))
+	// Unlisted method is refused.
+	assert.False(t, allowsMethod(confidentialClient("none"), "client_secret_basic"))
+}
+
+func TestErrInvalid(t *testing.T) {
+	t.Parallel()
+
+	// A nil cause returns the bare sentinel.
+	assert.ErrorIs(t, errInvalid(nil), oauth2.ErrInvalidClient)
+
+	// A non-nil cause returns an invalid_client error wrapping the cause.
+	cause := errors.New("db down")
+	got := errInvalid(cause)
+	assert.Equal(t, oauth2.CodeInvalidClient, oauth2.IsCode(got))
+	assert.ErrorIs(t, got, cause)
+}
+
+// --- client_secret_basic -------------------------------------------------
+
+func TestBasicMethodAndMatch(t *testing.T) {
+	t.Parallel()
+
+	b := NewBasic()
+	assert.Equal(t, "client_secret_basic", b.Method())
+
+	assert.False(t, b.Match(nil))
+	assert.False(t, b.Match(httptest.NewRequest(http.MethodPost, "/", nil)))
+
+	withBasic := httptest.NewRequest(http.MethodPost, "/", nil)
+	withBasic.Header.Set("Authorization", basicHeader("c1", "s3cr3t"))
+	assert.True(t, b.Match(withBasic))
+}
+
+func TestBasicAuthenticate(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	store := fakeStore{clients: map[string]oauth2.Client{"c1": confidentialClient()}}
+
+	req := func(header string) *http.Request {
+		r := httptest.NewRequest(http.MethodPost, "/", nil)
+		if header != "" {
+			r.Header.Set("Authorization", header)
+		}
+
+		return r
+	}
+
+	t.Run("success", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := NewBasic().Authenticate(ctx, req(basicHeader("c1", "s3cr3t")), store)
+		require.NoError(t, err)
+		assert.Equal(t, "c1", c.ID())
+	})
+
+	t.Run("malformed header", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewBasic().Authenticate(ctx, req("Basic not-base64!"), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("unknown client", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewBasic().Authenticate(ctx, req(basicHeader("ghost", "x")), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("store error", func(t *testing.T) {
+		t.Parallel()
+
+		boom := fakeStore{err: errors.New("db down")}
+		_, err := NewBasic().Authenticate(ctx, req(basicHeader("c1", "s3cr3t")), boom)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("method not allowed", func(t *testing.T) {
+		t.Parallel()
+
+		only := fakeStore{clients: map[string]oauth2.Client{"c1": confidentialClient("none")}}
+		_, err := NewBasic().Authenticate(ctx, req(basicHeader("c1", "s3cr3t")), only)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("client cannot verify secret", func(t *testing.T) {
+		t.Parallel()
+
+		noMatcher := fakeStore{clients: map[string]oauth2.Client{
+			"c1": noMatcherClient{id: "c1", typ: oauth2.ClientConfidential},
+		}}
+		_, err := NewBasic().Authenticate(ctx, req(basicHeader("c1", "s3cr3t")), noMatcher)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("secret mismatch", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewBasic().Authenticate(ctx, req(basicHeader("c1", "wrong")), store)
+		assertInvalidClient(t, err)
+	})
+}
+
+// --- client_secret_post --------------------------------------------------
+
+func TestPostMethodAndMatch(t *testing.T) {
+	t.Parallel()
+
+	p := NewPost()
+	assert.Equal(t, "client_secret_post", p.Method())
+
+	assert.False(t, p.Match(nil))
+
+	withForm := postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s"}})
+	assert.True(t, p.Match(withForm))
+
+	// An Authorization header makes post yield to basic.
+	withHeader := postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s"}})
+	withHeader.Header.Set("Authorization", "Basic xyz")
+	assert.False(t, p.Match(withHeader))
+
+	assert.False(t, p.Match(postReq(url.Values{"client_id": {"c1"}})))
+}
+
+func TestPostAuthenticate(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	store := fakeStore{clients: map[string]oauth2.Client{"c1": confidentialClient()}}
+
+	t.Run("success", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s3cr3t"}}), store)
+		require.NoError(t, err)
+		assert.Equal(t, "c1", c.ID())
+	})
+
+	t.Run("missing credentials", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewPost().Authenticate(ctx, postReq(url.Values{}), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("unknown client", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"ghost"}, "client_secret": {"x"}}), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("store error", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s3cr3t"}}),
+			fakeStore{err: errors.New("db down")})
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("method not allowed", func(t *testing.T) {
+		t.Parallel()
+
+		only := fakeStore{clients: map[string]oauth2.Client{"c1": confidentialClient("none")}}
+		_, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s3cr3t"}}), only)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("client cannot verify secret", func(t *testing.T) {
+		t.Parallel()
+
+		noMatcher := fakeStore{clients: map[string]oauth2.Client{
+			"c1": noMatcherClient{id: "c1", typ: oauth2.ClientConfidential},
+		}}
+		_, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"c1"}, "client_secret": {"s3cr3t"}}), noMatcher)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("secret mismatch", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewPost().Authenticate(ctx,
+			postReq(url.Values{"client_id": {"c1"}, "client_secret": {"wrong"}}), store)
+		assertInvalidClient(t, err)
+	})
+}
+
+// --- none ----------------------------------------------------------------
+
+func TestNoneMethodAndMatch(t *testing.T) {
+	t.Parallel()
+
+	n := NewNone()
+	assert.Equal(t, "none", n.Method())
+
+	assert.False(t, n.Match(nil))
+	assert.True(t, n.Match(postReq(url.Values{"client_id": {"pub"}})))
+	// A secret present means this is a post request, not none.
+	assert.False(t, n.Match(postReq(url.Values{"client_id": {"pub"}, "client_secret": {"s"}})))
+	// An Authorization header makes none yield.
+	withHeader := postReq(url.Values{"client_id": {"pub"}})
+	withHeader.Header.Set("Authorization", "Basic xyz")
+	assert.False(t, n.Match(withHeader))
+}
+
+func TestNoneAuthenticate(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	publicClient := &oauth2.DefaultClient{IDValue: "pub", TypeValue: oauth2.ClientPublic}
+	store := fakeStore{clients: map[string]oauth2.Client{"pub": publicClient}}
+
+	t.Run("success for a public client", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := NewNone().Authenticate(ctx, postReq(url.Values{"client_id": {"pub"}}), store)
+		require.NoError(t, err)
+		assert.Equal(t, "pub", c.ID())
+	})
+
+	t.Run("missing client_id", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewNone().Authenticate(ctx, postReq(url.Values{}), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("unknown client", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewNone().Authenticate(ctx, postReq(url.Values{"client_id": {"ghost"}}), store)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("store error", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := NewNone().Authenticate(ctx, postReq(url.Values{"client_id": {"pub"}}),
+			fakeStore{err: errors.New("db down")})
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("confidential client refused", func(t *testing.T) {
+		t.Parallel()
+
+		conf := fakeStore{clients: map[string]oauth2.Client{
+			"pub": &oauth2.DefaultClient{IDValue: "pub", TypeValue: oauth2.ClientConfidential},
+		}}
+		_, err := NewNone().Authenticate(ctx, postReq(url.Values{"client_id": {"pub"}}), conf)
+		assertInvalidClient(t, err)
+	})
+
+	t.Run("method not allowed", func(t *testing.T) {
+		t.Parallel()
+
+		only := fakeStore{clients: map[string]oauth2.Client{
+			"pub": &oauth2.DefaultClient{
+				IDValue: "pub", TypeValue: oauth2.ClientPublic,
+				AuthMethodValues: []string{"client_secret_basic"},
+			},
+		}}
+		_, err := NewNone().Authenticate(ctx, postReq(url.Values{"client_id": {"pub"}}), only)
+		assertInvalidClient(t, err)
+	})
+}
diff --git a/oauth2/clientauth/none.go b/oauth2/clientauth/none.go
new file mode 100644
index 0000000..a3701ee
--- /dev/null
+++ b/oauth2/clientauth/none.go
@@ -0,0 +1,67 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package clientauth
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// NewNone returns the "none" client-authentication method (OpenID Connect
+// Core §9). The client identifies itself via the client_id form parameter
+// but presents no secret; authentication relies on PKCE alone. This method
+// is meant for public clients (browser apps, native mobile apps).
+//
+// The server MUST reject confidential clients trying to use "none"; the
+// grant handler enforces PKCE separately.
+func NewNone() ClientAuthenticator { return noneAuth{} }
+
+type noneAuth struct{}
+
+// Method implements [ClientAuthenticator].
+func (noneAuth) Method() string { return "none" }
+
+// Match implements [ClientAuthenticator]. A bare client_id in the form
+// without a secret is the signal.
+func (noneAuth) Match(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+
+	if r.Header.Get("Authorization") != "" {
+		return false
+	}
+
+	return r.PostFormValue("client_id") != "" && r.PostFormValue("client_secret") == ""
+}
+
+// Authenticate implements [ClientAuthenticator].
+func (noneAuth) Authenticate(ctx context.Context, r *http.Request, store oauth2.ClientStore) (oauth2.Client, error) {
+	id := r.PostFormValue("client_id")
+	if id == "" {
+		return nil, oauth2.ErrInvalidClient.WithDescription("missing client_id")
+	}
+
+	client, err := store.LoadClient(ctx, id)
+	if err != nil {
+		return nil, errInvalid(err)
+	}
+
+	if client == nil {
+		return nil, oauth2.ErrInvalidClient.WithDescription("unknown client")
+	}
+
+	if client.Type() != oauth2.ClientPublic {
+		return nil, oauth2.ErrInvalidClient.WithDescription(`"none" reserved to public clients`)
+	}
+
+	if !allowsMethod(client, "none") {
+		return nil, oauth2.ErrInvalidClient.WithDescription("method not allowed for client")
+	}
+
+	return client, nil
+}
diff --git a/oauth2/clientauth/post.go b/oauth2/clientauth/post.go
new file mode 100644
index 0000000..224d8f6
--- /dev/null
+++ b/oauth2/clientauth/post.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package clientauth
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// NewPost returns a client_secret_post authenticator. The client_id and
+// client_secret are read from the form body per RFC 6749 §2.3.1
+// (the variant some legacy clients use instead of HTTP Basic).
+//
+// The form MUST have been parsed by the time Authenticate runs; the
+// OAuth2 server calls ParseForm before consulting any authenticator.
+func NewPost() ClientAuthenticator { return postAuth{} }
+
+type postAuth struct{}
+
+// Method implements [ClientAuthenticator].
+func (postAuth) Method() string { return "client_secret_post" }
+
+// Match implements [ClientAuthenticator]. We claim the request when
+// client_id+client_secret are present in the form and no Authorization
+// header is set; this lets Basic take precedence when both are supplied.
+func (postAuth) Match(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+
+	if r.Header.Get("Authorization") != "" {
+		return false
+	}
+
+	return r.PostFormValue("client_id") != "" && r.PostFormValue("client_secret") != ""
+}
+
+// Authenticate implements [ClientAuthenticator].
+func (postAuth) Authenticate(ctx context.Context, r *http.Request, store oauth2.ClientStore) (oauth2.Client, error) {
+	id := r.PostFormValue("client_id")
+	secret := r.PostFormValue("client_secret")
+
+	if id == "" || secret == "" {
+		return nil, oauth2.ErrInvalidClient.WithDescription("missing client_id or client_secret")
+	}
+
+	client, err := store.LoadClient(ctx, id)
+	if err != nil {
+		return nil, errInvalid(err)
+	}
+
+	if client == nil {
+		return nil, oauth2.ErrInvalidClient.WithDescription("unknown client")
+	}
+
+	if !allowsMethod(client, "client_secret_post") {
+		return nil, oauth2.ErrInvalidClient.WithDescription("method not allowed for client")
+	}
+
+	matcher, ok := client.(oauth2.SecretMatcher)
+	if !ok {
+		return nil, oauth2.ErrInvalidClient.WithDescription("client cannot verify secret")
+	}
+
+	if !matcher.SecretMatches(secret) {
+		return nil, errInvalid(errSecretMismatch)
+	}
+
+	return client, nil
+}
diff --git a/oauth2/doc.go b/oauth2/doc.go
new file mode 100644
index 0000000..4a58a4d
--- /dev/null
+++ b/oauth2/doc.go
@@ -0,0 +1,29 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package oauth2 is a modular OAuth2 authorization server.
+//
+// The server is organized by responsibility:
+//   - Server aggregates Profile, Storage, Grants, ClientAuth, IssuerResolver.
+//   - Profile selects the security baseline (OAuth2.0, OAuth2.0-BCP,
+//     OAuth2.1-draft). BCP is the recommended default and is enforced at
+//     runtime on the grants (PKCE required, "plain" PKCE refused).
+//   - Endpoints: AuthorizeHandler runs the RFC 6749 §3.1 authorization
+//     endpoint (authorization_code, and the opt-in legacy implicit flow);
+//     TokenHandler, RevokeHandler, IntrospectHandler and MetadataHandler
+//     cover the remaining RFC endpoints.
+//   - Grants implement authorization_code (with PKCE), client_credentials
+//     and refresh_token. The legacy password grant (grant.NewLegacyPassword)
+//     is opt-in and refused outside Profile20.
+//   - Tokens are opaque by default; refresh tokens and authorization codes
+//     are stored hashed. JWT access tokens are available via an adapter to
+//     the jwt sub-module (no hard dependency from oauth2 to jwt).
+//   - Stores expose atomic ConsumeAuthorizationCode and RotateRefreshToken
+//     to guarantee single-use semantics and reuse-detection.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - go.opentelemetry.io/otel
+//   - stdlib only
+package oauth2
diff --git a/oauth2/errors.go b/oauth2/errors.go
new file mode 100644
index 0000000..3e917f8
--- /dev/null
+++ b/oauth2/errors.go
@@ -0,0 +1,141 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Error is the OAuth2 error envelope (RFC 6749 §5.2). It carries the
+// machine-readable code, an optional human description, and an optional URI
+// pointing to extended documentation. Implementations of [Server] return
+// values of this type so the HTTP layer can serialize them as JSON.
+type Error struct {
+	// Code is the RFC 6749 §5.2 error identifier ("invalid_request",
+	// "invalid_client", ...).
+	Code string
+	// Description is the optional ASCII description displayed to the
+	// client.
+	Description string
+	// URI is the optional documentation URL.
+	URI string
+	// Cause is the wrapped Go error for server-side inspection. Never
+	// surfaced to the client.
+	Cause error
+}
+
+// Error implements the error interface.
+func (e *Error) Error() string {
+	if e.Description != "" {
+		return fmt.Sprintf("oauth2: %s: %s", e.Code, e.Description)
+	}
+
+	return "oauth2: " + e.Code
+}
+
+// Unwrap exposes the embedded cause to errors.Is / errors.As.
+func (e *Error) Unwrap() error { return e.Cause }
+
+// HTTPStatus returns the canonical HTTP status code for this error per
+// RFC 6749 §5.2 / RFC 7009 / RFC 7662.
+func (e *Error) HTTPStatus() int {
+	switch e.Code {
+	case CodeInvalidClient:
+		return 401
+	case CodeAccessDenied:
+		return 403
+	case CodeServerError:
+		return 500
+	case CodeTemporarilyUnavailable:
+		return 503
+	default:
+		return 400
+	}
+}
+
+// RFC 6749 §5.2 error codes plus the RFC 8693 / 7591 extensions used by
+// the modular OAuth2 server.
+const (
+	CodeInvalidRequest          = "invalid_request"
+	CodeInvalidClient           = "invalid_client"
+	CodeInvalidGrant            = "invalid_grant"
+	CodeInvalidScope            = "invalid_scope"
+	CodeUnauthorizedClient      = "unauthorized_client"
+	CodeUnsupportedGrantType    = "unsupported_grant_type"
+	CodeUnsupportedResponseType = "unsupported_response_type"
+	CodeAccessDenied            = "access_denied"
+	CodeServerError             = "server_error"
+	CodeTemporarilyUnavailable  = "temporarily_unavailable"
+)
+
+// Sentinel constructors returning *Error values. They wrap the core security
+// sentinels so HTTP / gRPC error mappers route them to the right status.
+var (
+	// ErrInvalidRequest -> 400 invalid_request.
+	ErrInvalidRequest = newCoded(CodeInvalidRequest, "the request is malformed", security.ErrInvalidCredentials)
+	// ErrInvalidClient -> 401 invalid_client.
+	ErrInvalidClient = newCoded(CodeInvalidClient, "client authentication failed", security.ErrClientSecretMismatch)
+	// ErrInvalidGrant -> 400 invalid_grant.
+	ErrInvalidGrant = newCoded(CodeInvalidGrant, "the grant is invalid or expired", security.ErrInvalidCredentials)
+	// ErrInvalidScope -> 400 invalid_scope.
+	ErrInvalidScope = newCoded(CodeInvalidScope, "the requested scope is invalid", security.ErrInvalidCredentials)
+	// ErrUnauthorizedClient -> 400 unauthorized_client.
+	ErrUnauthorizedClient = newCoded(CodeUnauthorizedClient, "the client is not authorized to use this grant", security.ErrInvalidCredentials)
+	// ErrUnsupportedGrantType -> 400 unsupported_grant_type.
+	ErrUnsupportedGrantType = newCoded(CodeUnsupportedGrantType, "the grant type is unsupported", security.ErrUnsupportedCredential)
+	// ErrUnsupportedResponseType -> 400 unsupported_response_type.
+	ErrUnsupportedResponseType = newCoded(CodeUnsupportedResponseType, "the response type is unsupported", security.ErrUnsupportedCredential)
+	// ErrAccessDenied -> 403 access_denied.
+	ErrAccessDenied = newCoded(CodeAccessDenied, "the resource owner denied the request", security.ErrAccessDenied)
+	// ErrServerError -> 500 server_error.
+	ErrServerError = newCoded(CodeServerError, "internal server error", nil)
+	// ErrCodeAlreadyUsed signals authorization-code reuse — surfaced as
+	// invalid_grant per RFC 6749 §4.1.2.
+	ErrCodeAlreadyUsed = newCoded(CodeInvalidGrant, "authorization code already consumed", security.ErrInvalidCredentials)
+	// ErrRefreshTokenReused signals refresh-token reuse — surfaced as
+	// invalid_grant per OAuth 2.0 BCP §8.10.3. Storage implementations
+	// MUST also revoke the entire token family when this occurs.
+	ErrRefreshTokenReused = newCoded(CodeInvalidGrant, "refresh token reused — family revoked", security.ErrInvalidCredentials)
+)
+
+// newCoded constructs an Error sentinel. The cause chain reaches the supplied
+// security sentinel via Unwrap so errors.Is keeps working transparently.
+func newCoded(code, desc string, cause error) *Error {
+	return &Error{Code: code, Description: desc, Cause: cause}
+}
+
+// IsCode returns the OAuth2 error code embedded in err, or "" when err is
+// not an [*Error] in its chain.
+func IsCode(err error) string {
+	var e *Error
+	if errors.As(err, &e) {
+		return e.Code
+	}
+
+	return ""
+}
+
+// WithDescription returns a copy of e with the human-readable description
+// replaced. Sentinels stay immutable so concurrent reads remain safe.
+func (e *Error) WithDescription(desc string) *Error {
+	cp := *e
+	cp.Description = desc
+
+	return &cp
+}
+
+// WithCause returns a copy of e with the wrapped cause set to err. The
+// resulting Error wraps both the original security sentinel (via the chain)
+// and the new cause, so errors.Is / errors.As keeps working in both
+// directions.
+func (e *Error) WithCause(err error) *Error {
+	cp := *e
+	cp.Cause = errors.Join(e.Cause, err)
+
+	return &cp
+}
diff --git a/oauth2/go.mod b/oauth2/go.mod
new file mode 100644
index 0000000..02261c4
--- /dev/null
+++ b/oauth2/go.mod
@@ -0,0 +1,23 @@
+module github.com/hyperscale-stack/security/oauth2
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../
diff --git a/oauth2/go.sum b/oauth2/go.sum
new file mode 100644
index 0000000..56bdaa2
--- /dev/null
+++ b/oauth2/go.sum
@@ -0,0 +1,40 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/oauth2/grant/authorization_code.go b/oauth2/grant/authorization_code.go
new file mode 100644
index 0000000..a1b3600
--- /dev/null
+++ b/oauth2/grant/authorization_code.go
@@ -0,0 +1,140 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+	"slices"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+)
+
+// AuthorizationCode implements RFC 6749 §4.1.3 with the RFC 7636 PKCE
+// extension. The flow:
+//
+//  1. Pop the code from storage atomically (single-use enforcement).
+//  2. Re-bind client (code.ClientID MUST match the authenticated client).
+//  3. Re-bind redirect_uri (RFC 6749 §4.1.3 paragraph 7).
+//  4. Verify PKCE when present / required.
+//  5. Generate access token (+ optional refresh token).
+//  6. Persist both and return the pair.
+type AuthorizationCode struct {
+	cfg Config
+}
+
+// NewAuthorizationCode constructs the handler.
+func NewAuthorizationCode(cfg Config) *AuthorizationCode {
+	if cfg.Storage == nil || cfg.AccessTokens == nil {
+		panic("oauth2/grant: NewAuthorizationCode requires Storage and AccessTokens")
+	}
+
+	return &AuthorizationCode{cfg: cfg}
+}
+
+// Type implements [Grant].
+func (g *AuthorizationCode) Type() string { return "authorization_code" }
+
+// Handle implements [Grant].
+func (g *AuthorizationCode) Handle(ctx context.Context, req Request) (*Response, error) {
+	rawCode := req.Form.Get("code")
+	if rawCode == "" {
+		return nil, oauth2.ErrInvalidRequest.WithDescription("missing code")
+	}
+
+	hash := oauth2.HashToken(nil, rawCode) // pepper-free: code only lives in storage briefly
+
+	code, err := g.cfg.Storage.ConsumeAuthorizationCode(ctx, hash)
+	if err != nil {
+		return nil, err //nolint:wrapcheck // oauth2.* sentinels pass through
+	}
+
+	if code.IsExpired(req.Now) {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("authorization code expired")
+	}
+
+	if code.ClientID != req.Client.ID() {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("code issued for a different client")
+	}
+
+	if redirect := req.Form.Get("redirect_uri"); redirect != code.RedirectURI {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("redirect_uri mismatch")
+	}
+
+	if err := g.verifyPKCE(req, code); err != nil {
+		return nil, err
+	}
+
+	if !grantTypeAllowed(req.Client, "authorization_code") {
+		return nil, oauth2.ErrUnauthorizedClient.WithDescription("client cannot use authorization_code")
+	}
+
+	return issueTokenPair(ctx, g.cfg, req, code.Subject, code.Scope)
+}
+
+func (g *AuthorizationCode) verifyPKCE(req Request, code *oauth2.AuthorizationCode) error {
+	verifier := req.Form.Get("code_verifier")
+
+	// PKCE is required when the grant is explicitly configured for it OR
+	// the active profile mandates it (BCP / OAuth 2.1). The profile can
+	// only tighten this, never relax it.
+	pkceRequired := g.cfg.RequirePKCE || req.Profile.RequiresPKCE()
+
+	if code.CodeChallenge == "" {
+		if pkceRequired {
+			return oauth2.ErrInvalidGrant.WithDescription("PKCE required")
+		}
+
+		return nil
+	}
+
+	if verifier == "" {
+		return oauth2.ErrInvalidGrant.WithDescription("missing code_verifier")
+	}
+
+	method := pkce.Method(code.CodeChallengeMethod)
+	if method == "" {
+		method = pkce.MethodPlain
+	}
+
+	// The "plain" transformation is accepted only when the profile tolerates
+	// it (Profile20). BCP and OAuth 2.1 mandate S256.
+	if method == pkce.MethodPlain && !req.Profile.AllowsPKCEPlain() {
+		return oauth2.ErrInvalidGrant.WithDescription(`PKCE method "plain" is refused by the active profile`)
+	}
+
+	if !pkce.Verify(method, verifier, code.CodeChallenge) {
+		return oauth2.ErrInvalidGrant.WithDescription("PKCE verification failed")
+	}
+
+	return nil
+}
+
+// grantTypeAllowed reports whether the client is configured for grant.
+// An empty GrantTypes() list means "any grant" — common in single-tenant
+// deployments where the client list is curated.
+func grantTypeAllowed(c oauth2.Client, grant string) bool {
+	all := c.GrantTypes()
+	if len(all) == 0 {
+		return true
+	}
+
+	return slices.Contains(all, grant)
+}
+
+// newFamilyID returns a 16-byte random identifier used to group every
+// access / refresh token issued from the same original authorization.
+// base64url -> 22 chars without padding.
+func newFamilyID() (string, error) {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("read random: %w", err)
+	}
+
+	return base64.RawURLEncoding.EncodeToString(b), nil
+}
diff --git a/oauth2/grant/client_credentials.go b/oauth2/grant/client_credentials.go
new file mode 100644
index 0000000..39c1dde
--- /dev/null
+++ b/oauth2/grant/client_credentials.go
@@ -0,0 +1,103 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant
+
+import (
+	"context"
+	"slices"
+	"strings"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// ClientCredentials implements RFC 6749 §4.4: the client authenticates
+// itself and obtains an access token bound to its own identity (no
+// resource-owner concept).
+//
+// Refresh tokens MUST NOT be issued for this grant (RFC 6749 §4.4.3),
+// so the handler ignores cfg.RefreshTokens even when set.
+type ClientCredentials struct {
+	cfg Config
+}
+
+// NewClientCredentials constructs the handler.
+func NewClientCredentials(cfg Config) *ClientCredentials {
+	if cfg.Storage == nil || cfg.AccessTokens == nil {
+		panic("oauth2/grant: NewClientCredentials requires Storage and AccessTokens")
+	}
+
+	return &ClientCredentials{cfg: cfg}
+}
+
+// Type implements [Grant].
+func (g *ClientCredentials) Type() string { return "client_credentials" }
+
+// Handle implements [Grant]. The client has already been authenticated by
+// the time the server hands the request to the grant.
+func (g *ClientCredentials) Handle(ctx context.Context, req Request) (*Response, error) {
+	if !grantTypeAllowed(req.Client, "client_credentials") {
+		return nil, oauth2.ErrUnauthorizedClient.WithDescription("client cannot use client_credentials")
+	}
+
+	scope, err := narrowScopes(req.Form.Get("scope"), req.Client.Scopes())
+	if err != nil {
+		return nil, err
+	}
+
+	expires := req.Now.Add(g.cfg.AccessTTL)
+
+	atRaw, atHash, err := g.cfg.AccessTokens.Generate(ctx, token.AccessTokenClaims{
+		Issuer:    req.Issuer,
+		Subject:   req.Client.ID(), // sub = client id for machine-to-machine flows
+		Audience:  req.Audience,
+		ClientID:  req.Client.ID(),
+		Scope:     scope,
+		IssuedAt:  req.Now,
+		ExpiresAt: expires,
+	})
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	access := &oauth2.AccessToken{
+		Token: atRaw, TokenHash: atHash, ClientID: req.Client.ID(), Subject: req.Client.ID(),
+		Scope: scope, IssuedAt: req.Now, ExpiresAt: expires, Audience: req.Audience,
+	}
+	if err := g.cfg.Storage.SaveAccessToken(ctx, access); err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	return &Response{
+		Pair:      oauth2.TokenPair{Access: *access},
+		Scope:     scope,
+		TokenType: oauth2.TokenTypeBearer,
+	}, nil
+}
+
+// narrowScopes filters requested against the client's allowed scopes. When
+// the client has no allowed list, requested is accepted as-is. When
+// requested is empty and the client has at least one scope, the first one
+// is returned as the default — matches the common UX of "no scope ->
+// default scope".
+func narrowScopes(requested string, allowed []string) (string, error) {
+	requestedFields := strings.Fields(requested)
+
+	if len(allowed) == 0 {
+		return requested, nil
+	}
+
+	if len(requestedFields) == 0 {
+		return allowed[0], nil
+	}
+
+	for _, s := range requestedFields {
+		if !slices.Contains(allowed, s) {
+			return "", oauth2.ErrInvalidScope.WithDescription("scope " + s + " not allowed for client")
+		}
+	}
+
+	return strings.Join(requestedFields, " "), nil
+}
diff --git a/oauth2/grant/grant.go b/oauth2/grant/grant.go
new file mode 100644
index 0000000..8fa32ad
--- /dev/null
+++ b/oauth2/grant/grant.go
@@ -0,0 +1,56 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package grant ships the grant-type handlers consumed by the OAuth2
+// server's /token endpoint. Each handler satisfies [oauth2.Grant] and is
+// registered in the server's grant table at construction time.
+//
+// Three grants are shipped:
+//
+//   - authorization_code (with PKCE; PKCE is mandatory in
+//     [oauth2.Profile20BCP] and [oauth2.Profile21Draft])
+//   - client_credentials
+//   - refresh_token (with rotation + reuse detection)
+//
+// Legacy grants (password, implicit) live behind explicit opt-in helpers
+// and are refused outside [oauth2.Profile20].
+package grant
+
+import (
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// Config gathers the runtime knobs every grant needs.
+type Config struct {
+	// Storage is the persistence layer.
+	Storage oauth2.Storage
+	// AccessTokens issues access tokens (opaque or JWT).
+	AccessTokens token.AccessTokenGenerator
+	// RefreshTokens issues refresh tokens. Optional — when nil, the
+	// grant emits no refresh token.
+	RefreshTokens token.RefreshTokenGenerator
+	// AccessTTL is the access-token expiry window.
+	AccessTTL time.Duration
+	// RefreshTTL is the refresh-token expiry window. Honored when
+	// RefreshTokens is non-nil.
+	RefreshTTL time.Duration
+	// RequirePKCE forces PKCE on authorization_code; default in BCP/21
+	// profiles. The authorization_code grant honors this independently
+	// of public-vs-confidential client type.
+	RequirePKCE bool
+	// RotateRefreshTokens emits a fresh refresh token on every
+	// /token?grant_type=refresh_token call and marks the old one
+	// consumed; reuse triggers family revocation. Default true in BCP/21.
+	RotateRefreshTokens bool
+}
+
+// Request and Response are type aliases anchoring the contract in the
+// parent oauth2 package so handlers and the Server share one definition.
+type (
+	Request  = oauth2.GrantRequest
+	Response = oauth2.GrantResponse
+)
diff --git a/oauth2/grant/grant_more_test.go b/oauth2/grant/grant_more_test.go
new file mode 100644
index 0000000..0d61ab3
--- /dev/null
+++ b/oauth2/grant/grant_more_test.go
@@ -0,0 +1,409 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant_test
+
+import (
+	"context"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGrantTypes(t *testing.T) {
+	t.Parallel()
+
+	cfg := grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour}
+
+	assert.Equal(t, "authorization_code", grant.NewAuthorizationCode(cfg).Type())
+	assert.Equal(t, "client_credentials", grant.NewClientCredentials(cfg).Type())
+	assert.Equal(t, "refresh_token", grant.NewRefreshToken(cfg).Type())
+}
+
+func TestConstructorsPanicWithoutDeps(t *testing.T) {
+	t.Parallel()
+
+	bad := grant.Config{} // no Storage, no AccessTokens
+
+	assert.Panics(t, func() { grant.NewAuthorizationCode(bad) })
+	assert.Panics(t, func() { grant.NewClientCredentials(bad) })
+	assert.Panics(t, func() { grant.NewRefreshToken(bad) })
+}
+
+// --- authorization_code edge cases --------------------------------------
+
+func TestAuthorizationCodeMissingCode(t *testing.T) {
+	t.Parallel()
+
+	g, req := newAuthCodeReq(context.Background(), newStore(), true)
+	req.Form.Del("code")
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidRequest, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeExpired(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Now = time.Date(2026, 5, 20, 13, 0, 0, 0, time.UTC) // past the code's 12:10 expiry
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeClientMismatch(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Client = &oauth2.DefaultClient{IDValue: "another-client", TypeValue: oauth2.ClientConfidential}
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeGrantTypeNotAllowed(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Client = &oauth2.DefaultClient{
+		IDValue:           clientID,
+		TypeValue:         oauth2.ClientConfidential,
+		RedirectURIValues: []string{redirectURI},
+		GrantTypeValues:   []string{"client_credentials"}, // not authorization_code
+	}
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeUnauthorizedClient, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeMissingVerifier(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Form.Del("code_verifier") // the code carries a challenge but no verifier is sent
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+// plainPKCECode seeds a code whose challenge method is empty (the grant
+// defaults to "plain", where the verifier equals the challenge verbatim)
+// and returns the matching /token form.
+func plainPKCECode(t *testing.T, store oauth2.Storage) url.Values {
+	t.Helper()
+
+	raw := "raw-plain-code"
+	require.NoError(t, store.SaveAuthorizationCode(context.Background(), &oauth2.AuthorizationCode{
+		Code: raw, CodeHash: oauth2.HashToken(nil, raw),
+		ClientID: clientID, Subject: subject, RedirectURI: redirectURI, Scope: "read:mail",
+		CodeChallenge: "shared-plain-secret", CodeChallengeMethod: "",
+		IssuedAt:  time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC),
+		ExpiresAt: time.Date(2026, 5, 20, 12, 10, 0, 0, time.UTC),
+	}))
+
+	form := url.Values{}
+	form.Set("code", raw)
+	form.Set("redirect_uri", redirectURI)
+	form.Set("code_verifier", "shared-plain-secret")
+
+	return form
+}
+
+func TestAuthorizationCodePlainPKCEAcceptedUnderProfile20(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	form := plainPKCECode(t, store)
+
+	g := grant.NewAuthorizationCode(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	resp, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: form, Profile: oauth2.Profile20,
+		Now: time.Date(2026, 5, 20, 12, 5, 0, 0, time.UTC),
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+}
+
+func TestAuthorizationCodePlainPKCERefusedUnderBCP(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	form := plainPKCECode(t, store)
+
+	g := grant.NewAuthorizationCode(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	// Profile20BCP (and 21Draft) mandate S256 — "plain" must be refused.
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: form, Profile: oauth2.Profile20BCP,
+		Now: time.Date(2026, 5, 20, 12, 5, 0, 0, time.UTC),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeProfileRequiresPKCE(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	ctx := context.Background()
+
+	// A code minted with no PKCE challenge at all.
+	raw := "raw-no-pkce-code"
+	require.NoError(t, store.SaveAuthorizationCode(ctx, &oauth2.AuthorizationCode{
+		Code: raw, CodeHash: oauth2.HashToken(nil, raw),
+		ClientID: clientID, Subject: subject, RedirectURI: redirectURI, Scope: "read:mail",
+		IssuedAt:  time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC),
+		ExpiresAt: time.Date(2026, 5, 20, 12, 10, 0, 0, time.UTC),
+	}))
+
+	// The grant itself does not force PKCE (RequirePKCE false), but the
+	// BCP profile does — the request must still be refused.
+	g := grant.NewAuthorizationCode(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("code", raw)
+	form.Set("redirect_uri", redirectURI)
+
+	_, err := g.Handle(ctx, grant.Request{
+		Client: newClient(), Form: form, Profile: oauth2.Profile20BCP,
+		Now: time.Date(2026, 5, 20, 12, 5, 0, 0, time.UTC),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeWithoutRefreshGenerator(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	ctx := context.Background()
+	_, req := newAuthCodeReq(ctx, store, true)
+
+	// A config with no RefreshTokens generator issues an access token only.
+	g := grant.NewAuthorizationCode(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	resp, err := g.Handle(ctx, req)
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+	assert.Nil(t, resp.Pair.Refresh, "no refresh token without a RefreshTokens generator")
+}
+
+// --- client_credentials edge cases --------------------------------------
+
+func TestClientCredentialsGrantTypeNotAllowed(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewClientCredentials(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	client := &oauth2.DefaultClient{
+		IDValue:         clientID,
+		TypeValue:       oauth2.ClientConfidential,
+		GrantTypeValues: []string{"refresh_token"}, // not client_credentials
+	}
+
+	_, err := g.Handle(context.Background(), grant.Request{Client: client, Form: url.Values{}, Now: time.Now()})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeUnauthorizedClient, oauth2.IsCode(err))
+}
+
+func TestClientCredentialsNoScopeRestriction(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewClientCredentials(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	// A client with no Scopes() list accepts any requested scope verbatim.
+	client := &oauth2.DefaultClient{IDValue: clientID, TypeValue: oauth2.ClientConfidential}
+	form := url.Values{}
+	form.Set("scope", "anything:goes")
+
+	resp, err := g.Handle(context.Background(), grant.Request{Client: client, Form: form, Now: time.Now()})
+	require.NoError(t, err)
+	assert.Equal(t, "anything:goes", resp.Scope)
+}
+
+func TestClientCredentialsDefaultsToFirstScope(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewClientCredentials(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	// No scope requested + a restricted client -> the first allowed scope.
+	resp, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: url.Values{}, Now: time.Now(),
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "read:mail", resp.Scope)
+}
+
+// --- refresh_token edge cases -------------------------------------------
+
+// seedRefresh stores a refresh token and returns its raw value.
+func seedRefresh(t *testing.T, store interface {
+	SaveRefreshToken(context.Context, *oauth2.RefreshToken) error
+}, raw, scope string, expiresAt time.Time) {
+	t.Helper()
+
+	require.NoError(t, store.SaveRefreshToken(context.Background(), &oauth2.RefreshToken{
+		Token: raw, TokenHash: oauth2.HashToken(nil, raw),
+		ClientID: clientID, Subject: subject, Scope: scope,
+		IssuedAt: time.Now().Add(-time.Hour), ExpiresAt: expiresAt, FamilyID: "fam-x",
+	}))
+}
+
+func TestRefreshTokenMissing(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: url.Values{}, Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidRequest, oauth2.IsCode(err))
+}
+
+func TestRefreshTokenUnknown(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "never-issued")
+
+	_, err := g.Handle(context.Background(), grant.Request{Client: newClient(), Form: form, Now: time.Now()})
+	require.Error(t, err)
+}
+
+func TestRefreshTokenExpired(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	seedRefresh(t, store, "expired-rt", "read:mail", time.Now().Add(-time.Minute))
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "expired-rt")
+
+	_, err := g.Handle(context.Background(), grant.Request{Client: newClient(), Form: form, Now: time.Now()})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestRefreshTokenClientMismatch(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	seedRefresh(t, store, "other-client-rt", "read:mail", time.Now().Add(time.Hour))
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "other-client-rt")
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: &oauth2.DefaultClient{IDValue: "intruder", TypeValue: oauth2.ClientConfidential},
+		Form:   form, Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestRefreshTokenNarrowsScope(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	seedRefresh(t, store, "narrow-rt", "read:mail write:mail", time.Now().Add(time.Hour))
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), RefreshTokens: newRefreshGen(),
+		AccessTTL: time.Hour, RefreshTTL: 24 * time.Hour, RotateRefreshTokens: true,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "narrow-rt")
+	form.Set("scope", "read:mail") // a subset of the original grant
+
+	resp, err := g.Handle(context.Background(), grant.Request{Client: newClient(), Form: form, Now: time.Now()})
+	require.NoError(t, err)
+	assert.Equal(t, "read:mail", resp.Scope)
+}
+
+func TestRefreshTokenRefusesBroadenedScope(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	seedRefresh(t, store, "broaden-rt", "read:mail", time.Now().Add(time.Hour))
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "broaden-rt")
+	form.Set("scope", "read:mail admin") // admin was not in the original grant
+
+	_, err := g.Handle(context.Background(), grant.Request{Client: newClient(), Form: form, Now: time.Now()})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidScope, oauth2.IsCode(err))
+}
+
+func TestRefreshTokenWithoutRotation(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	seedRefresh(t, store, "static-rt", "read:mail", time.Now().Add(time.Hour))
+
+	// RotateRefreshTokens defaults to false here: the grant issues a new
+	// access token but no replacement refresh token.
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), RefreshTokens: newRefreshGen(),
+		AccessTTL: time.Hour, RefreshTTL: 24 * time.Hour, RotateRefreshTokens: false,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", "static-rt")
+
+	resp, err := g.Handle(context.Background(), grant.Request{Client: newClient(), Form: form, Now: time.Now()})
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+	assert.Nil(t, resp.Pair.Refresh, "no rotation -> no new refresh token")
+}
diff --git a/oauth2/grant/grant_test.go b/oauth2/grant/grant_test.go
new file mode 100644
index 0000000..d3ab6ad
--- /dev/null
+++ b/oauth2/grant/grant_test.go
@@ -0,0 +1,251 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant_test
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Shared fixtures.
+const (
+	clientID       = "client-1"
+	clientSecret   = "secret-1"
+	subject        = "alice"
+	redirectURI    = "https://app.example/cb"
+	codeVerifier   = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+	codeChallenge  = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+)
+
+func newClient() oauth2.Client {
+	return &oauth2.DefaultClient{
+		IDValue:           clientID,
+		Secret:            clientSecret,
+		TypeValue:         oauth2.ClientConfidential,
+		RedirectURIValues: []string{redirectURI},
+		ScopeValues:       []string{"read:mail", "write:mail", "admin"},
+	}
+}
+
+func newStore() *memory.Store { return memory.New() }
+
+func newAccessGen() token.AccessTokenGenerator {
+	return token.NewOpaque(32)
+}
+
+func newRefreshGen() token.RefreshTokenGenerator {
+	return token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)}
+}
+
+func newAuthCodeReq(ctx context.Context, store *memory.Store, withPKCE bool) (*grant.AuthorizationCode, grant.Request) {
+	form := url.Values{}
+	form.Set("redirect_uri", redirectURI)
+
+	rawCode := "raw-auth-code-xyz"
+	codeHash := oauth2.HashToken(nil, rawCode)
+	form.Set("code", rawCode)
+
+	code := &oauth2.AuthorizationCode{
+		Code:        rawCode,
+		CodeHash:    codeHash,
+		ClientID:    clientID,
+		Subject:     subject,
+		RedirectURI: redirectURI,
+		Scope:       "read:mail",
+		IssuedAt:    time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC),
+		ExpiresAt:   time.Date(2026, 5, 20, 12, 10, 0, 0, time.UTC),
+	}
+
+	if withPKCE {
+		code.CodeChallenge = codeChallenge
+		code.CodeChallengeMethod = string(pkce.MethodS256)
+		form.Set("code_verifier", codeVerifier)
+	}
+
+	_ = store.SaveAuthorizationCode(ctx, code)
+
+	g := grant.NewAuthorizationCode(grant.Config{
+		Storage:       store,
+		AccessTokens:  newAccessGen(),
+		RefreshTokens: newRefreshGen(),
+		AccessTTL:     time.Hour,
+		RefreshTTL:    24 * time.Hour,
+		RequirePKCE:   false,
+	})
+	req := grant.Request{
+		Client:   newClient(),
+		Form:     form,
+		Issuer:   "https://auth.example",
+		Audience: "api",
+		Now:      time.Date(2026, 5, 20, 12, 5, 0, 0, time.UTC),
+	}
+
+	return g, req
+}
+
+func TestAuthorizationCodeHappyPath(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+
+	resp, err := g.Handle(context.Background(), req)
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+	assert.NotNil(t, resp.Pair.Refresh)
+	assert.Equal(t, "Bearer", resp.TokenType)
+	assert.Equal(t, "read:mail", resp.Scope)
+}
+
+func TestAuthorizationCodeReuseDetected(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+
+	_, err := g.Handle(context.Background(), req)
+	require.NoError(t, err)
+
+	// Second use must fail.
+	_, err = g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, oauth2.ErrCodeAlreadyUsed) || oauth2.IsCode(err) == oauth2.CodeInvalidGrant,
+		"replayed code must be refused")
+}
+
+func TestAuthorizationCodePKCEMismatch(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Form.Set("code_verifier", "wrong-verifier")
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeRedirectMismatch(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, true)
+	req.Form.Set("redirect_uri", "https://attacker.example/cb")
+
+	_, err := g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestAuthorizationCodeRequiresPKCEWhenConfigured(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g, req := newAuthCodeReq(context.Background(), store, false) // no PKCE on the code
+
+	// Override g with RequirePKCE=true and reuse req. Need a fresh code
+	// because newAuthCodeReq already consumed nothing yet.
+	gReq := grant.NewAuthorizationCode(grant.Config{
+		Storage:       store,
+		AccessTokens:  newAccessGen(),
+		RefreshTokens: newRefreshGen(),
+		AccessTTL:     time.Hour,
+		RefreshTTL:    24 * time.Hour,
+		RequirePKCE:   true,
+	})
+
+	_, err := gReq.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+
+	_ = g // silence unused; g is the non-pkce-required version we don't use here
+}
+
+func TestClientCredentialsHappyPath(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g := grant.NewClientCredentials(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("scope", "read:mail")
+
+	resp, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: form, Issuer: "https://auth.example", Audience: "api",
+		Now: time.Now(),
+	})
+	require.NoError(t, err)
+	assert.Nil(t, resp.Pair.Refresh, "RFC 6749 §4.4.3 forbids refresh tokens for client_credentials")
+	assert.Equal(t, "read:mail", resp.Scope)
+}
+
+func TestClientCredentialsRejectsBroadenedScope(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	g := grant.NewClientCredentials(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), AccessTTL: time.Hour,
+	})
+
+	form := url.Values{}
+	form.Set("scope", "billing:write")
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: form, Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidScope, oauth2.IsCode(err))
+}
+
+func TestRefreshTokenRotationDetectsReuse(t *testing.T) {
+	t.Parallel()
+
+	store := newStore()
+	now := time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC)
+
+	// Seed an existing refresh token.
+	rawRT := "raw-refresh-token-xyz"
+	rtHash := oauth2.HashToken(nil, rawRT)
+	rt := &oauth2.RefreshToken{
+		Token: rawRT, TokenHash: rtHash, ClientID: clientID, Subject: subject,
+		Scope: "read:mail", IssuedAt: now, ExpiresAt: now.Add(24 * time.Hour),
+		FamilyID: "family-1",
+	}
+	require.NoError(t, store.SaveRefreshToken(context.Background(), rt))
+
+	g := grant.NewRefreshToken(grant.Config{
+		Storage: store, AccessTokens: newAccessGen(), RefreshTokens: newRefreshGen(),
+		AccessTTL: time.Hour, RefreshTTL: 24 * time.Hour, RotateRefreshTokens: true,
+	})
+
+	form := url.Values{}
+	form.Set("refresh_token", rawRT)
+
+	req := grant.Request{
+		Client: newClient(), Form: form, Issuer: "https://auth.example",
+		Audience: "api", Now: now.Add(5 * time.Minute),
+	}
+
+	_, err := g.Handle(context.Background(), req)
+	require.NoError(t, err, "first rotation must succeed")
+
+	// Replaying with the SAME old refresh token must fail and revoke the family.
+	_, err = g.Handle(context.Background(), req)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, oauth2.ErrRefreshTokenReused)
+}
diff --git a/oauth2/grant/issue.go b/oauth2/grant/issue.go
new file mode 100644
index 0000000..7423d0a
--- /dev/null
+++ b/oauth2/grant/issue.go
@@ -0,0 +1,77 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// issueTokenPair mints an access token — and, when the config carries a
+// refresh-token generator, a companion refresh token in the same family —
+// for the given subject and scope, persists them, and returns the grant
+// response. It is the shared issuance path of the authorization_code and
+// legacy password grants.
+func issueTokenPair(ctx context.Context, cfg Config, req Request, subject, scope string) (*Response, error) {
+	familyID, err := newFamilyID()
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	expires := req.Now.Add(cfg.AccessTTL)
+
+	atRaw, atHash, err := cfg.AccessTokens.Generate(ctx, token.AccessTokenClaims{
+		Issuer:    req.Issuer,
+		Subject:   subject,
+		Audience:  req.Audience,
+		ClientID:  req.Client.ID(),
+		Scope:     scope,
+		FamilyID:  familyID,
+		IssuedAt:  req.Now,
+		ExpiresAt: expires,
+	})
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	access := &oauth2.AccessToken{
+		Token: atRaw, TokenHash: atHash, ClientID: req.Client.ID(), Subject: subject,
+		Scope: scope, IssuedAt: req.Now, ExpiresAt: expires,
+		FamilyID: familyID, Audience: req.Audience,
+	}
+	if err := cfg.Storage.SaveAccessToken(ctx, access); err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	resp := &Response{
+		Pair:      oauth2.TokenPair{Access: *access},
+		Scope:     scope,
+		TokenType: oauth2.TokenTypeBearer,
+	}
+
+	if cfg.RefreshTokens == nil {
+		return resp, nil
+	}
+
+	rtRaw, rtHash, err := cfg.RefreshTokens.Generate(ctx)
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	refresh := &oauth2.RefreshToken{
+		Token: rtRaw, TokenHash: rtHash, ClientID: req.Client.ID(), Subject: subject,
+		Scope: scope, IssuedAt: req.Now, ExpiresAt: req.Now.Add(cfg.RefreshTTL),
+		FamilyID: familyID,
+	}
+	if err := cfg.Storage.SaveRefreshToken(ctx, refresh); err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	resp.Pair.Refresh = refresh
+
+	return resp, nil
+}
diff --git a/oauth2/grant/legacy_password.go b/oauth2/grant/legacy_password.go
new file mode 100644
index 0000000..e56493c
--- /dev/null
+++ b/oauth2/grant/legacy_password.go
@@ -0,0 +1,89 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// ResourceOwnerVerifier validates a resource owner's username / password
+// for the legacy password grant. It returns the resource-owner subject
+// (the value that lands in the access token's `sub`) on success.
+//
+// An unknown user and a wrong password MUST be indistinguishable to the
+// caller — return the same error for both, so the grant cannot be used to
+// enumerate accounts. Implementations live in the application layer; this
+// package ships none.
+type ResourceOwnerVerifier interface {
+	VerifyResourceOwner(ctx context.Context, username, password string) (subject string, err error)
+}
+
+// LegacyPassword implements the RFC 6749 §4.3 Resource Owner Password
+// Credentials grant.
+//
+// LEGACY — discouraged. This grant makes the client handle the resource
+// owner's password directly; the OAuth 2.0 Security BCP and OAuth 2.1 drop
+// it for exactly that reason. It is opt-in (you must add it to
+// ServerConfig.Grants yourself) and [oauth2.NewServer] refuses it outside
+// [oauth2.Profile20]. Use it only to migrate first-party legacy clients
+// that cannot yet adopt the authorization_code flow; do not enable it for
+// new deployments.
+type LegacyPassword struct {
+	cfg      Config
+	verifier ResourceOwnerVerifier
+}
+
+// NewLegacyPassword constructs the legacy password grant. It panics when
+// Storage, AccessTokens, or verifier is nil.
+func NewLegacyPassword(cfg Config, verifier ResourceOwnerVerifier) *LegacyPassword {
+	if cfg.Storage == nil || cfg.AccessTokens == nil {
+		panic("oauth2/grant: NewLegacyPassword requires Storage and AccessTokens")
+	}
+
+	if verifier == nil {
+		panic("oauth2/grant: NewLegacyPassword requires a ResourceOwnerVerifier")
+	}
+
+	return &LegacyPassword{cfg: cfg, verifier: verifier}
+}
+
+// Type implements [oauth2.Grant]. The "password" identifier is what
+// oauth2.NewServer matches to refuse this grant outside Profile20.
+func (g *LegacyPassword) Type() string { return "password" }
+
+// Handle implements [oauth2.Grant].
+func (g *LegacyPassword) Handle(ctx context.Context, req Request) (*Response, error) {
+	if !grantTypeAllowed(req.Client, "password") {
+		return nil, oauth2.ErrUnauthorizedClient.WithDescription("client cannot use the password grant")
+	}
+
+	username := req.Form.Get("username")
+	password := req.Form.Get("password")
+
+	if username == "" || password == "" {
+		return nil, oauth2.ErrInvalidRequest.WithDescription("missing username or password")
+	}
+
+	subject, err := g.verifier.VerifyResourceOwner(ctx, username, password)
+	if err != nil {
+		// The cause stays server-side for telemetry; the client only sees
+		// the generic description (anti-enumeration).
+		return nil, oauth2.ErrInvalidGrant.
+			WithCause(err).
+			WithDescription("invalid resource owner credentials")
+	}
+
+	scope, err := narrowScopes(req.Form.Get("scope"), req.Client.Scopes())
+	if err != nil {
+		return nil, err
+	}
+
+	return issueTokenPair(ctx, g.cfg, req, subject, scope)
+}
+
+// Compile-time interface check.
+var _ oauth2.Grant = (*LegacyPassword)(nil)
diff --git a/oauth2/grant/legacy_password_test.go b/oauth2/grant/legacy_password_test.go
new file mode 100644
index 0000000..04bffca
--- /dev/null
+++ b/oauth2/grant/legacy_password_test.go
@@ -0,0 +1,173 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant_test
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeROVerifier is a test ResourceOwnerVerifier.
+type fakeROVerifier struct {
+	subject string
+	err     error
+}
+
+func (v fakeROVerifier) VerifyResourceOwner(_ context.Context, _, _ string) (string, error) {
+	return v.subject, v.err
+}
+
+func passwordForm(username, password, scope string) url.Values {
+	form := url.Values{}
+
+	if username != "" {
+		form.Set("username", username)
+	}
+
+	if password != "" {
+		form.Set("password", password)
+	}
+
+	if scope != "" {
+		form.Set("scope", scope)
+	}
+
+	return form
+}
+
+func TestNewLegacyPasswordPanics(t *testing.T) {
+	t.Parallel()
+
+	good := fakeROVerifier{subject: subject}
+	full := grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour}
+
+	assert.Panics(t, func() { grant.NewLegacyPassword(grant.Config{}, good) })
+	assert.Panics(t, func() { grant.NewLegacyPassword(full, nil) })
+}
+
+func TestLegacyPasswordType(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{subject: subject},
+	)
+	assert.Equal(t, "password", g.Type())
+}
+
+func TestLegacyPasswordHappyPath(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(grant.Config{
+		Storage: newStore(), AccessTokens: newAccessGen(),
+		RefreshTokens: newRefreshGen(), AccessTTL: time.Hour, RefreshTTL: 24 * time.Hour,
+	}, fakeROVerifier{subject: "alice"})
+
+	resp, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: passwordForm("alice", "s3cr3t", "read:mail"),
+		Issuer: "https://auth.example", Audience: "api", Now: time.Now(),
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+	assert.Equal(t, "alice", resp.Pair.Access.Subject)
+	assert.Equal(t, "read:mail", resp.Scope)
+	assert.NotNil(t, resp.Pair.Refresh, "a refresh token is issued when configured")
+}
+
+func TestLegacyPasswordWithoutRefreshGenerator(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{subject: "alice"},
+	)
+
+	resp, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: passwordForm("alice", "s3cr3t", ""), Now: time.Now(),
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, resp.Pair.Access.Token)
+	assert.Nil(t, resp.Pair.Refresh)
+}
+
+func TestLegacyPasswordMissingCredentials(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{subject: "alice"},
+	)
+
+	for _, form := range []url.Values{
+		passwordForm("", "s3cr3t", ""),
+		passwordForm("alice", "", ""),
+		passwordForm("", "", ""),
+	} {
+		_, err := g.Handle(context.Background(), grant.Request{
+			Client: newClient(), Form: form, Now: time.Now(),
+		})
+		require.Error(t, err)
+		assert.Equal(t, oauth2.CodeInvalidRequest, oauth2.IsCode(err))
+	}
+}
+
+func TestLegacyPasswordInvalidCredentials(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{err: errors.New("no such user")},
+	)
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: passwordForm("ghost", "whatever", ""), Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(err))
+}
+
+func TestLegacyPasswordGrantTypeNotAllowed(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{subject: "alice"},
+	)
+
+	client := &oauth2.DefaultClient{
+		IDValue:         clientID,
+		TypeValue:       oauth2.ClientConfidential,
+		GrantTypeValues: []string{"authorization_code"}, // not "password"
+	}
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: client, Form: passwordForm("alice", "s3cr3t", ""), Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeUnauthorizedClient, oauth2.IsCode(err))
+}
+
+func TestLegacyPasswordRejectsBroadenedScope(t *testing.T) {
+	t.Parallel()
+
+	g := grant.NewLegacyPassword(
+		grant.Config{Storage: newStore(), AccessTokens: newAccessGen(), AccessTTL: time.Hour},
+		fakeROVerifier{subject: "alice"},
+	)
+
+	_, err := g.Handle(context.Background(), grant.Request{
+		Client: newClient(), Form: passwordForm("alice", "s3cr3t", "billing:write"), Now: time.Now(),
+	})
+	require.Error(t, err)
+	assert.Equal(t, oauth2.CodeInvalidScope, oauth2.IsCode(err))
+}
diff --git a/oauth2/grant/refresh_token.go b/oauth2/grant/refresh_token.go
new file mode 100644
index 0000000..ce2367a
--- /dev/null
+++ b/oauth2/grant/refresh_token.go
@@ -0,0 +1,190 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package grant
+
+import (
+	"context"
+	"errors"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+)
+
+// RefreshToken implements RFC 6749 §6 with the OAuth 2.0 BCP §8.10
+// hardening (rotation + reuse detection).
+//
+// The flow:
+//
+//  1. Look up the refresh token; treat consumed tokens as reuse and revoke
+//     the family.
+//  2. Re-bind client (refresh.ClientID MUST match the authenticated client).
+//  3. Optionally narrow scope (RFC 6749 §6 forbids broadening).
+//  4. Issue a fresh access token.
+//  5. If RotateRefreshTokens, issue a fresh refresh token in the same
+//     family AND atomically mark the old one consumed.
+type RefreshToken struct {
+	cfg Config
+}
+
+// NewRefreshToken constructs the handler.
+func NewRefreshToken(cfg Config) *RefreshToken {
+	if cfg.Storage == nil || cfg.AccessTokens == nil {
+		panic("oauth2/grant: NewRefreshToken requires Storage and AccessTokens")
+	}
+
+	return &RefreshToken{cfg: cfg}
+}
+
+// Type implements [Grant].
+func (g *RefreshToken) Type() string { return "refresh_token" }
+
+// Handle implements [Grant].
+func (g *RefreshToken) Handle(ctx context.Context, req Request) (*Response, error) {
+	if !grantTypeAllowed(req.Client, "refresh_token") {
+		return nil, oauth2.ErrUnauthorizedClient.WithDescription("client cannot use refresh_token")
+	}
+
+	raw := req.Form.Get("refresh_token")
+	if raw == "" {
+		return nil, oauth2.ErrInvalidRequest.WithDescription("missing refresh_token")
+	}
+
+	rtHash := oauth2.HashToken(nil, raw)
+
+	rt, err := g.cfg.Storage.LookupRefreshToken(ctx, rtHash)
+	if err != nil {
+		return nil, err //nolint:wrapcheck // oauth2.* sentinels pass through
+	}
+
+	if rt.Consumed {
+		// Reuse detected — revoke the whole family and refuse.
+		_ = g.cfg.Storage.RevokeRefreshFamily(ctx, rt.FamilyID)
+
+		return nil, oauth2.ErrRefreshTokenReused
+	}
+
+	if rt.IsExpired(req.Now) {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("refresh_token expired")
+	}
+
+	if rt.ClientID != req.Client.ID() {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("refresh_token issued for a different client")
+	}
+
+	scope, err := narrowScopesForRefresh(req.Form.Get("scope"), rt.Scope)
+	if err != nil {
+		return nil, err
+	}
+
+	return g.issueRotated(ctx, req, rt, scope)
+}
+
+func (g *RefreshToken) issueRotated(ctx context.Context, req Request, old *oauth2.RefreshToken, scope string) (*Response, error) {
+	expires := req.Now.Add(g.cfg.AccessTTL)
+
+	atRaw, atHash, err := g.cfg.AccessTokens.Generate(ctx, token.AccessTokenClaims{
+		Issuer:    req.Issuer,
+		Subject:   old.Subject,
+		Audience:  req.Audience,
+		ClientID:  req.Client.ID(),
+		Scope:     scope,
+		FamilyID:  old.FamilyID,
+		IssuedAt:  req.Now,
+		ExpiresAt: expires,
+	})
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	access := &oauth2.AccessToken{
+		Token: atRaw, TokenHash: atHash, ClientID: req.Client.ID(), Subject: old.Subject,
+		Scope: scope, IssuedAt: req.Now, ExpiresAt: expires,
+		FamilyID: old.FamilyID, Audience: req.Audience,
+	}
+	if err := g.cfg.Storage.SaveAccessToken(ctx, access); err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	resp := &Response{
+		Pair:      oauth2.TokenPair{Access: *access},
+		Scope:     scope,
+		TokenType: oauth2.TokenTypeBearer,
+	}
+
+	if !g.cfg.RotateRefreshTokens || g.cfg.RefreshTokens == nil {
+		return resp, nil
+	}
+
+	rtRaw, rtHash, err := g.cfg.RefreshTokens.Generate(ctx)
+	if err != nil {
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	next := &oauth2.RefreshToken{
+		Token: rtRaw, TokenHash: rtHash, ClientID: req.Client.ID(), Subject: old.Subject,
+		Scope: scope, IssuedAt: req.Now, ExpiresAt: req.Now.Add(g.cfg.RefreshTTL),
+		FamilyID: old.FamilyID,
+	}
+
+	if err := g.cfg.Storage.RotateRefreshToken(ctx, old.TokenHash, next); err != nil {
+		if errors.Is(err, oauth2.ErrRefreshTokenReused) {
+			return nil, err //nolint:wrapcheck // oauth2.* sentinels pass through
+		}
+
+		return nil, oauth2.ErrServerError.WithCause(err)
+	}
+
+	resp.Pair.Refresh = next
+
+	return resp, nil
+}
+
+// narrowScopesForRefresh refuses broadening (RFC 6749 §6). An empty
+// requested scope inherits the original grant's scope.
+func narrowScopesForRefresh(requested, original string) (string, error) {
+	if requested == "" {
+		return original, nil
+	}
+
+	originalSet := make(map[string]struct{}, 8)
+
+	for _, s := range splitScopes(original) {
+		originalSet[s] = struct{}{}
+	}
+
+	for _, s := range splitScopes(requested) {
+		if _, ok := originalSet[s]; !ok {
+			return "", oauth2.ErrInvalidScope.WithDescription("refresh cannot broaden scope")
+		}
+	}
+
+	return requested, nil
+}
+
+func splitScopes(s string) []string {
+	out := make([]string, 0, 4)
+	start := -1
+
+	for i, r := range s {
+		if r == ' ' || r == '\t' {
+			if start >= 0 {
+				out = append(out, s[start:i])
+				start = -1
+			}
+
+			continue
+		}
+
+		if start < 0 {
+			start = i
+		}
+	}
+
+	if start >= 0 {
+		out = append(out, s[start:])
+	}
+
+	return out
+}
diff --git a/oauth2/grant_contract.go b/oauth2/grant_contract.go
new file mode 100644
index 0000000..bab8d2d
--- /dev/null
+++ b/oauth2/grant_contract.go
@@ -0,0 +1,51 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"net/url"
+	"time"
+)
+
+// GrantRequest is the parsed /token request handed to a [Grant]. The
+// server unpacks the HTTP request once and feeds this struct to whichever
+// Grant matches the grant_type parameter.
+type GrantRequest struct {
+	Client   Client
+	Form     url.Values
+	Issuer   string
+	Audience string
+	Now      time.Time
+	// Profile is the server's active security profile. Grants use it to
+	// enforce the profile-mandated rules at runtime (e.g. PKCE required,
+	// "plain" PKCE refused). A profile can only tighten a grant's own
+	// configuration, never loosen it.
+	Profile Profile
+}
+
+// TokenTypeBearer is the RFC 6750 §7.1 token type issued by every grant in
+// this library; it is the value of the OAuth2 token_type response field.
+const TokenTypeBearer = "Bearer"
+
+// GrantResponse is what a grant hands back to the server. The HTTP layer
+// projects it onto the RFC 6749 §5.1 JSON body.
+type GrantResponse struct {
+	Pair        TokenPair
+	Scope       string
+	TokenType   string // e.g. TokenTypeBearer
+	ExtraParams map[string]any
+}
+
+// Grant validates and processes one OAuth2 grant_type value. Each Grant is
+// invoked exclusively by the server's /token endpoint; the server
+// authenticates the client beforehand.
+type Grant interface {
+	// Type returns the grant_type identifier.
+	Type() string
+	// Handle runs the grant. Returns oauth2.* sentinel errors that the
+	// server then projects onto the OAuth2 JSON error envelope.
+	Handle(ctx context.Context, req GrantRequest) (*GrantResponse, error)
+}
diff --git a/oauth2/hash.go b/oauth2/hash.go
new file mode 100644
index 0000000..52f8593
--- /dev/null
+++ b/oauth2/hash.go
@@ -0,0 +1,28 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+)
+
+// HashToken returns the canonical one-way hash used by the storage layer to
+// look tokens up without ever persisting the raw value.
+//
+// pepper is an optional HMAC key. The shipped token machinery — the
+// generators in oauth2/token and every server lookup path (grants,
+// /introspect, /revoke) — calls HashToken with a nil pepper: OAuth2 tokens
+// and codes carry ≥ 128 bits of entropy, so a bare SHA-256 is already
+// preimage- and brute-force-resistant. Pass a non-nil pepper only if you
+// hash some lower-entropy value AND every party that looks it up uses the
+// exact same key.
+func HashToken(pepper []byte, token string) string {
+	mac := hmac.New(sha256.New, pepper)
+	mac.Write([]byte(token))
+
+	return hex.EncodeToString(mac.Sum(nil))
+}
diff --git a/oauth2/introspect_endpoint.go b/oauth2/introspect_endpoint.go
new file mode 100644
index 0000000..6ba7c65
--- /dev/null
+++ b/oauth2/introspect_endpoint.go
@@ -0,0 +1,110 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+// IntrospectHandler returns the http.Handler for RFC 7662 token
+// introspection. The caller MUST authenticate as an OAuth2 client (the
+// same ClientAuthenticators are reused). A successful response carries
+// "active":true plus the standard claims; a failed lookup returns
+// "active":false with no other fields.
+func (s *Server) IntrospectHandler() http.Handler {
+	return http.HandlerFunc(s.serveIntrospect)
+}
+
+func (s *Server) serveIntrospect(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("POST required"))
+
+		return
+	}
+
+	if err := r.ParseForm(); err != nil {
+		writeOAuthError(w, ErrInvalidRequest.WithCause(err))
+
+		return
+	}
+
+	if _, err := s.authenticateClient(r.Context(), r); err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	rawToken := r.PostFormValue("token")
+	if rawToken == "" {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("missing token"))
+
+		return
+	}
+
+	body := s.introspect(r, rawToken)
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(http.StatusOK)
+
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		_ = err
+	}
+}
+
+// introspectResponse is the RFC 7662 §2.2 JSON envelope. We populate the
+// most commonly consumed fields; deployments needing custom claims should
+// wrap this endpoint.
+type introspectResponse struct {
+	Active    bool   `json:"active"`
+	Scope     string `json:"scope,omitempty"`
+	ClientID  string `json:"client_id,omitempty"`
+	Subject   string `json:"sub,omitempty"`
+	ExpiresAt int64  `json:"exp,omitempty"`
+	IssuedAt  int64  `json:"iat,omitempty"`
+	TokenType string `json:"token_type,omitempty"`
+	Audience  string `json:"aud,omitempty"`
+}
+
+func (s *Server) introspect(r *http.Request, rawToken string) introspectResponse {
+	hash := HashToken(nil, rawToken)
+	now := s.cfg.Now()
+
+	if at, err := s.cfg.Storage.LookupAccessToken(r.Context(), hash); err == nil {
+		if at.IsExpired(now) {
+			return introspectResponse{Active: false}
+		}
+
+		return introspectResponse{
+			Active:    true,
+			Scope:     at.Scope,
+			ClientID:  at.ClientID,
+			Subject:   at.Subject,
+			ExpiresAt: at.ExpiresAt.Unix(),
+			IssuedAt:  at.IssuedAt.Unix(),
+			TokenType: TokenTypeBearer,
+			Audience:  at.Audience,
+		}
+	}
+
+	if rt, err := s.cfg.Storage.LookupRefreshToken(r.Context(), hash); err == nil {
+		if rt.IsExpired(now) || rt.Consumed {
+			return introspectResponse{Active: false}
+		}
+
+		return introspectResponse{
+			Active:    true,
+			Scope:     rt.Scope,
+			ClientID:  rt.ClientID,
+			Subject:   rt.Subject,
+			ExpiresAt: rt.ExpiresAt.Unix(),
+			IssuedAt:  rt.IssuedAt.Unix(),
+			TokenType: "refresh_token",
+		}
+	}
+
+	return introspectResponse{Active: false}
+}
diff --git a/oauth2/issuer.go b/oauth2/issuer.go
new file mode 100644
index 0000000..bb6e59b
--- /dev/null
+++ b/oauth2/issuer.go
@@ -0,0 +1,34 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"net/http"
+)
+
+// IssuerResolver returns the issuer identifier (and matching audience) for
+// the request being processed. The interface lets multi-tenant deployments
+// dispatch on the Host header or a routing prefix without baking the
+// tenant into every grant handler.
+type IssuerResolver interface {
+	Resolve(ctx context.Context, r *http.Request) (issuer, audience string, err error)
+}
+
+// StaticIssuer returns an [IssuerResolver] that always returns the
+// configured (issuer, audience) pair. The canonical single-tenant setup.
+func StaticIssuer(issuer, audience string) IssuerResolver {
+	return staticIssuer{issuer: issuer, audience: audience}
+}
+
+type staticIssuer struct {
+	issuer   string
+	audience string
+}
+
+// Resolve implements [IssuerResolver].
+func (s staticIssuer) Resolve(context.Context, *http.Request) (string, string, error) {
+	return s.issuer, s.audience, nil
+}
diff --git a/oauth2/metadata_endpoint.go b/oauth2/metadata_endpoint.go
new file mode 100644
index 0000000..2ec153f
--- /dev/null
+++ b/oauth2/metadata_endpoint.go
@@ -0,0 +1,115 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+)
+
+// MetadataHandler returns the http.Handler for RFC 8414's
+// /.well-known/oauth-authorization-server discovery document. The
+// payload is derived from the active ServerConfig so adding a grant or
+// changing the issuer is automatically reflected.
+//
+// Endpoint URLs are built as issuer + ServerConfig.RoutePrefix + "/<name>",
+// so the document stays consistent with wherever the handlers are mounted.
+// The jwks_uri keeps the host-root .well-known location per RFC 8615.
+func (s *Server) MetadataHandler() http.Handler {
+	return http.HandlerFunc(s.serveMetadata)
+}
+
+func (s *Server) serveMetadata(w http.ResponseWriter, r *http.Request) {
+	issuer, _, err := s.resolveIssuer(r.Context(), r)
+	if err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	base := strings.TrimSuffix(issuer, "/")
+	routes := base + s.cfg.RoutePrefix
+
+	doc := metadataDoc{
+		Issuer:                            issuer,
+		AuthorizationEndpoint:             routes + "/authorize",
+		TokenEndpoint:                     routes + "/token",
+		RevocationEndpoint:                routes + "/revoke",
+		IntrospectionEndpoint:             routes + "/introspect",
+		JWKSURI:                           base + "/.well-known/jwks.json",
+		GrantTypesSupported:               s.grantTypes(),
+		ResponseTypesSupported:            []string{responseTypeCode},
+		TokenEndpointAuthMethodsSupported: s.clientAuthMethods(),
+		CodeChallengeMethodsSupported:     s.pkceMethods(),
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "max-age=300")
+	w.WriteHeader(http.StatusOK)
+
+	if err := json.NewEncoder(w).Encode(doc); err != nil {
+		_ = err
+	}
+}
+
+// metadataDoc is the subset of RFC 8414 we publish. Adding new fields is
+// trivial and binary-compatible: clients ignore unknown keys.
+type metadataDoc struct {
+	Issuer                            string   `json:"issuer"`
+	AuthorizationEndpoint             string   `json:"authorization_endpoint,omitempty"`
+	TokenEndpoint                     string   `json:"token_endpoint"`
+	RevocationEndpoint                string   `json:"revocation_endpoint,omitempty"`
+	IntrospectionEndpoint             string   `json:"introspection_endpoint,omitempty"`
+	JWKSURI                           string   `json:"jwks_uri,omitempty"`
+	GrantTypesSupported               []string `json:"grant_types_supported"`
+	ResponseTypesSupported            []string `json:"response_types_supported"`
+	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`
+	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported,omitempty"`
+}
+
+func (s *Server) grantTypes() []string {
+	out := make([]string, 0, len(s.dispatch))
+	for t := range s.dispatch {
+		out = append(out, t)
+	}
+
+	return out
+}
+
+func (s *Server) clientAuthMethods() []string {
+	out := make([]string, 0, len(s.cfg.ClientAuth))
+	for _, m := range s.cfg.ClientAuth {
+		out = append(out, m.Method())
+	}
+
+	return out
+}
+
+func (s *Server) pkceMethods() []string {
+	if s.cfg.Profile.AllowsPKCEPlain() {
+		return []string{pkce.MethodS256.String(), pkce.MethodPlain.String()}
+	}
+
+	return []string{pkce.MethodS256.String()}
+}
+
+// normalizeRoutePrefix cleans a user-supplied [ServerConfig.RoutePrefix]:
+// an empty value defaults to "/oauth2", a missing leading slash is added,
+// and a trailing slash is trimmed. The result is either "" (root mount) or
+// a clean "/path".
+func normalizeRoutePrefix(prefix string) string {
+	if prefix == "" {
+		return "/oauth2"
+	}
+
+	if !strings.HasPrefix(prefix, "/") {
+		prefix = "/" + prefix
+	}
+
+	return strings.TrimRight(prefix, "/")
+}
diff --git a/oauth2/models.go b/oauth2/models.go
new file mode 100644
index 0000000..d85ffc1
--- /dev/null
+++ b/oauth2/models.go
@@ -0,0 +1,109 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import "time"
+
+// AuthorizationCode is the record persisted between the /authorize call and
+// the matching /token call. The Code field carries the raw, single-use value
+// returned to the user-agent; storage implementations MUST hash it before
+// persisting and consume atomically (RFC 6749 §4.1.2 + OAuth 2.0 BCP §4.5).
+type AuthorizationCode struct {
+	// Code is the raw, single-use authorization code as issued to the
+	// user-agent. Storage implementations persist its hash, never the raw
+	// value. The struct carries the raw form because the issuance flow
+	// needs to redirect it.
+	Code string
+	// CodeHash is the storage-side hash of Code. Filled in by the storage
+	// layer; the issuance flow leaves it empty.
+	CodeHash string
+	// ClientID is the requesting client's identifier.
+	ClientID string
+	// Subject is the resource-owner subject (`sub` claim equivalent).
+	Subject string
+	// RedirectURI is the redirect_uri sent to /authorize; the matching
+	// /token call MUST present the same URI.
+	RedirectURI string
+	// Scope is the granted (post-consent) scope.
+	Scope string
+	// CodeChallenge is the PKCE challenge (RFC 7636 §4.2). Required for
+	// public clients; required for every client under OAuth 2.0 BCP §2.1.1.
+	CodeChallenge string
+	// CodeChallengeMethod is the PKCE method ("S256" or "plain").
+	CodeChallengeMethod string
+	// Nonce echoes the OIDC nonce parameter for replay protection in id
+	// tokens. Empty for plain OAuth2 flows.
+	Nonce string
+	// IssuedAt is the wall-clock issuance time.
+	IssuedAt time.Time
+	// ExpiresAt is the wall-clock expiry time. Codes typically live 10
+	// minutes (RFC 6749 §4.1.2).
+	ExpiresAt time.Time
+}
+
+// IsExpired reports whether the code has passed its expiry.
+func (c *AuthorizationCode) IsExpired(now time.Time) bool {
+	return now.After(c.ExpiresAt)
+}
+
+// AccessToken is the record persisted for an issued access token. The Token
+// field carries the raw value returned to the client; the TokenHash field
+// is the storage key. JWT-formatted tokens still have a TokenHash so that
+// revocation and introspection can be implemented uniformly.
+type AccessToken struct {
+	Token     string
+	TokenHash string
+	ClientID  string
+	Subject   string
+	Scope     string
+	IssuedAt  time.Time
+	ExpiresAt time.Time
+	// FamilyID identifies the token family this access token belongs to,
+	// used for refresh-token rotation and reuse detection. Empty when
+	// rotation is disabled.
+	FamilyID string
+	// Audience is the configured aud claim (typically the resource server
+	// identifier). Single-valued in this model; servers needing multi-aud
+	// should rebuild the model in their JWT signer.
+	Audience string
+}
+
+// IsExpired reports whether the token has passed its expiry.
+func (t *AccessToken) IsExpired(now time.Time) bool {
+	return now.After(t.ExpiresAt)
+}
+
+// RefreshToken is the record persisted for a refresh token. Refresh tokens
+// are ALWAYS opaque and ALWAYS stored hashed (never the raw value).
+type RefreshToken struct {
+	Token     string // raw value, only present transiently during issuance
+	TokenHash string
+	ClientID  string
+	Subject   string
+	Scope     string
+	IssuedAt  time.Time
+	ExpiresAt time.Time
+	// FamilyID groups every refresh token derived from the same original
+	// authorisation. Rotation issues a new RefreshToken with the same
+	// FamilyID; reuse of a consumed token leads to revocation of the
+	// entire family (OAuth 2.0 BCP §8.10.3).
+	FamilyID string
+	// Consumed indicates whether the token has been rotated. Reuse of a
+	// consumed token MUST trigger family revocation.
+	Consumed bool
+}
+
+// IsExpired reports whether the token has passed its expiry.
+func (t *RefreshToken) IsExpired(now time.Time) bool {
+	return now.After(t.ExpiresAt)
+}
+
+// TokenPair couples an access token with its companion refresh token (when
+// rotation is enabled). The grant handlers return this; the response writer
+// turns it into the RFC 6749 §5.1 JSON body.
+type TokenPair struct {
+	Access  AccessToken
+	Refresh *RefreshToken
+}
diff --git a/oauth2/pkce/method_test.go b/oauth2/pkce/method_test.go
new file mode 100644
index 0000000..cab49ca
--- /dev/null
+++ b/oauth2/pkce/method_test.go
@@ -0,0 +1,19 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package pkce_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMethodString(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "S256", pkce.MethodS256.String())
+	assert.Equal(t, "plain", pkce.MethodPlain.String())
+}
diff --git a/oauth2/pkce/pkce.go b/oauth2/pkce/pkce.go
new file mode 100644
index 0000000..ac2dfec
--- /dev/null
+++ b/oauth2/pkce/pkce.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package pkce ships the RFC 7636 verifier helpers used by the OAuth2
+// server's authorization-code grant.
+//
+// PKCE is mandatory for public clients and recommended for confidential
+// clients (OAuth 2.0 BCP §2.1.1 / OAuth 2.1 draft §1.7). The "plain"
+// method is supported for backwards compatibility but its use is refused
+// when the server profile is OAuth 2.0 BCP or OAuth 2.1 draft.
+package pkce
+
+import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+)
+
+// Method identifies the PKCE transformation used to derive the challenge
+// from the verifier (RFC 7636 §4.2).
+type Method string
+
+const (
+	// MethodS256 is the SHA-256 + base64url challenge transformation.
+	MethodS256 Method = "S256"
+	// MethodPlain echoes the verifier verbatim. RFC 7636 allows it for
+	// transition; the server profile must opt-in.
+	MethodPlain Method = "plain"
+)
+
+// String makes Method satisfy fmt.Stringer.
+func (m Method) String() string { return string(m) }
+
+// Verify computes the challenge from verifier per method and compares it
+// constant-time against expected. Returns false on length mismatch, on
+// unsupported method, or on plain-vs-S256 mismatch.
+func Verify(method Method, verifier, expected string) bool {
+	switch method {
+	case MethodS256:
+		return s256Equal(verifier, expected)
+	case MethodPlain:
+		return subtle.ConstantTimeCompare([]byte(verifier), []byte(expected)) == 1
+	default:
+		return false
+	}
+}
+
+// VerifyS256 is a convenience for the recommended S256 method.
+func VerifyS256(verifier, expected string) bool { return s256Equal(verifier, expected) }
+
+func s256Equal(verifier, expected string) bool {
+	sum := sha256.Sum256([]byte(verifier))
+	got := base64.RawURLEncoding.EncodeToString(sum[:])
+
+	return subtle.ConstantTimeCompare([]byte(got), []byte(expected)) == 1
+}
+
+// Challenge derives the challenge for a given verifier and method. Useful
+// in test helpers and client-side libraries; not used by the server during
+// verification (the server only consumes the challenge stored alongside
+// the code).
+func Challenge(method Method, verifier string) (string, bool) {
+	switch method {
+	case MethodS256:
+		sum := sha256.Sum256([]byte(verifier))
+
+		return base64.RawURLEncoding.EncodeToString(sum[:]), true
+	case MethodPlain:
+		return verifier, true
+	default:
+		return "", false
+	}
+}
diff --git a/oauth2/pkce/pkce_test.go b/oauth2/pkce/pkce_test.go
new file mode 100644
index 0000000..0f4de0a
--- /dev/null
+++ b/oauth2/pkce/pkce_test.go
@@ -0,0 +1,72 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package pkce_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2/pkce"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	// Test vector from RFC 7636 Appendix B:
+	// verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+	// challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+	rfc7636Verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+	rfc7636Challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+)
+
+func TestVerifyS256AcceptsRFC7636Vector(t *testing.T) {
+	t.Parallel()
+
+	assert.True(t, pkce.VerifyS256(rfc7636Verifier, rfc7636Challenge))
+	assert.True(t, pkce.Verify(pkce.MethodS256, rfc7636Verifier, rfc7636Challenge))
+}
+
+func TestVerifyS256RejectsBadVerifier(t *testing.T) {
+	t.Parallel()
+
+	assert.False(t, pkce.VerifyS256("wrong-verifier", rfc7636Challenge))
+}
+
+func TestVerifyPlainAcceptsExactMatch(t *testing.T) {
+	t.Parallel()
+
+	assert.True(t, pkce.Verify(pkce.MethodPlain, "verifier", "verifier"))
+	assert.False(t, pkce.Verify(pkce.MethodPlain, "verifier", "other"))
+}
+
+func TestVerifyUnknownMethodReturnsFalse(t *testing.T) {
+	t.Parallel()
+
+	assert.False(t, pkce.Verify("MD5", "verifier", "challenge"))
+}
+
+func TestChallengeMatchesVerification(t *testing.T) {
+	t.Parallel()
+
+	verifier := "my-random-verifier-with-enough-entropy-43-chars"
+	got, ok := pkce.Challenge(pkce.MethodS256, verifier)
+	require.True(t, ok)
+	assert.True(t, pkce.VerifyS256(verifier, got),
+		"Challenge / Verify round-trip MUST agree")
+}
+
+func TestChallengePlainEchoesVerifier(t *testing.T) {
+	t.Parallel()
+
+	got, ok := pkce.Challenge(pkce.MethodPlain, "foo")
+	require.True(t, ok)
+	assert.Equal(t, "foo", got)
+}
+
+func TestChallengeUnknownMethodReturnsFalse(t *testing.T) {
+	t.Parallel()
+
+	_, ok := pkce.Challenge("MD5", "foo")
+	assert.False(t, ok)
+}
diff --git a/oauth2/profile.go b/oauth2/profile.go
new file mode 100644
index 0000000..8f06e50
--- /dev/null
+++ b/oauth2/profile.go
@@ -0,0 +1,60 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+// Profile selects the security baseline the [Server] applies. Three values
+// are supported:
+//
+//   - Profile20      — vanilla RFC 6749. Allows implicit and password
+//     grants when explicitly registered; PKCE is opt-in.
+//   - Profile20BCP   — IETF draft-ietf-oauth-security-topics ("OAuth 2.0
+//     Security Best Current Practice"). Refuses implicit
+//     and password grants outright; mandates PKCE on
+//     authorization_code; mandates refresh-token
+//     rotation.
+//   - Profile21Draft — draft-ietf-oauth-v2-1. Same constraints as BCP plus
+//     an explicit prohibition of "plain" PKCE.
+//
+// The recommended default is [Profile20BCP].
+type Profile int
+
+// Profile enumerations. The zero value is Profile20BCP so the "I forgot to
+// pick a profile" deployment lands on a safe baseline.
+const (
+	Profile20BCP   Profile = iota // recommended default
+	Profile20                     // vanilla RFC 6749 (legacy grants allowed)
+	Profile21Draft                // OAuth 2.1 draft (strictest)
+)
+
+// String makes Profile satisfy fmt.Stringer; values match the metadata
+// document published at /.well-known/oauth-authorization-server.
+func (p Profile) String() string {
+	switch p {
+	case Profile20:
+		return "oauth2.0"
+	case Profile20BCP:
+		return "oauth2.0-bcp"
+	case Profile21Draft:
+		return "oauth2.1-draft"
+	default:
+		return "unknown"
+	}
+}
+
+// AllowsLegacyGrant reports whether the profile permits the legacy
+// password / implicit grants. Only [Profile20] does.
+func (p Profile) AllowsLegacyGrant() bool { return p == Profile20 }
+
+// RequiresPKCE reports whether the profile mandates PKCE on
+// authorization_code. True for BCP and 21-draft.
+func (p Profile) RequiresPKCE() bool { return p != Profile20 }
+
+// RequiresRefreshRotation reports whether the profile mandates refresh-
+// token rotation. True for BCP and 21-draft.
+func (p Profile) RequiresRefreshRotation() bool { return p != Profile20 }
+
+// AllowsPKCEPlain reports whether the profile tolerates the "plain" PKCE
+// method (RFC 7636 §4.2). Only Profile20 does; BCP and 21-draft mandate S256.
+func (p Profile) AllowsPKCEPlain() bool { return p == Profile20 }
diff --git a/oauth2/revoke_endpoint.go b/oauth2/revoke_endpoint.go
new file mode 100644
index 0000000..7d2b4db
--- /dev/null
+++ b/oauth2/revoke_endpoint.go
@@ -0,0 +1,84 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"net/http"
+)
+
+// RevokeHandler returns the http.Handler for RFC 7009 token revocation.
+// Both access and refresh tokens are accepted; the server tries each
+// kind in turn. Revocation of a refresh token also revokes the rest of
+// its family (the BCP §8.10.3 reuse-detection mechanism reuses the same
+// hammer).
+//
+// The handler always returns 200 OK on completion — RFC 7009 §2.2 says
+// revocation requests MUST NOT leak whether the token existed.
+func (s *Server) RevokeHandler() http.Handler {
+	return http.HandlerFunc(s.serveRevoke)
+}
+
+func (s *Server) serveRevoke(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("POST required"))
+
+		return
+	}
+
+	if err := r.ParseForm(); err != nil {
+		writeOAuthError(w, ErrInvalidRequest.WithCause(err))
+
+		return
+	}
+
+	client, err := s.authenticateClient(r.Context(), r)
+	if err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	rawToken := r.PostFormValue("token")
+	if rawToken == "" {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("missing token"))
+
+		return
+	}
+
+	// RFC 7009 §2.1: the hint is optional. We try access then refresh
+	// regardless so the caller's hint is treated as advisory.
+	s.bestEffortRevoke(r.Context(), client, rawToken)
+
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Pragma", "no-cache")
+	w.WriteHeader(http.StatusOK)
+}
+
+// bestEffortRevoke tries to revoke a token assuming it is an access token,
+// then assuming it is a refresh token. The implementation is intentionally
+// silent: per RFC 7009 §2.2, the response must not reveal whether the
+// token existed.
+func (s *Server) bestEffortRevoke(ctx context.Context, client Client, rawToken string) {
+	hash := HashToken(nil, rawToken)
+
+	if at, err := s.cfg.Storage.LookupAccessToken(ctx, hash); err == nil {
+		if at.ClientID == client.ID() {
+			_ = s.cfg.Storage.RevokeAccessToken(ctx, hash)
+
+			if at.FamilyID != "" {
+				_ = s.cfg.Storage.RevokeRefreshFamily(ctx, at.FamilyID)
+			}
+		}
+
+		return
+	}
+
+	if rt, err := s.cfg.Storage.LookupRefreshToken(ctx, hash); err == nil {
+		if rt.ClientID == client.ID() && rt.FamilyID != "" {
+			_ = s.cfg.Storage.RevokeRefreshFamily(ctx, rt.FamilyID)
+		}
+	}
+}
diff --git a/oauth2/server.go b/oauth2/server.go
new file mode 100644
index 0000000..a5f0f51
--- /dev/null
+++ b/oauth2/server.go
@@ -0,0 +1,165 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+// ClientAuthenticator is the contract the [Server] consumes for client
+// authentication. Concrete implementations live in oauth2/clientauth; the
+// interface lives here to avoid an import cycle.
+type ClientAuthenticator interface {
+	Method() string
+	Match(r *http.Request) bool
+	Authenticate(ctx context.Context, r *http.Request, store ClientStore) (Client, error)
+}
+
+// ServerConfig bundles every dependency the [Server] needs at construction
+// time. The composition root (typically main()) instantiates a ServerConfig
+// once and passes it to [NewServer].
+type ServerConfig struct {
+	// Profile selects the security baseline (see Profile). The zero value
+	// is [Profile20BCP] — the recommended default.
+	Profile Profile
+	// Storage is the persistence backend (codes / access tokens / refresh
+	// tokens). Use storage/memory for dev/tests and store/sql or
+	// store/redis for production.
+	Storage Storage
+	// ClientStore resolves client records by ID.
+	ClientStore ClientStore
+	// IssuerResolver selects the (issuer, audience) pair for each request.
+	// Use [StaticIssuer] for single-tenant deployments.
+	IssuerResolver IssuerResolver
+	// Grants lists the grant_type handlers active on /token. The Server
+	// builds a dispatch map keyed on Grant.Type().
+	Grants []Grant
+	// ClientAuth lists the client-authentication methods active on /token
+	// (and /revoke, /introspect). The Server consults them in order and
+	// uses the first one whose Match returns true.
+	ClientAuth []ClientAuthenticator
+	// RoutePrefix is the path prefix under which the token / revoke /
+	// introspect / authorize endpoints are mounted. It is used solely to
+	// build the endpoint URLs published by the RFC 8414 metadata document,
+	// so the discovery document stays consistent with wherever the handlers
+	// are actually mounted.
+	//
+	// The value is normalized at construction: an empty prefix defaults to
+	// "/oauth2", a missing leading slash is added, and a trailing slash is
+	// trimmed ("/" yields a root mount). The .well-known endpoints are not
+	// affected — they live at the host root per RFC 8615.
+	RoutePrefix string
+	// Now is the clock used to stamp issuance / expiry. Defaults to
+	// time.Now (wall clock); inject a fixed clock in tests.
+	Now func() time.Time
+}
+
+// Server is the OAuth2 authorization server. It exposes one
+// http.Handler per RFC endpoint; users mount them into their router of
+// choice.
+type Server struct {
+	cfg ServerConfig
+
+	// dispatch maps Grant.Type() to the Grant instance for O(1) lookup
+	// on /token.
+	dispatch map[string]Grant
+}
+
+// NewServer validates cfg and returns a ready-to-mount [Server]. It
+// returns an error when the configuration is internally inconsistent
+// (no storage, no client store, ...).
+func NewServer(cfg ServerConfig) (*Server, error) {
+	if cfg.Storage == nil {
+		return nil, errors.New("oauth2: NewServer: Storage is required")
+	}
+
+	if cfg.ClientStore == nil {
+		return nil, errors.New("oauth2: NewServer: ClientStore is required")
+	}
+
+	if cfg.IssuerResolver == nil {
+		return nil, errors.New("oauth2: NewServer: IssuerResolver is required")
+	}
+
+	if len(cfg.ClientAuth) == 0 {
+		return nil, errors.New("oauth2: NewServer: at least one ClientAuthenticator is required")
+	}
+
+	if cfg.Now == nil {
+		cfg.Now = time.Now
+	}
+
+	cfg.RoutePrefix = normalizeRoutePrefix(cfg.RoutePrefix)
+
+	s := &Server{cfg: cfg, dispatch: make(map[string]Grant, len(cfg.Grants))}
+	for _, g := range cfg.Grants {
+		if _, dup := s.dispatch[g.Type()]; dup {
+			return nil, fmt.Errorf("oauth2: NewServer: duplicate grant type %q", g.Type())
+		}
+
+		s.dispatch[g.Type()] = g
+	}
+
+	if err := profileConstraints(cfg.Profile, cfg.Grants); err != nil {
+		return nil, err
+	}
+
+	return s, nil
+}
+
+// Config returns the configuration the server was constructed with. Useful
+// for endpoints (metadata, jwks) that need to introspect it.
+func (s *Server) Config() ServerConfig { return s.cfg }
+
+// authenticateClient runs the configured client-authentication methods in
+// order and returns the first match.
+func (s *Server) authenticateClient(ctx context.Context, r *http.Request) (Client, error) {
+	for _, m := range s.cfg.ClientAuth {
+		if !m.Match(r) {
+			continue
+		}
+
+		c, err := m.Authenticate(ctx, r, s.cfg.ClientStore)
+		if err != nil {
+			return nil, fmt.Errorf("oauth2.Server: client auth: %w", err)
+		}
+
+		return c, nil
+	}
+
+	return nil, ErrInvalidClient.WithDescription("no client authentication method matched")
+}
+
+// resolveIssuer wraps IssuerResolver.Resolve, translating its error to the
+// canonical oauth2.Error envelope when present.
+func (s *Server) resolveIssuer(ctx context.Context, r *http.Request) (string, string, error) {
+	iss, aud, err := s.cfg.IssuerResolver.Resolve(ctx, r)
+	if err != nil {
+		return "", "", ErrServerError.WithCause(err)
+	}
+
+	return iss, aud, nil
+}
+
+// profileConstraints enforces the profile-specific bans (e.g. legacy
+// grants refused outside Profile20).
+func profileConstraints(p Profile, grants []Grant) error {
+	if p.AllowsLegacyGrant() {
+		return nil
+	}
+
+	for _, g := range grants {
+		switch g.Type() {
+		case "password", "implicit":
+			return fmt.Errorf("oauth2: profile %s forbids grant %q", p, g.Type())
+		}
+	}
+
+	return nil
+}
diff --git a/oauth2/server_test.go b/oauth2/server_test.go
new file mode 100644
index 0000000..d82b034
--- /dev/null
+++ b/oauth2/server_test.go
@@ -0,0 +1,639 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/clientauth"
+	"github.com/hyperscale-stack/security/oauth2/grant"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	testClientID     = "client-abc"
+	testClientSecret = "secret-xyz"
+)
+
+// staticClientStore is a tiny in-memory [oauth2.ClientStore].
+type staticClientStore struct{ clients map[string]oauth2.Client }
+
+func (s *staticClientStore) LoadClient(_ context.Context, id string) (oauth2.Client, error) {
+	c, ok := s.clients[id]
+	if !ok {
+		return nil, nil
+	}
+
+	return c, nil
+}
+
+// failingIssuer is an [oauth2.IssuerResolver] that always errors.
+type failingIssuer struct{}
+
+func (failingIssuer) Resolve(context.Context, *http.Request) (string, string, error) {
+	return "", "", errors.New("issuer backend down")
+}
+
+// legacyGrant registers a grant_type without a real implementation — enough
+// for the profile-constraint check at NewServer time.
+type legacyGrant struct{ typ string }
+
+func (g legacyGrant) Type() string { return g.typ }
+func (g legacyGrant) Handle(context.Context, oauth2.GrantRequest) (*oauth2.GrantResponse, error) {
+	return nil, oauth2.ErrServerError
+}
+
+func newTestServer(t *testing.T) (*oauth2.Server, *memory.Store) {
+	t.Helper()
+
+	store := memory.New()
+	clients := &staticClientStore{clients: map[string]oauth2.Client{
+		testClientID: &oauth2.DefaultClient{
+			IDValue:     testClientID,
+			Secret:      testClientSecret,
+			TypeValue:   oauth2.ClientConfidential,
+			ScopeValues: []string{"api:read"},
+		},
+	}}
+
+	cfg := grant.Config{
+		Storage:             store,
+		AccessTokens:        token.NewOpaque(32),
+		RefreshTokens:       token.OpaqueRefreshAdapter{Opaque: token.NewOpaque(32)},
+		AccessTTL:           time.Hour,
+		RefreshTTL:          24 * time.Hour,
+		RotateRefreshTokens: true,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile:        oauth2.Profile20BCP,
+		Storage:        store,
+		ClientStore:    clients,
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		Grants:         []oauth2.Grant{grant.NewClientCredentials(cfg), grant.NewRefreshToken(cfg)},
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic(), clientauth.NewPost()},
+	})
+	require.NoError(t, err)
+
+	return srv, store
+}
+
+// formRequest builds a POST x-www-form-urlencoded request with Basic auth.
+func formRequest(path string, form url.Values, withAuth bool) *http.Request {
+	req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	if withAuth {
+		req.SetBasicAuth(testClientID, testClientSecret)
+	}
+
+	return req
+}
+
+func TestNewServerValidation(t *testing.T) {
+	t.Parallel()
+
+	store := memory.New()
+	clients := &staticClientStore{}
+	iss := oauth2.StaticIssuer("https://auth.example", "api")
+	auth := []oauth2.ClientAuthenticator{clientauth.NewBasic()}
+
+	cases := []struct {
+		name string
+		cfg  oauth2.ServerConfig
+	}{
+		{"missing storage", oauth2.ServerConfig{ClientStore: clients, IssuerResolver: iss, ClientAuth: auth}},
+		{"missing client store", oauth2.ServerConfig{Storage: store, IssuerResolver: iss, ClientAuth: auth}},
+		{"missing issuer", oauth2.ServerConfig{Storage: store, ClientStore: clients, ClientAuth: auth}},
+		{"missing client auth", oauth2.ServerConfig{Storage: store, ClientStore: clients, IssuerResolver: iss}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := oauth2.NewServer(tc.cfg)
+			require.Error(t, err)
+		})
+	}
+}
+
+func TestNewServerDuplicateGrantType(t *testing.T) {
+	t.Parallel()
+
+	_, err := oauth2.NewServer(oauth2.ServerConfig{
+		Storage:        memory.New(),
+		ClientStore:    &staticClientStore{},
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+		Grants:         []oauth2.Grant{legacyGrant{typ: "client_credentials"}, legacyGrant{typ: "client_credentials"}},
+		Profile:        oauth2.Profile20,
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "duplicate grant type")
+}
+
+func TestNewServerProfileConstraints(t *testing.T) {
+	t.Parallel()
+
+	base := oauth2.ServerConfig{
+		Storage:        memory.New(),
+		ClientStore:    &staticClientStore{},
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+	}
+
+	// BCP refuses the legacy password / implicit grants.
+	for _, legacy := range []string{"password", "implicit"} {
+		cfg := base
+		cfg.Profile = oauth2.Profile20BCP
+		cfg.Grants = []oauth2.Grant{legacyGrant{typ: legacy}}
+
+		_, err := oauth2.NewServer(cfg)
+		require.Error(t, err, legacy)
+		assert.Contains(t, err.Error(), legacy)
+	}
+
+	// Profile20 allows them.
+	cfg := base
+	cfg.Profile = oauth2.Profile20
+	cfg.Grants = []oauth2.Grant{legacyGrant{typ: "password"}}
+
+	_, err := oauth2.NewServer(cfg)
+	require.NoError(t, err)
+}
+
+func TestServerConfigDefaultsClock(t *testing.T) {
+	t.Parallel()
+
+	srv, _ := newTestServer(t)
+	assert.NotNil(t, srv.Config().Now, "NewServer defaults Now to time.Now")
+}
+
+func TestTokenEndpoint(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GET is rejected", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.TokenHandler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/oauth2/token", nil))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+	})
+
+	t.Run("missing client auth is 401", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.TokenHandler().ServeHTTP(rec,
+			formRequest("/oauth2/token", url.Values{"grant_type": {"client_credentials"}}, false))
+		assert.Equal(t, http.StatusUnauthorized, rec.Code)
+	})
+
+	t.Run("missing grant_type is 400 invalid_request", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.TokenHandler().ServeHTTP(rec, formRequest("/oauth2/token", url.Values{}, true))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+		assert.Equal(t, oauth2.CodeInvalidRequest, decodeError(t, rec))
+	})
+
+	t.Run("unsupported grant_type is 400", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.TokenHandler().ServeHTTP(rec,
+			formRequest("/oauth2/token", url.Values{"grant_type": {"password"}}, true))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+		assert.Equal(t, oauth2.CodeUnsupportedGrantType, decodeError(t, rec))
+	})
+
+	t.Run("client_credentials success", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.TokenHandler().ServeHTTP(rec, formRequest("/oauth2/token",
+			url.Values{"grant_type": {"client_credentials"}, "scope": {"api:read"}}, true))
+
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var body map[string]any
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+		assert.NotEmpty(t, body["access_token"])
+		assert.Equal(t, "Bearer", body["token_type"])
+	})
+}
+
+func TestTokenEndpointIssuerError(t *testing.T) {
+	t.Parallel()
+
+	store := memory.New()
+	cfg := grant.Config{
+		Storage:      store,
+		AccessTokens: token.NewOpaque(32),
+		AccessTTL:    time.Hour,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Storage:     store,
+		ClientStore: &staticClientStore{clients: map[string]oauth2.Client{
+			testClientID: &oauth2.DefaultClient{IDValue: testClientID, Secret: testClientSecret},
+		}},
+		IssuerResolver: failingIssuer{},
+		Grants:         []oauth2.Grant{grant.NewClientCredentials(cfg)},
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+	})
+	require.NoError(t, err)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec,
+		formRequest("/oauth2/token", url.Values{"grant_type": {"client_credentials"}}, true))
+
+	assert.Equal(t, http.StatusInternalServerError, rec.Code)
+	assert.Equal(t, oauth2.CodeServerError, decodeError(t, rec))
+}
+
+func TestRevokeEndpoint(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GET is rejected", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.RevokeHandler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/oauth2/revoke", nil))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+	})
+
+	t.Run("missing token is 400", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.RevokeHandler().ServeHTTP(rec, formRequest("/oauth2/revoke", url.Values{}, true))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+	})
+
+	t.Run("unknown token still returns 200", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.RevokeHandler().ServeHTTP(rec,
+			formRequest("/oauth2/revoke", url.Values{"token": {"nope"}}, true))
+		assert.Equal(t, http.StatusOK, rec.Code)
+	})
+
+	t.Run("revokes a stored access token of the family", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		ctx := context.Background()
+		require.NoError(t, store.SaveAccessToken(ctx, &oauth2.AccessToken{
+			TokenHash: oauth2.HashToken(nil, "raw-access"),
+			ClientID:  testClientID,
+			FamilyID:  "fam-1",
+			ExpiresAt: time.Now().Add(time.Hour),
+		}))
+
+		rec := httptest.NewRecorder()
+		srv.RevokeHandler().ServeHTTP(rec,
+			formRequest("/oauth2/revoke", url.Values{"token": {"raw-access"}}, true))
+		assert.Equal(t, http.StatusOK, rec.Code)
+
+		_, err := store.LookupAccessToken(ctx, oauth2.HashToken(nil, "raw-access"))
+		assert.Error(t, err, "access token must be revoked")
+	})
+
+	t.Run("revokes a stored refresh token family", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		ctx := context.Background()
+		require.NoError(t, store.SaveRefreshToken(ctx, &oauth2.RefreshToken{
+			TokenHash: oauth2.HashToken(nil, "raw-refresh"),
+			ClientID:  testClientID,
+			FamilyID:  "fam-2",
+			ExpiresAt: time.Now().Add(time.Hour),
+		}))
+
+		rec := httptest.NewRecorder()
+		srv.RevokeHandler().ServeHTTP(rec,
+			formRequest("/oauth2/revoke", url.Values{"token": {"raw-refresh"}}, true))
+		assert.Equal(t, http.StatusOK, rec.Code)
+	})
+}
+
+func TestIntrospectEndpoint(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GET is rejected", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.IntrospectHandler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/oauth2/introspect", nil))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+	})
+
+	t.Run("missing token is 400", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.IntrospectHandler().ServeHTTP(rec, formRequest("/oauth2/introspect", url.Values{}, true))
+		assert.Equal(t, http.StatusBadRequest, rec.Code)
+	})
+
+	t.Run("unknown token is inactive", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		assert.False(t, introspect(t, srv, "ghost")["active"].(bool))
+	})
+
+	t.Run("active access token is active", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		require.NoError(t, store.SaveAccessToken(context.Background(), &oauth2.AccessToken{
+			TokenHash: oauth2.HashToken(nil, "live-at"),
+			ClientID:  testClientID,
+			Subject:   "user-1",
+			Scope:     "api:read",
+			IssuedAt:  time.Now().Add(-time.Minute),
+			ExpiresAt: time.Now().Add(time.Hour),
+		}))
+
+		body := introspect(t, srv, "live-at")
+		assert.True(t, body["active"].(bool))
+		assert.Equal(t, "Bearer", body["token_type"])
+		assert.Equal(t, "user-1", body["sub"])
+	})
+
+	t.Run("expired access token is inactive", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		require.NoError(t, store.SaveAccessToken(context.Background(), &oauth2.AccessToken{
+			TokenHash: oauth2.HashToken(nil, "dead-at"),
+			ClientID:  testClientID,
+			ExpiresAt: time.Now().Add(-time.Hour),
+		}))
+		assert.False(t, introspect(t, srv, "dead-at")["active"].(bool))
+	})
+
+	t.Run("active refresh token is active", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		require.NoError(t, store.SaveRefreshToken(context.Background(), &oauth2.RefreshToken{
+			TokenHash: oauth2.HashToken(nil, "live-rt"),
+			ClientID:  testClientID,
+			ExpiresAt: time.Now().Add(time.Hour),
+		}))
+
+		body := introspect(t, srv, "live-rt")
+		assert.True(t, body["active"].(bool))
+		assert.Equal(t, "refresh_token", body["token_type"])
+	})
+
+	t.Run("consumed refresh token is inactive", func(t *testing.T) {
+		t.Parallel()
+
+		srv, store := newTestServer(t)
+		require.NoError(t, store.SaveRefreshToken(context.Background(), &oauth2.RefreshToken{
+			TokenHash: oauth2.HashToken(nil, "used-rt"),
+			ClientID:  testClientID,
+			ExpiresAt: time.Now().Add(time.Hour),
+			Consumed:  true,
+		}))
+		assert.False(t, introspect(t, srv, "used-rt")["active"].(bool))
+	})
+}
+
+func TestMetadataEndpoint(t *testing.T) {
+	t.Parallel()
+
+	t.Run("advertises configuration", func(t *testing.T) {
+		t.Parallel()
+
+		srv, _ := newTestServer(t)
+		rec := httptest.NewRecorder()
+		srv.MetadataHandler().ServeHTTP(rec,
+			httptest.NewRequest(http.MethodGet, "/.well-known/oauth-authorization-server", nil))
+
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var body map[string]any
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+		assert.Equal(t, "https://auth.example", body["issuer"])
+		assert.Equal(t, "https://auth.example/oauth2/token", body["token_endpoint"])
+		assert.Equal(t, []any{"S256"}, body["code_challenge_methods_supported"])
+	})
+
+	t.Run("issuer error is 500", func(t *testing.T) {
+		t.Parallel()
+
+		store := memory.New()
+		srv, err := oauth2.NewServer(oauth2.ServerConfig{
+			Storage:        store,
+			ClientStore:    &staticClientStore{},
+			IssuerResolver: failingIssuer{},
+			ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+		})
+		require.NoError(t, err)
+
+		rec := httptest.NewRecorder()
+		srv.MetadataHandler().ServeHTTP(rec,
+			httptest.NewRequest(http.MethodGet, "/.well-known/oauth-authorization-server", nil))
+		assert.Equal(t, http.StatusInternalServerError, rec.Code)
+	})
+}
+
+// decodeError extracts the "error" field of an RFC 6749 §5.2 envelope.
+func decodeError(t *testing.T, rec *httptest.ResponseRecorder) string {
+	t.Helper()
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+
+	code, _ := body["error"].(string)
+
+	return code
+}
+
+// introspect POSTs token to /introspect and returns the decoded body.
+func introspect(t *testing.T, srv *oauth2.Server, raw string) map[string]any {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+	srv.IntrospectHandler().ServeHTTP(rec,
+		formRequest("/oauth2/introspect", url.Values{"token": {raw}}, true))
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+
+	return body
+}
+
+func TestMetadataRoutePrefix(t *testing.T) {
+	t.Parallel()
+
+	const issuer = "https://auth.example"
+
+	build := func(t *testing.T, prefix string) *oauth2.Server {
+		t.Helper()
+
+		srv, err := oauth2.NewServer(oauth2.ServerConfig{
+			Storage:        memory.New(),
+			ClientStore:    &staticClientStore{},
+			IssuerResolver: oauth2.StaticIssuer(issuer, "api"),
+			ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+			RoutePrefix:    prefix,
+		})
+		require.NoError(t, err)
+
+		return srv
+	}
+
+	doc := func(t *testing.T, srv *oauth2.Server) map[string]any {
+		t.Helper()
+
+		rec := httptest.NewRecorder()
+		srv.MetadataHandler().ServeHTTP(rec,
+			httptest.NewRequest(http.MethodGet, "/.well-known/oauth-authorization-server", nil))
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var body map[string]any
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+
+		return body
+	}
+
+	cases := []struct {
+		name   string
+		prefix string
+		want   string // normalized prefix
+	}{
+		{"default", "", "/oauth2"},
+		{"custom", "/auth", "/auth"},
+		{"missing leading slash", "auth", "/auth"},
+		{"trailing slash", "/auth/", "/auth"},
+		{"root mount", "/", ""},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			srv := build(t, tc.prefix)
+
+			// The normalized prefix is what the config reports back.
+			assert.Equal(t, tc.want, srv.Config().RoutePrefix)
+
+			body := doc(t, srv)
+			routes := issuer + tc.want
+
+			assert.Equal(t, routes+"/token", body["token_endpoint"])
+			assert.Equal(t, routes+"/revoke", body["revocation_endpoint"])
+			assert.Equal(t, routes+"/introspect", body["introspection_endpoint"])
+			assert.Equal(t, routes+"/authorize", body["authorization_endpoint"])
+
+			// jwks_uri keeps the host-root .well-known location regardless.
+			assert.Equal(t, issuer+"/.well-known/jwks.json", body["jwks_uri"])
+		})
+	}
+}
+
+// passwordVerifier is a ResourceOwnerVerifier accepting a single account.
+type passwordVerifier struct{}
+
+func (passwordVerifier) VerifyResourceOwner(_ context.Context, username, password string) (string, error) {
+	if username == "alice" && password == "s3cr3t" {
+		return "alice", nil
+	}
+
+	return "", errors.New("invalid credentials")
+}
+
+// TestTokenEndpointLegacyPasswordGrant wires the opt-in legacy password
+// grant under Profile20 and exercises it end-to-end through /token.
+func TestTokenEndpointLegacyPasswordGrant(t *testing.T) {
+	t.Parallel()
+
+	store := memory.New()
+	cfg := grant.Config{
+		Storage: store, AccessTokens: token.NewOpaque(32), AccessTTL: time.Hour,
+	}
+
+	srv, err := oauth2.NewServer(oauth2.ServerConfig{
+		Profile: oauth2.Profile20, // legacy grants are accepted only here
+		Storage: store,
+		ClientStore: &staticClientStore{clients: map[string]oauth2.Client{
+			testClientID: &oauth2.DefaultClient{
+				IDValue: testClientID, Secret: testClientSecret, TypeValue: oauth2.ClientConfidential,
+			},
+		}},
+		IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+		Grants:         []oauth2.Grant{grant.NewLegacyPassword(cfg, passwordVerifier{})},
+		ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+	})
+	require.NoError(t, err)
+
+	rec := httptest.NewRecorder()
+	srv.TokenHandler().ServeHTTP(rec, formRequest("/oauth2/token",
+		url.Values{"grant_type": {"password"}, "username": {"alice"}, "password": {"s3cr3t"}}, true))
+
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var body map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.NotEmpty(t, body["access_token"])
+	assert.Equal(t, "Bearer", body["token_type"])
+}
+
+// TestNewServerRefusesLegacyPasswordOutsideProfile20 confirms the opt-in
+// legacy grant is rejected at construction under the BCP / 2.1 profiles.
+func TestNewServerRefusesLegacyPasswordOutsideProfile20(t *testing.T) {
+	t.Parallel()
+
+	store := memory.New()
+	cfg := grant.Config{
+		Storage: store, AccessTokens: token.NewOpaque(32), AccessTTL: time.Hour,
+	}
+
+	for _, profile := range []oauth2.Profile{oauth2.Profile20BCP, oauth2.Profile21Draft} {
+		_, err := oauth2.NewServer(oauth2.ServerConfig{
+			Profile:        profile,
+			Storage:        store,
+			ClientStore:    &staticClientStore{},
+			IssuerResolver: oauth2.StaticIssuer("https://auth.example", "api"),
+			Grants:         []oauth2.Grant{grant.NewLegacyPassword(cfg, passwordVerifier{})},
+			ClientAuth:     []oauth2.ClientAuthenticator{clientauth.NewBasic()},
+		})
+		require.Error(t, err, profile)
+		assert.Contains(t, err.Error(), "password")
+	}
+}
diff --git a/oauth2/storage.go b/oauth2/storage.go
new file mode 100644
index 0000000..829eedb
--- /dev/null
+++ b/oauth2/storage.go
@@ -0,0 +1,63 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import "context"
+
+// AuthorizationCodeStore persists single-use authorization codes. The
+// Consume* operation MUST be atomic: a code may be returned successfully
+// to AT MOST one caller.
+type AuthorizationCodeStore interface {
+	// SaveAuthorizationCode persists the code. The storage layer hashes
+	// code.Code into code.CodeHash before persisting.
+	SaveAuthorizationCode(ctx context.Context, code *AuthorizationCode) error
+
+	// ConsumeAuthorizationCode atomically reads-and-deletes the code
+	// identified by codeHash. Returns [ErrCodeAlreadyUsed] when the code
+	// was previously consumed (allowing the server to reject reuse with
+	// invalid_grant and revoke the resulting access token per RFC 6749
+	// §4.1.2).
+	ConsumeAuthorizationCode(ctx context.Context, codeHash string) (*AuthorizationCode, error)
+}
+
+// AccessTokenStore persists access tokens. Implementations MUST store hashes
+// (the canonical hash function is [HashToken]).
+type AccessTokenStore interface {
+	SaveAccessToken(ctx context.Context, t *AccessToken) error
+	// LookupAccessToken returns the token record matching tokenHash, or
+	// nil + ErrInvalidGrant when none matches.
+	LookupAccessToken(ctx context.Context, tokenHash string) (*AccessToken, error)
+	RevokeAccessToken(ctx context.Context, tokenHash string) error
+}
+
+// RefreshTokenStore persists refresh tokens. The rotation operation MUST
+// be atomic: rotating a token consumed elsewhere MUST fail with
+// [ErrRefreshTokenReused] and trigger family revocation.
+type RefreshTokenStore interface {
+	SaveRefreshToken(ctx context.Context, t *RefreshToken) error
+	// RotateRefreshToken atomically marks oldHash as consumed and persists
+	// next as the active refresh token. Returns the new TokenPair on
+	// success, ErrRefreshTokenReused when oldHash was already consumed
+	// (in which case the implementation MUST also call
+	// [RevokeRefreshFamily] for the offending FamilyID before returning).
+	RotateRefreshToken(ctx context.Context, oldHash string, next *RefreshToken) error
+	// LookupRefreshToken returns the refresh-token record matching
+	// tokenHash, or nil + ErrInvalidGrant when none matches. Consumed
+	// tokens MUST be returned with Consumed=true so the caller can treat
+	// them as reuse.
+	LookupRefreshToken(ctx context.Context, tokenHash string) (*RefreshToken, error)
+	// RevokeRefreshFamily marks every refresh token in familyID as
+	// consumed AND revokes every access token whose FamilyID matches.
+	RevokeRefreshFamily(ctx context.Context, familyID string) error
+}
+
+// Storage groups the per-aspect interfaces. Implementations MAY decide to
+// satisfy individual sub-interfaces with different backends (e.g. SQL for
+// authorization codes, Redis for tokens).
+type Storage interface {
+	AuthorizationCodeStore
+	AccessTokenStore
+	RefreshTokenStore
+}
diff --git a/oauth2/storage/memory/conformance_test.go b/oauth2/storage/memory/conformance_test.go
new file mode 100644
index 0000000..61f1f2e
--- /dev/null
+++ b/oauth2/storage/memory/conformance_test.go
@@ -0,0 +1,24 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package memory_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/storetest"
+)
+
+// TestMemoryStoreConformance runs the shared storage contract against the
+// in-memory implementation. The same suite runs against the SQL and Redis
+// stores so behavioural drift between backends fails CI.
+func TestMemoryStoreConformance(t *testing.T) {
+	t.Parallel()
+
+	storetest.RunConformance(t, func() oauth2.Storage {
+		return memory.New()
+	})
+}
diff --git a/oauth2/storage/memory/memory.go b/oauth2/storage/memory/memory.go
new file mode 100644
index 0000000..47a5456
--- /dev/null
+++ b/oauth2/storage/memory/memory.go
@@ -0,0 +1,217 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package memory ships an in-process [oauth2.Storage] implementation
+// suitable for tests, examples and small single-instance deployments.
+// Production deployments MUST use the SQL or Redis implementations
+// instead — the in-memory store loses all state on restart.
+//
+// All operations are guarded by a single sync.Mutex; the resulting
+// throughput is fine for tens of thousands of req/s but the structure is
+// optimized for clarity, not for scale.
+package memory
+
+import (
+	"context"
+	"sync"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// Store is an in-memory [oauth2.Storage]. The zero value is unusable;
+// build one with [New].
+type Store struct {
+	mu       sync.Mutex
+	codes    map[string]oauth2.AuthorizationCode
+	access   map[string]oauth2.AccessToken
+	refresh  map[string]oauth2.RefreshToken
+	families map[string][]string // familyID -> refresh-token hashes (for revocation)
+}
+
+// New returns a fresh [Store].
+func New() *Store {
+	return &Store{
+		codes:    make(map[string]oauth2.AuthorizationCode),
+		access:   make(map[string]oauth2.AccessToken),
+		refresh:  make(map[string]oauth2.RefreshToken),
+		families: make(map[string][]string),
+	}
+}
+
+// SaveAuthorizationCode implements [oauth2.AuthorizationCodeStore].
+func (s *Store) SaveAuthorizationCode(_ context.Context, code *oauth2.AuthorizationCode) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if code.CodeHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("storage: empty code hash")
+	}
+
+	s.codes[code.CodeHash] = *code
+
+	return nil
+}
+
+// ConsumeAuthorizationCode implements [oauth2.AuthorizationCodeStore]. The
+// operation is atomic under the store's mutex.
+func (s *Store) ConsumeAuthorizationCode(_ context.Context, codeHash string) (*oauth2.AuthorizationCode, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	c, ok := s.codes[codeHash]
+	if !ok {
+		return nil, oauth2.ErrCodeAlreadyUsed
+	}
+
+	delete(s.codes, codeHash)
+
+	// Expiry is NOT checked here: the store only guarantees atomic
+	// single-use read+delete. The grant handler validates IsExpired with
+	// its injected clock — keeping the check in one place avoids the
+	// store and the grant disagreeing on "now".
+	cp := c
+
+	return &cp, nil
+}
+
+// SaveAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) SaveAccessToken(_ context.Context, t *oauth2.AccessToken) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("storage: empty access token hash")
+	}
+
+	s.access[t.TokenHash] = *t
+
+	return nil
+}
+
+// LookupAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) LookupAccessToken(_ context.Context, tokenHash string) (*oauth2.AccessToken, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	t, ok := s.access[tokenHash]
+	if !ok {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("access token not found")
+	}
+
+	cp := t
+
+	return &cp, nil
+}
+
+// RevokeAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) RevokeAccessToken(_ context.Context, tokenHash string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	delete(s.access, tokenHash)
+
+	return nil
+}
+
+// SaveRefreshToken implements [oauth2.RefreshTokenStore]. The token is
+// registered in its family so that subsequent revocation can iterate every
+// sibling.
+func (s *Store) SaveRefreshToken(_ context.Context, t *oauth2.RefreshToken) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("storage: empty refresh token hash")
+	}
+
+	s.refresh[t.TokenHash] = *t
+
+	if t.FamilyID != "" {
+		s.families[t.FamilyID] = append(s.families[t.FamilyID], t.TokenHash)
+	}
+
+	return nil
+}
+
+// LookupRefreshToken implements [oauth2.RefreshTokenStore].
+func (s *Store) LookupRefreshToken(_ context.Context, tokenHash string) (*oauth2.RefreshToken, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	t, ok := s.refresh[tokenHash]
+	if !ok {
+		return nil, oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+	}
+
+	cp := t
+
+	return &cp, nil
+}
+
+// RotateRefreshToken implements [oauth2.RefreshTokenStore]. The atomic
+// sequence under the store's mutex is:
+//
+//  1. Look up the old token; if missing -> ErrInvalidGrant.
+//  2. If the old token is already consumed -> revoke the entire family and
+//     return [oauth2.ErrRefreshTokenReused] (BCP §8.10.3).
+//  3. Mark the old token as consumed, save the new token, register it in
+//     the same family.
+func (s *Store) RotateRefreshToken(ctx context.Context, oldHash string, next *oauth2.RefreshToken) error {
+	s.mu.Lock()
+
+	old, ok := s.refresh[oldHash]
+	if !ok {
+		s.mu.Unlock()
+
+		return oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+	}
+
+	if old.Consumed {
+		family := old.FamilyID
+
+		s.mu.Unlock()
+
+		_ = s.RevokeRefreshFamily(ctx, family)
+
+		return oauth2.ErrRefreshTokenReused
+	}
+
+	old.Consumed = true
+	s.refresh[oldHash] = old
+	s.refresh[next.TokenHash] = *next
+
+	if next.FamilyID != "" {
+		s.families[next.FamilyID] = append(s.families[next.FamilyID], next.TokenHash)
+	}
+
+	s.mu.Unlock()
+
+	return nil
+}
+
+// RevokeRefreshFamily implements [oauth2.RefreshTokenStore]. Every refresh
+// token in the family is marked consumed and every access token whose
+// FamilyID matches is removed.
+func (s *Store) RevokeRefreshFamily(_ context.Context, familyID string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	for _, hash := range s.families[familyID] {
+		if t, ok := s.refresh[hash]; ok {
+			t.Consumed = true
+			s.refresh[hash] = t
+		}
+	}
+
+	for hash, t := range s.access {
+		if t.FamilyID == familyID {
+			delete(s.access, hash)
+		}
+	}
+
+	return nil
+}
+
+// Compile-time interface check.
+var _ oauth2.Storage = (*Store)(nil)
diff --git a/oauth2/store/redis/codec.go b/oauth2/store/redis/codec.go
new file mode 100644
index 0000000..8df83f9
--- /dev/null
+++ b/oauth2/store/redis/codec.go
@@ -0,0 +1,168 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package redisstore
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// marshalJSON wraps json.Marshal so callers return a package-scoped error
+// (satisfying wrapcheck) rather than the bare encoding/json error.
+func marshalJSON(v any) ([]byte, error) {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return nil, fmt.Errorf("redisstore: marshal: %w", err)
+	}
+
+	return b, nil
+}
+
+// The DTO types below are the on-wire JSON shapes persisted in Redis. They
+// deliberately omit the raw Token / Code fields — only hashes are keys, and
+// the raw secret is never stored. Timestamps are Unix seconds for compact,
+// unambiguous encoding. The `consumed` field name is load-bearing: the
+// rotate-refresh Lua script reads it via cjson.
+
+type codeDTO struct {
+	ClientID            string `json:"client_id"`
+	Subject             string `json:"subject"`
+	RedirectURI         string `json:"redirect_uri"`
+	Scope               string `json:"scope"`
+	CodeChallenge       string `json:"code_challenge"`
+	CodeChallengeMethod string `json:"code_challenge_method"`
+	Nonce               string `json:"nonce"`
+	IssuedAt            int64  `json:"issued_at"`
+	ExpiresAt           int64  `json:"expires_at"`
+}
+
+func encodeCode(c *oauth2.AuthorizationCode) ([]byte, error) {
+	return marshalJSON(codeDTO{
+		ClientID:            c.ClientID,
+		Subject:             c.Subject,
+		RedirectURI:         c.RedirectURI,
+		Scope:               c.Scope,
+		CodeChallenge:       c.CodeChallenge,
+		CodeChallengeMethod: c.CodeChallengeMethod,
+		Nonce:               c.Nonce,
+		IssuedAt:            c.IssuedAt.Unix(),
+		ExpiresAt:           c.ExpiresAt.Unix(),
+	})
+}
+
+func decodeCode(hash string, raw []byte) (*oauth2.AuthorizationCode, error) {
+	var d codeDTO
+	if err := json.Unmarshal(raw, &d); err != nil {
+		return nil, err //nolint:wrapcheck // caller wraps
+	}
+
+	return &oauth2.AuthorizationCode{
+		CodeHash:            hash,
+		ClientID:            d.ClientID,
+		Subject:             d.Subject,
+		RedirectURI:         d.RedirectURI,
+		Scope:               d.Scope,
+		CodeChallenge:       d.CodeChallenge,
+		CodeChallengeMethod: d.CodeChallengeMethod,
+		Nonce:               d.Nonce,
+		IssuedAt:            time.Unix(d.IssuedAt, 0),
+		ExpiresAt:           time.Unix(d.ExpiresAt, 0),
+	}, nil
+}
+
+type accessDTO struct {
+	ClientID  string `json:"client_id"`
+	Subject   string `json:"subject"`
+	Scope     string `json:"scope"`
+	FamilyID  string `json:"family_id"`
+	Audience  string `json:"audience"`
+	IssuedAt  int64  `json:"issued_at"`
+	ExpiresAt int64  `json:"expires_at"`
+}
+
+func encodeAccess(t *oauth2.AccessToken) ([]byte, error) {
+	return marshalJSON(accessDTO{
+		ClientID:  t.ClientID,
+		Subject:   t.Subject,
+		Scope:     t.Scope,
+		FamilyID:  t.FamilyID,
+		Audience:  t.Audience,
+		IssuedAt:  t.IssuedAt.Unix(),
+		ExpiresAt: t.ExpiresAt.Unix(),
+	})
+}
+
+func decodeAccess(hash string, raw []byte) (*oauth2.AccessToken, error) {
+	var d accessDTO
+	if err := json.Unmarshal(raw, &d); err != nil {
+		return nil, err //nolint:wrapcheck // caller wraps
+	}
+
+	return &oauth2.AccessToken{
+		TokenHash: hash,
+		ClientID:  d.ClientID,
+		Subject:   d.Subject,
+		Scope:     d.Scope,
+		FamilyID:  d.FamilyID,
+		Audience:  d.Audience,
+		IssuedAt:  time.Unix(d.IssuedAt, 0),
+		ExpiresAt: time.Unix(d.ExpiresAt, 0),
+	}, nil
+}
+
+type refreshDTO struct {
+	ClientID  string `json:"client_id"`
+	Subject   string `json:"subject"`
+	Scope     string `json:"scope"`
+	FamilyID  string `json:"family_id"`
+	Consumed  bool   `json:"consumed"`
+	IssuedAt  int64  `json:"issued_at"`
+	ExpiresAt int64  `json:"expires_at"`
+}
+
+func encodeRefresh(t *oauth2.RefreshToken) ([]byte, error) {
+	return marshalJSON(refreshDTO{
+		ClientID:  t.ClientID,
+		Subject:   t.Subject,
+		Scope:     t.Scope,
+		FamilyID:  t.FamilyID,
+		Consumed:  t.Consumed,
+		IssuedAt:  t.IssuedAt.Unix(),
+		ExpiresAt: t.ExpiresAt.Unix(),
+	})
+}
+
+func decodeRefresh(hash string, raw []byte) (*oauth2.RefreshToken, error) {
+	var d refreshDTO
+	if err := json.Unmarshal(raw, &d); err != nil {
+		return nil, err //nolint:wrapcheck // caller wraps
+	}
+
+	return &oauth2.RefreshToken{
+		TokenHash: hash,
+		ClientID:  d.ClientID,
+		Subject:   d.Subject,
+		Scope:     d.Scope,
+		FamilyID:  d.FamilyID,
+		Consumed:  d.Consumed,
+		IssuedAt:  time.Unix(d.IssuedAt, 0),
+		ExpiresAt: time.Unix(d.ExpiresAt, 0),
+	}, nil
+}
+
+// ttlUntil returns the duration from now until t, clamped to a 1-second
+// minimum so a token that is technically already expired still gets a
+// short-lived key (the grant layer rejects it on its own clock anyway).
+func ttlUntil(t time.Time) time.Duration {
+	d := time.Until(t)
+	if d < time.Second {
+		return time.Second
+	}
+
+	return d
+}
diff --git a/oauth2/store/redis/doc.go b/oauth2/store/redis/doc.go
new file mode 100644
index 0000000..91c71df
--- /dev/null
+++ b/oauth2/store/redis/doc.go
@@ -0,0 +1,13 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package redisstore is a Redis implementation of oauth2.Storage. Atomicity
+// of ConsumeAuthorizationCode and RotateRefreshToken is guaranteed by Lua
+// scripts loaded via EVALSHA (with EVAL fallback).
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security/oauth2
+//   - github.com/redis/go-redis/v9
+//   - stdlib only
+package redisstore
diff --git a/oauth2/store/redis/go.mod b/oauth2/store/redis/go.mod
new file mode 100644
index 0000000..1bede00
--- /dev/null
+++ b/oauth2/store/redis/go.mod
@@ -0,0 +1,30 @@
+module github.com/hyperscale-stack/security/oauth2/store/redis
+
+go 1.26
+
+require (
+	github.com/alicebob/miniredis/v2 v2.38.0
+	github.com/hyperscale-stack/security/oauth2 v0.0.0-00010101000000-000000000000
+	github.com/redis/go-redis/v9 v9.7.0
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/yuin/gopher-lua v1.1.1 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security/oauth2 => ../../
+
+replace github.com/hyperscale-stack/security => ../../../
diff --git a/oauth2/store/redis/go.sum b/oauth2/store/redis/go.sum
new file mode 100644
index 0000000..58702c6
--- /dev/null
+++ b/oauth2/store/redis/go.sum
@@ -0,0 +1,52 @@
+github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw=
+github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.7.0 h1:HhLSs+B6O021gwzl+locl0zEDnyNkxMtf/Z3NNBMa9E=
+github.com/redis/go-redis/v9 v9.7.0/go.mod h1:f6zhXITC7JUJIlPEiBOTXxJgPLdZcA93GewI7inzyWw=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
+github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/oauth2/store/redis/store.go b/oauth2/store/redis/store.go
new file mode 100644
index 0000000..f4b3114
--- /dev/null
+++ b/oauth2/store/redis/store.go
@@ -0,0 +1,342 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package redisstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/redis/go-redis/v9"
+)
+
+// Store is a Redis-backed [oauth2.Storage]. Single-use atomicity
+// (ConsumeAuthorizationCode, RotateRefreshToken) is provided by Lua
+// scripts: a Redis Lua script runs to completion without interleaving
+// other commands, so the read-modify-write sequence is indivisible.
+type Store struct {
+	rdb    redis.UniversalClient
+	prefix string
+}
+
+// Option configures the Store.
+type Option func(*Store)
+
+// WithKeyPrefix overrides the key namespace. Default: "oauth2:".
+func WithKeyPrefix(prefix string) Option {
+	return func(s *Store) { s.prefix = prefix }
+}
+
+// New returns a [Store] bound to the given Redis client. The caller owns
+// the client's lifecycle.
+func New(rdb redis.UniversalClient, opts ...Option) (*Store, error) {
+	if rdb == nil {
+		return nil, errors.New("redisstore: New: nil redis client")
+	}
+
+	s := &Store{rdb: rdb, prefix: "oauth2:"}
+	for _, o := range opts {
+		o(s)
+	}
+
+	return s, nil
+}
+
+func (s *Store) codeKey(hash string) string { return s.prefix + "code:" + hash }
+func (s *Store) atKey(hash string) string   { return s.prefix + "at:" + hash }
+func (s *Store) rtKey(hash string) string   { return s.prefix + "rt:" + hash }
+func (s *Store) famRTKey(fam string) string { return s.prefix + "famrt:" + fam }
+func (s *Store) famATKey(fam string) string { return s.prefix + "famat:" + fam }
+
+// --- Lua scripts ---------------------------------------------------------
+
+// consumeCodeScript atomically reads-and-deletes an authorization code.
+// Returns the JSON value, or false when the key is absent.
+var consumeCodeScript = redis.NewScript(`
+local v = redis.call('GET', KEYS[1])
+if not v then return false end
+redis.call('DEL', KEYS[1])
+return v
+`)
+
+// rotateRefreshScript atomically rotates a refresh token.
+//
+//	KEYS[1] old refresh-token key
+//	KEYS[2] new refresh-token key
+//	KEYS[3] family set of refresh-token hashes
+//	ARGV[1] new refresh-token JSON
+//	ARGV[2] new refresh-token TTL (seconds)
+//	ARGV[3] new refresh-token hash
+//
+// Returns: 'ok' on success, 'notfound' when the old key is absent,
+// 'reused' when the old token was already consumed.
+var rotateRefreshScript = redis.NewScript(`
+local old = redis.call('GET', KEYS[1])
+if not old then return 'notfound' end
+local decoded = cjson.decode(old)
+if decoded.consumed then return 'reused' end
+decoded.consumed = true
+local ttl = redis.call('PTTL', KEYS[1])
+if ttl and ttl > 0 then
+  redis.call('SET', KEYS[1], cjson.encode(decoded), 'PX', ttl)
+else
+  redis.call('SET', KEYS[1], cjson.encode(decoded))
+end
+redis.call('SET', KEYS[2], ARGV[1], 'EX', tonumber(ARGV[2]))
+redis.call('SADD', KEYS[3], ARGV[3])
+return 'ok'
+`)
+
+// --- authorization codes -------------------------------------------------
+
+// SaveAuthorizationCode implements [oauth2.AuthorizationCodeStore].
+func (s *Store) SaveAuthorizationCode(ctx context.Context, code *oauth2.AuthorizationCode) error {
+	if code.CodeHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("redisstore: empty code hash")
+	}
+
+	payload, err := encodeCode(code)
+	if err != nil {
+		return fmt.Errorf("redisstore: encode code: %w", err)
+	}
+
+	if err := s.rdb.Set(ctx, s.codeKey(code.CodeHash), payload, ttlUntil(code.ExpiresAt)).Err(); err != nil {
+		return fmt.Errorf("redisstore: save authorization code: %w", err)
+	}
+
+	return nil
+}
+
+// ConsumeAuthorizationCode implements [oauth2.AuthorizationCodeStore] via
+// the consumeCode Lua script — atomic read+delete.
+func (s *Store) ConsumeAuthorizationCode(ctx context.Context, codeHash string) (*oauth2.AuthorizationCode, error) {
+	res, err := consumeCodeScript.Run(ctx, s.rdb, []string{s.codeKey(codeHash)}).Result()
+	if err != nil {
+		if errors.Is(err, redis.Nil) {
+			return nil, oauth2.ErrCodeAlreadyUsed
+		}
+
+		return nil, fmt.Errorf("redisstore: consume authorization code: %w", err)
+	}
+
+	str, ok := res.(string)
+	if !ok {
+		// The script returned false: key absent / already consumed.
+		return nil, oauth2.ErrCodeAlreadyUsed
+	}
+
+	code, err := decodeCode(codeHash, []byte(str))
+	if err != nil {
+		return nil, fmt.Errorf("redisstore: decode code: %w", err)
+	}
+
+	return code, nil
+}
+
+// --- access tokens -------------------------------------------------------
+
+// SaveAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) SaveAccessToken(ctx context.Context, t *oauth2.AccessToken) error {
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("redisstore: empty access token hash")
+	}
+
+	payload, err := encodeAccess(t)
+	if err != nil {
+		return fmt.Errorf("redisstore: encode access token: %w", err)
+	}
+
+	pipe := s.rdb.TxPipeline()
+	pipe.Set(ctx, s.atKey(t.TokenHash), payload, ttlUntil(t.ExpiresAt))
+
+	if t.FamilyID != "" {
+		pipe.SAdd(ctx, s.famATKey(t.FamilyID), t.TokenHash)
+	}
+
+	if _, err := pipe.Exec(ctx); err != nil {
+		return fmt.Errorf("redisstore: save access token: %w", err)
+	}
+
+	return nil
+}
+
+// LookupAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) LookupAccessToken(ctx context.Context, tokenHash string) (*oauth2.AccessToken, error) {
+	raw, err := s.rdb.Get(ctx, s.atKey(tokenHash)).Bytes()
+	if err != nil {
+		if errors.Is(err, redis.Nil) {
+			return nil, oauth2.ErrInvalidGrant.WithDescription("access token not found")
+		}
+
+		return nil, fmt.Errorf("redisstore: lookup access token: %w", err)
+	}
+
+	t, err := decodeAccess(tokenHash, raw)
+	if err != nil {
+		return nil, fmt.Errorf("redisstore: decode access token: %w", err)
+	}
+
+	return t, nil
+}
+
+// RevokeAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) RevokeAccessToken(ctx context.Context, tokenHash string) error {
+	if err := s.rdb.Del(ctx, s.atKey(tokenHash)).Err(); err != nil {
+		return fmt.Errorf("redisstore: revoke access token: %w", err)
+	}
+
+	return nil
+}
+
+// --- refresh tokens ------------------------------------------------------
+
+// SaveRefreshToken implements [oauth2.RefreshTokenStore].
+func (s *Store) SaveRefreshToken(ctx context.Context, t *oauth2.RefreshToken) error {
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("redisstore: empty refresh token hash")
+	}
+
+	payload, err := encodeRefresh(t)
+	if err != nil {
+		return fmt.Errorf("redisstore: encode refresh token: %w", err)
+	}
+
+	pipe := s.rdb.TxPipeline()
+	pipe.Set(ctx, s.rtKey(t.TokenHash), payload, ttlUntil(t.ExpiresAt))
+
+	if t.FamilyID != "" {
+		pipe.SAdd(ctx, s.famRTKey(t.FamilyID), t.TokenHash)
+	}
+
+	if _, err := pipe.Exec(ctx); err != nil {
+		return fmt.Errorf("redisstore: save refresh token: %w", err)
+	}
+
+	return nil
+}
+
+// LookupRefreshToken implements [oauth2.RefreshTokenStore].
+func (s *Store) LookupRefreshToken(ctx context.Context, tokenHash string) (*oauth2.RefreshToken, error) {
+	raw, err := s.rdb.Get(ctx, s.rtKey(tokenHash)).Bytes()
+	if err != nil {
+		if errors.Is(err, redis.Nil) {
+			return nil, oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+		}
+
+		return nil, fmt.Errorf("redisstore: lookup refresh token: %w", err)
+	}
+
+	t, err := decodeRefresh(tokenHash, raw)
+	if err != nil {
+		return nil, fmt.Errorf("redisstore: decode refresh token: %w", err)
+	}
+
+	return t, nil
+}
+
+// RotateRefreshToken implements [oauth2.RefreshTokenStore] via the
+// rotateRefresh Lua script — the consumed-flag check and the new-token
+// insert happen atomically. Reuse of a consumed token returns
+// [oauth2.ErrRefreshTokenReused] and revokes the whole family.
+func (s *Store) RotateRefreshToken(ctx context.Context, oldHash string, next *oauth2.RefreshToken) error {
+	payload, err := encodeRefresh(next)
+	if err != nil {
+		return fmt.Errorf("redisstore: encode rotated refresh token: %w", err)
+	}
+
+	keys := []string{
+		s.rtKey(oldHash),
+		s.rtKey(next.TokenHash),
+		s.famRTKey(next.FamilyID),
+	}
+	args := []any{payload, int64(ttlUntil(next.ExpiresAt).Seconds()), next.TokenHash}
+
+	res, err := rotateRefreshScript.Run(ctx, s.rdb, keys, args...).Result()
+	if err != nil {
+		return fmt.Errorf("redisstore: rotate refresh token: %w", err)
+	}
+
+	switch res {
+	case "ok":
+		return nil
+	case "notfound":
+		return oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+	case "reused":
+		// Reuse detected — revoke the whole family per BCP §8.10.3.
+		_ = s.RevokeRefreshFamily(ctx, next.FamilyID)
+
+		return oauth2.ErrRefreshTokenReused
+	default:
+		return fmt.Errorf("redisstore: rotate: unexpected script result %v", res)
+	}
+}
+
+// RevokeRefreshFamily implements [oauth2.RefreshTokenStore]: every refresh
+// token of the family is marked consumed, every access token of the
+// family is deleted.
+func (s *Store) RevokeRefreshFamily(ctx context.Context, familyID string) error {
+	rtHashes, err := s.rdb.SMembers(ctx, s.famRTKey(familyID)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		return fmt.Errorf("redisstore: list family refresh tokens: %w", err)
+	}
+
+	for _, h := range rtHashes {
+		if err := s.markConsumed(ctx, h); err != nil {
+			return err
+		}
+	}
+
+	atHashes, err := s.rdb.SMembers(ctx, s.famATKey(familyID)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		return fmt.Errorf("redisstore: list family access tokens: %w", err)
+	}
+
+	for _, h := range atHashes {
+		if err := s.rdb.Del(ctx, s.atKey(h)).Err(); err != nil {
+			return fmt.Errorf("redisstore: purge family access token: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// markConsumed flips the consumed flag of a single refresh token,
+// preserving its TTL.
+func (s *Store) markConsumed(ctx context.Context, hash string) error {
+	raw, err := s.rdb.Get(ctx, s.rtKey(hash)).Bytes()
+	if err != nil {
+		if errors.Is(err, redis.Nil) {
+			return nil // already gone — nothing to revoke
+		}
+
+		return fmt.Errorf("redisstore: get refresh token: %w", err)
+	}
+
+	rt, err := decodeRefresh(hash, raw)
+	if err != nil {
+		return fmt.Errorf("redisstore: decode refresh token: %w", err)
+	}
+
+	if rt.Consumed {
+		return nil
+	}
+
+	rt.Consumed = true
+
+	payload, err := encodeRefresh(rt)
+	if err != nil {
+		return fmt.Errorf("redisstore: encode refresh token: %w", err)
+	}
+
+	if err := s.rdb.Set(ctx, s.rtKey(hash), payload, redis.KeepTTL).Err(); err != nil {
+		return fmt.Errorf("redisstore: mark refresh token consumed: %w", err)
+	}
+
+	return nil
+}
+
+// Compile-time interface check.
+var _ oauth2.Storage = (*Store)(nil)
diff --git a/oauth2/store/redis/store_error_test.go b/oauth2/store/redis/store_error_test.go
new file mode 100644
index 0000000..2d5fe77
--- /dev/null
+++ b/oauth2/store/redis/store_error_test.go
@@ -0,0 +1,186 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package redisstore_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/hyperscale-stack/security/oauth2"
+	redisstore "github.com/hyperscale-stack/security/oauth2/store/redis"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRedisStoreRejectsEmptyHashes(t *testing.T) {
+	t.Parallel()
+
+	store := newRedisStore(t)
+	ctx := context.Background()
+
+	require.Error(t, store.SaveAuthorizationCode(ctx, &oauth2.AuthorizationCode{}))
+	require.Error(t, store.SaveAccessToken(ctx, &oauth2.AccessToken{}))
+	require.Error(t, store.SaveRefreshToken(ctx, &oauth2.RefreshToken{}))
+}
+
+// TestRedisStoreReportsBackendErrors closes the miniredis server so every
+// command fails, exercising the store's error-return branches.
+func TestRedisStoreReportsBackendErrors(t *testing.T) {
+	t.Parallel()
+
+	mr := miniredis.RunT(t)
+	client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+
+	store, err := redisstore.New(client)
+	require.NoError(t, err)
+
+	mr.Close() // the backend is now unreachable
+
+	ctx := context.Background()
+	now := time.Now()
+
+	code := &oauth2.AuthorizationCode{
+		CodeHash: "h", ExpiresAt: now.Add(time.Minute),
+	}
+	require.Error(t, store.SaveAuthorizationCode(ctx, code))
+
+	_, err = store.ConsumeAuthorizationCode(ctx, "h")
+	require.Error(t, err)
+
+	at := &oauth2.AccessToken{TokenHash: "h", FamilyID: "f", ExpiresAt: now.Add(time.Minute)}
+	require.Error(t, store.SaveAccessToken(ctx, at))
+
+	_, err = store.LookupAccessToken(ctx, "h")
+	require.Error(t, err)
+
+	require.Error(t, store.RevokeAccessToken(ctx, "h"))
+
+	rt := &oauth2.RefreshToken{TokenHash: "h", FamilyID: "f", ExpiresAt: now.Add(time.Minute)}
+	require.Error(t, store.SaveRefreshToken(ctx, rt))
+
+	_, err = store.LookupRefreshToken(ctx, "h")
+	require.Error(t, err)
+
+	require.Error(t, store.RotateRefreshToken(ctx, "h", rt))
+	require.Error(t, store.RevokeRefreshFamily(ctx, "f"))
+}
+
+// TestRedisStoreDecodeErrors injects corrupt JSON directly into Redis and
+// checks the decode-error branches.
+func TestRedisStoreDecodeErrors(t *testing.T) {
+	t.Parallel()
+
+	mr := miniredis.RunT(t)
+	client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+
+	store, err := redisstore.New(client)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+
+	require.NoError(t, mr.Set("oauth2:code:bad", "{not-json"))
+	_, err = store.ConsumeAuthorizationCode(ctx, "bad")
+	require.Error(t, err)
+
+	require.NoError(t, mr.Set("oauth2:at:bad", "{not-json"))
+	_, err = store.LookupAccessToken(ctx, "bad")
+	require.Error(t, err)
+
+	require.NoError(t, mr.Set("oauth2:rt:bad", "{not-json"))
+	_, err = store.LookupRefreshToken(ctx, "bad")
+	require.Error(t, err)
+}
+
+// TestRedisStoreConsumeUnknownCode covers the "code already used / absent"
+// branch of the consume script.
+func TestRedisStoreConsumeUnknownCode(t *testing.T) {
+	t.Parallel()
+
+	store := newRedisStore(t)
+
+	_, err := store.ConsumeAuthorizationCode(context.Background(), "never-saved")
+	require.ErrorIs(t, err, oauth2.ErrCodeAlreadyUsed)
+}
+
+// TestRedisStoreRotateUnknownToken covers the script's "notfound" branch.
+func TestRedisStoreRotateUnknownToken(t *testing.T) {
+	t.Parallel()
+
+	store := newRedisStore(t)
+
+	err := store.RotateRefreshToken(context.Background(), "never-saved", &oauth2.RefreshToken{
+		TokenHash: "new", FamilyID: "fam", ExpiresAt: time.Now().Add(time.Hour),
+	})
+	require.Error(t, err)
+}
+
+// TestRedisStoreRevokeFamilyMarksRefreshTokens checks the family-revocation
+// path: every refresh token of the family ends up consumed.
+func TestRedisStoreRevokeFamilyMarksRefreshTokens(t *testing.T) {
+	t.Parallel()
+
+	store := newRedisStore(t)
+	ctx := context.Background()
+	now := time.Now()
+
+	rt := &oauth2.RefreshToken{
+		Token: "raw", TokenHash: "rt-hash", ClientID: "c", Subject: "s",
+		Scope: "read", FamilyID: "fam-1", IssuedAt: now, ExpiresAt: now.Add(time.Hour),
+	}
+	require.NoError(t, store.SaveRefreshToken(ctx, rt))
+
+	require.NoError(t, store.RevokeRefreshFamily(ctx, "fam-1"))
+
+	got, err := store.LookupRefreshToken(ctx, "rt-hash")
+	require.NoError(t, err)
+	assert.True(t, got.Consumed, "family revocation must mark the refresh token consumed")
+
+	// Revoking again is idempotent — the token is already consumed.
+	require.NoError(t, store.RevokeRefreshFamily(ctx, "fam-1"))
+}
+
+// TestRedisStoreRevokeFamilyWithCorruptMember exercises the markConsumed
+// decode-error branch.
+func TestRedisStoreRevokeFamilyWithCorruptMember(t *testing.T) {
+	t.Parallel()
+
+	mr := miniredis.RunT(t)
+	client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+
+	store, err := redisstore.New(client)
+	require.NoError(t, err)
+
+	// A family set referencing a refresh token whose payload is corrupt.
+	_, err = mr.SAdd("oauth2:famrt:fam-x", "corrupt-hash")
+	require.NoError(t, err)
+	require.NoError(t, mr.Set("oauth2:rt:corrupt-hash", "{not-json"))
+
+	require.Error(t, store.RevokeRefreshFamily(context.Background(), "fam-x"))
+}
+
+// TestRedisStoreSavePastExpiryClampsTTL saves a token already past its
+// expiry; ttlUntil must clamp the key TTL to the 1-second floor.
+func TestRedisStoreSavePastExpiryClampsTTL(t *testing.T) {
+	t.Parallel()
+
+	store := newRedisStore(t)
+	ctx := context.Background()
+
+	at := &oauth2.AccessToken{
+		TokenHash: "expired", ClientID: "c", Subject: "s",
+		IssuedAt: time.Now().Add(-time.Hour), ExpiresAt: time.Now().Add(-time.Minute),
+	}
+	require.NoError(t, store.SaveAccessToken(ctx, at))
+
+	got, err := store.LookupAccessToken(ctx, "expired")
+	require.NoError(t, err)
+	assert.Equal(t, "c", got.ClientID)
+}
diff --git a/oauth2/store/redis/store_test.go b/oauth2/store/redis/store_test.go
new file mode 100644
index 0000000..ed06106
--- /dev/null
+++ b/oauth2/store/redis/store_test.go
@@ -0,0 +1,87 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package redisstore_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/hyperscale-stack/security/oauth2"
+	redisstore "github.com/hyperscale-stack/security/oauth2/store/redis"
+	"github.com/hyperscale-stack/security/oauth2/storetest"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+)
+
+// newRedisStore spins up an isolated miniredis server (pure-Go, no Docker)
+// and returns a Store wired to it. miniredis embeds a Lua interpreter with
+// cjson, so the consume-code and rotate-refresh scripts run exactly as on
+// a real Redis.
+func newRedisStore(t *testing.T) oauth2.Storage {
+	t.Helper()
+
+	mr := miniredis.RunT(t)
+
+	client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+
+	store, err := redisstore.New(client)
+	require.NoError(t, err)
+
+	return store
+}
+
+// TestRedisStoreConformance runs the shared storage contract against the
+// Redis implementation. The same 11-case suite the memory and SQL stores
+// pass — concurrency races included — exercising the Lua-script atomicity.
+func TestRedisStoreConformance(t *testing.T) {
+	t.Parallel()
+
+	storetest.RunConformance(t, func() oauth2.Storage {
+		return newRedisStore(t)
+	})
+}
+
+// TestNewRejectsNilClient checks the constructor guard.
+func TestNewRejectsNilClient(t *testing.T) {
+	t.Parallel()
+
+	_, err := redisstore.New(nil)
+	require.Error(t, err)
+}
+
+// TestKeyPrefixIsHonored verifies WithKeyPrefix namespaces the keys: two
+// stores with different prefixes on the same Redis do not see each other.
+func TestKeyPrefixIsHonored(t *testing.T) {
+	t.Parallel()
+
+	mr := miniredis.RunT(t)
+	client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+
+	a, err := redisstore.New(client, redisstore.WithKeyPrefix("tenant-a:"))
+	require.NoError(t, err)
+	b, err := redisstore.New(client, redisstore.WithKeyPrefix("tenant-b:"))
+	require.NoError(t, err)
+
+	now := time.Now()
+	code := &oauth2.AuthorizationCode{
+		Code: "raw", CodeHash: "shared-hash", ClientID: "c", Subject: "s",
+		RedirectURI: "https://x", Scope: "read",
+		IssuedAt: now, ExpiresAt: now.Add(time.Minute),
+	}
+	require.NoError(t, a.SaveAuthorizationCode(context.Background(), code))
+
+	// Tenant B must not see tenant A's code despite the identical hash.
+	_, err = b.ConsumeAuthorizationCode(context.Background(), "shared-hash")
+	require.Error(t, err, "key prefixes must isolate tenants")
+
+	// Tenant A still consumes it fine.
+	got, err := a.ConsumeAuthorizationCode(context.Background(), "shared-hash")
+	require.NoError(t, err)
+	require.Equal(t, "c", got.ClientID)
+}
diff --git a/oauth2/store/sql/dialect.go b/oauth2/store/sql/dialect.go
new file mode 100644
index 0000000..7d06905
--- /dev/null
+++ b/oauth2/store/sql/dialect.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore
+
+import (
+	"strconv"
+	"strings"
+)
+
+// Dialect abstracts the few SQL syntax differences the store cares about:
+// the parameter-placeholder style and the boolean literals. The store
+// writes every query with "?" placeholders and rebinds them through the
+// dialect, so query strings stay readable.
+type Dialect interface {
+	// Name returns a stable identifier ("postgres", "mysql", "sqlite")
+	// used in error messages and OTel attributes.
+	Name() string
+	// rebind rewrites a "?"-placeholder query into the dialect's native
+	// placeholder style. Postgres needs $1,$2,…; MySQL and SQLite keep ?.
+	rebind(query string) string
+}
+
+// Postgres is the PostgreSQL dialect ($1,$2,… placeholders).
+var Postgres Dialect = postgres{}
+
+// MySQL is the MySQL / MariaDB dialect (? placeholders).
+var MySQL Dialect = mysql{}
+
+// SQLite is the SQLite dialect (? placeholders).
+var SQLite Dialect = sqlite{}
+
+type postgres struct{}
+
+func (postgres) Name() string { return "postgres" }
+
+// rebind replaces each ? with the positional $N form Postgres expects.
+func (postgres) rebind(query string) string {
+	var b strings.Builder
+
+	b.Grow(len(query) + 8)
+
+	n := 0
+
+	for i := 0; i < len(query); i++ {
+		if query[i] == '?' {
+			n++
+
+			b.WriteByte('$')
+			b.WriteString(strconv.Itoa(n))
+
+			continue
+		}
+
+		b.WriteByte(query[i])
+	}
+
+	return b.String()
+}
+
+type mysql struct{}
+
+func (mysql) Name() string           { return "mysql" }
+func (mysql) rebind(q string) string { return q }
+
+// dialectSQLite is the dialect identifier for SQLite, kept as a constant so
+// it can be referenced from Name() and from schema generation.
+const dialectSQLite = "sqlite"
+
+type sqlite struct{}
+
+func (sqlite) Name() string           { return dialectSQLite }
+func (sqlite) rebind(q string) string { return q }
diff --git a/oauth2/store/sql/dialect_internal_test.go b/oauth2/store/sql/dialect_internal_test.go
new file mode 100644
index 0000000..b9e021f
--- /dev/null
+++ b/oauth2/store/sql/dialect_internal_test.go
@@ -0,0 +1,30 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDialectRebind(t *testing.T) {
+	t.Parallel()
+
+	const query = `SELECT * FROM t WHERE a = ? AND b = ? AND c = ?`
+
+	// Postgres rewrites "?" into positional $N placeholders.
+	assert.Equal(t,
+		`SELECT * FROM t WHERE a = $1 AND b = $2 AND c = $3`,
+		postgres{}.rebind(query))
+
+	// MySQL and SQLite keep the "?" placeholders verbatim.
+	assert.Equal(t, query, mysql{}.rebind(query))
+	assert.Equal(t, query, sqlite{}.rebind(query))
+
+	// A query with no placeholders is returned unchanged by every dialect.
+	const noParams = `SELECT 1`
+	assert.Equal(t, noParams, postgres{}.rebind(noParams))
+}
diff --git a/oauth2/store/sql/doc.go b/oauth2/store/sql/doc.go
new file mode 100644
index 0000000..caf771a
--- /dev/null
+++ b/oauth2/store/sql/doc.go
@@ -0,0 +1,13 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package sqlstore is a database/sql implementation of oauth2.Storage with
+// real atomicity (transactional ConsumeAuthorizationCode and
+// RotateRefreshToken). Dialects supported: PostgreSQL, MySQL, SQLite.
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security/oauth2
+//   - database/sql
+//   - stdlib only (drivers are pluggable; users bring their own)
+package sqlstore
diff --git a/oauth2/store/sql/go.mod b/oauth2/store/sql/go.mod
new file mode 100644
index 0000000..5b59fda
--- /dev/null
+++ b/oauth2/store/sql/go.mod
@@ -0,0 +1,36 @@
+module github.com/hyperscale-stack/security/oauth2/store/sql
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security/oauth2 v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	modernc.org/sqlite v1.50.1
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	modernc.org/libc v1.72.3 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+)
+
+replace github.com/hyperscale-stack/security/oauth2 => ../../
+
+replace github.com/hyperscale-stack/security => ../../../
diff --git a/oauth2/store/sql/go.sum b/oauth2/store/sql/go.sum
new file mode 100644
index 0000000..82aaac7
--- /dev/null
+++ b/oauth2/store/sql/go.sum
@@ -0,0 +1,87 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
+golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
+golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/cc/v4 v4.28.2 h1:3tQ0lf2ADtoby2EtSP+J7IE2SHwEJdP8ioR59wx7XpY=
+modernc.org/cc/v4 v4.28.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.34.0 h1:yRLPFZieg532OT4rp4JFNIVcquwalMX26G95WQDqwCQ=
+modernc.org/ccgo/v4 v4.34.0/go.mod h1:AS5WYMyBakQ+fhsHhtP8mWB82KTGPkNNJDGfGQCe0/A=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.2 h1:ZtDCnhonXSZexk/AYsegNRV1lJGgaNZJuKjJSWKyEqo=
+modernc.org/gc/v3 v3.1.2/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.72.3 h1:ZnDF4tXn4NBXFutMMQC4vtbTFSXhhKzR73fv0beZEAU=
+modernc.org/libc v1.72.3/go.mod h1:dn0dZNnnn1clLyvRxLxYExxiKRZIRENOfqQ8XEeg4Qs=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.50.1 h1:l+cQvn0sd0zJJtfygGHuQJ5AjlrwXmWPw4KP3ZMwr9w=
+modernc.org/sqlite v1.50.1/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
diff --git a/oauth2/store/sql/schema.go b/oauth2/store/sql/schema.go
new file mode 100644
index 0000000..39d3dc2
--- /dev/null
+++ b/oauth2/store/sql/schema.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore
+
+import (
+	"context"
+	"fmt"
+)
+
+// Schema returns the DDL statements that create the three tables backing
+// the store, for the given dialect. Timestamps are stored as BIGINT Unix
+// seconds to dodge the TIMESTAMP / DATETIME portability minefield between
+// engines. Token / code raw values are NEVER stored — only their hashes.
+//
+// The statements are idempotent (CREATE TABLE IF NOT EXISTS). Production
+// deployments typically run them through a migration tool rather than via
+// [Store.Migrate], but Migrate is offered for tests and small setups.
+func Schema(d Dialect) []string {
+	boolType := "BOOLEAN"
+	if d.Name() == dialectSQLite {
+		boolType = "INTEGER"
+	}
+
+	return []string{
+		`CREATE TABLE IF NOT EXISTS oauth2_auth_codes (
+			code_hash             VARCHAR(128) PRIMARY KEY,
+			client_id             VARCHAR(255) NOT NULL,
+			subject               VARCHAR(255) NOT NULL,
+			redirect_uri          TEXT         NOT NULL,
+			scope                 TEXT         NOT NULL,
+			code_challenge        TEXT         NOT NULL,
+			code_challenge_method VARCHAR(16)  NOT NULL,
+			nonce                 TEXT         NOT NULL,
+			issued_at             BIGINT       NOT NULL,
+			expires_at            BIGINT       NOT NULL
+		)`,
+		`CREATE TABLE IF NOT EXISTS oauth2_access_tokens (
+			token_hash VARCHAR(128) PRIMARY KEY,
+			client_id  VARCHAR(255) NOT NULL,
+			subject    VARCHAR(255) NOT NULL,
+			scope      TEXT         NOT NULL,
+			family_id  VARCHAR(64)  NOT NULL,
+			audience   VARCHAR(255) NOT NULL,
+			issued_at  BIGINT       NOT NULL,
+			expires_at BIGINT       NOT NULL
+		)`,
+		`CREATE INDEX IF NOT EXISTS idx_oauth2_access_family ON oauth2_access_tokens (family_id)`,
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS oauth2_refresh_tokens (
+			token_hash VARCHAR(128) PRIMARY KEY,
+			client_id  VARCHAR(255) NOT NULL,
+			subject    VARCHAR(255) NOT NULL,
+			scope      TEXT         NOT NULL,
+			family_id  VARCHAR(64)  NOT NULL,
+			consumed   %s           NOT NULL DEFAULT 0,
+			issued_at  BIGINT       NOT NULL,
+			expires_at BIGINT       NOT NULL
+		)`, boolType),
+		`CREATE INDEX IF NOT EXISTS idx_oauth2_refresh_family ON oauth2_refresh_tokens (family_id)`,
+	}
+}
+
+// Migrate applies [Schema] to the store's database. It is safe to call
+// repeatedly (every statement is IF NOT EXISTS).
+func (s *Store) Migrate(ctx context.Context) error {
+	for _, stmt := range Schema(s.dialect) {
+		if _, err := s.db.ExecContext(ctx, stmt); err != nil {
+			return fmt.Errorf("sqlstore: migrate: %w", err)
+		}
+	}
+
+	return nil
+}
diff --git a/oauth2/store/sql/store.go b/oauth2/store/sql/store.go
new file mode 100644
index 0000000..61c59b8
--- /dev/null
+++ b/oauth2/store/sql/store.go
@@ -0,0 +1,345 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// Store is a database/sql-backed [oauth2.Storage]. Atomicity of the
+// single-use operations (ConsumeAuthorizationCode, RotateRefreshToken) is
+// guaranteed by transactions plus affected-row checks — no SELECT…FOR
+// UPDATE is needed because the winning DELETE / UPDATE is the one that
+// reports RowsAffected()==1.
+type Store struct {
+	db      *sql.DB
+	dialect Dialect
+}
+
+// New returns a [Store] bound to db using the given [Dialect]. The
+// caller owns db's lifecycle. Call [Store.Migrate] once at boot (or run
+// the DDL from [Schema] through a migration tool).
+func New(db *sql.DB, dialect Dialect) (*Store, error) {
+	if db == nil {
+		return nil, errors.New("sqlstore: New: nil *sql.DB")
+	}
+
+	if dialect == nil {
+		return nil, errors.New("sqlstore: New: nil Dialect")
+	}
+
+	return &Store{db: db, dialect: dialect}, nil
+}
+
+// exec runs a non-query statement, rebinding placeholders for the dialect.
+func (s *Store) exec(ctx context.Context, q string, args ...any) (sql.Result, error) {
+	return s.db.ExecContext(ctx, s.dialect.rebind(q), args...) //nolint:wrapcheck // wrapped by callers
+}
+
+// --- authorization codes -------------------------------------------------
+
+// SaveAuthorizationCode implements [oauth2.AuthorizationCodeStore].
+func (s *Store) SaveAuthorizationCode(ctx context.Context, code *oauth2.AuthorizationCode) error {
+	if code.CodeHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("sqlstore: empty code hash")
+	}
+
+	const q = `INSERT INTO oauth2_auth_codes
+		(code_hash, client_id, subject, redirect_uri, scope,
+		 code_challenge, code_challenge_method, nonce, issued_at, expires_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+
+	_, err := s.exec(ctx, q,
+		code.CodeHash, code.ClientID, code.Subject, code.RedirectURI, code.Scope,
+		code.CodeChallenge, code.CodeChallengeMethod, code.Nonce,
+		code.IssuedAt.Unix(), code.ExpiresAt.Unix())
+	if err != nil {
+		return fmt.Errorf("sqlstore: save authorization code: %w", err)
+	}
+
+	return nil
+}
+
+// ConsumeAuthorizationCode implements [oauth2.AuthorizationCodeStore]. The
+// SELECT + DELETE run in one transaction; the DELETE's RowsAffected()
+// decides the winner when two callers race, so the operation is atomic
+// without SELECT…FOR UPDATE.
+func (s *Store) ConsumeAuthorizationCode(ctx context.Context, codeHash string) (*oauth2.AuthorizationCode, error) {
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("sqlstore: begin: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	const sel = `SELECT client_id, subject, redirect_uri, scope,
+		code_challenge, code_challenge_method, nonce, issued_at, expires_at
+		FROM oauth2_auth_codes WHERE code_hash = ?`
+
+	var (
+		code              = &oauth2.AuthorizationCode{CodeHash: codeHash}
+		issuedAt, expires int64
+	)
+
+	row := tx.QueryRowContext(ctx, s.dialect.rebind(sel), codeHash)
+	if err := row.Scan(
+		&code.ClientID, &code.Subject, &code.RedirectURI, &code.Scope,
+		&code.CodeChallenge, &code.CodeChallengeMethod, &code.Nonce,
+		&issuedAt, &expires,
+	); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, oauth2.ErrCodeAlreadyUsed
+		}
+
+		return nil, fmt.Errorf("sqlstore: select authorization code: %w", err)
+	}
+
+	res, err := tx.ExecContext(ctx, s.dialect.rebind(
+		`DELETE FROM oauth2_auth_codes WHERE code_hash = ?`), codeHash)
+	if err != nil {
+		return nil, fmt.Errorf("sqlstore: delete authorization code: %w", err)
+	}
+
+	affected, err := res.RowsAffected()
+	if err != nil {
+		return nil, fmt.Errorf("sqlstore: rows affected: %w", err)
+	}
+
+	if affected != 1 {
+		// A concurrent transaction consumed the code first.
+		return nil, oauth2.ErrCodeAlreadyUsed
+	}
+
+	if err := tx.Commit(); err != nil {
+		return nil, fmt.Errorf("sqlstore: commit: %w", err)
+	}
+
+	code.IssuedAt = time.Unix(issuedAt, 0)
+	code.ExpiresAt = time.Unix(expires, 0)
+
+	return code, nil
+}
+
+// --- access tokens -------------------------------------------------------
+
+// SaveAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) SaveAccessToken(ctx context.Context, t *oauth2.AccessToken) error {
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("sqlstore: empty access token hash")
+	}
+
+	const q = `INSERT INTO oauth2_access_tokens
+		(token_hash, client_id, subject, scope, family_id, audience, issued_at, expires_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+
+	_, err := s.exec(ctx, q,
+		t.TokenHash, t.ClientID, t.Subject, t.Scope, t.FamilyID, t.Audience,
+		t.IssuedAt.Unix(), t.ExpiresAt.Unix())
+	if err != nil {
+		return fmt.Errorf("sqlstore: save access token: %w", err)
+	}
+
+	return nil
+}
+
+// LookupAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) LookupAccessToken(ctx context.Context, tokenHash string) (*oauth2.AccessToken, error) {
+	const q = `SELECT client_id, subject, scope, family_id, audience, issued_at, expires_at
+		FROM oauth2_access_tokens WHERE token_hash = ?`
+
+	var (
+		t                 = &oauth2.AccessToken{TokenHash: tokenHash}
+		issuedAt, expires int64
+	)
+
+	row := s.db.QueryRowContext(ctx, s.dialect.rebind(q), tokenHash)
+	if err := row.Scan(&t.ClientID, &t.Subject, &t.Scope, &t.FamilyID, &t.Audience,
+		&issuedAt, &expires); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, oauth2.ErrInvalidGrant.WithDescription("access token not found")
+		}
+
+		return nil, fmt.Errorf("sqlstore: lookup access token: %w", err)
+	}
+
+	t.IssuedAt = time.Unix(issuedAt, 0)
+	t.ExpiresAt = time.Unix(expires, 0)
+
+	return t, nil
+}
+
+// RevokeAccessToken implements [oauth2.AccessTokenStore].
+func (s *Store) RevokeAccessToken(ctx context.Context, tokenHash string) error {
+	if _, err := s.exec(ctx, `DELETE FROM oauth2_access_tokens WHERE token_hash = ?`, tokenHash); err != nil {
+		return fmt.Errorf("sqlstore: revoke access token: %w", err)
+	}
+
+	return nil
+}
+
+// --- refresh tokens ------------------------------------------------------
+
+// SaveRefreshToken implements [oauth2.RefreshTokenStore].
+func (s *Store) SaveRefreshToken(ctx context.Context, t *oauth2.RefreshToken) error {
+	if t.TokenHash == "" {
+		return oauth2.ErrInvalidRequest.WithDescription("sqlstore: empty refresh token hash")
+	}
+
+	const q = `INSERT INTO oauth2_refresh_tokens
+		(token_hash, client_id, subject, scope, family_id, consumed, issued_at, expires_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+
+	_, err := s.exec(ctx, q,
+		t.TokenHash, t.ClientID, t.Subject, t.Scope, t.FamilyID, boolToInt(t.Consumed),
+		t.IssuedAt.Unix(), t.ExpiresAt.Unix())
+	if err != nil {
+		return fmt.Errorf("sqlstore: save refresh token: %w", err)
+	}
+
+	return nil
+}
+
+// LookupRefreshToken implements [oauth2.RefreshTokenStore].
+func (s *Store) LookupRefreshToken(ctx context.Context, tokenHash string) (*oauth2.RefreshToken, error) {
+	const q = `SELECT client_id, subject, scope, family_id, consumed, issued_at, expires_at
+		FROM oauth2_refresh_tokens WHERE token_hash = ?`
+
+	t, err := scanRefresh(s.db.QueryRowContext(ctx, s.dialect.rebind(q), tokenHash), tokenHash)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+		}
+
+		return nil, fmt.Errorf("sqlstore: lookup refresh token: %w", err)
+	}
+
+	return t, nil
+}
+
+// RotateRefreshToken implements [oauth2.RefreshTokenStore]. The whole
+// sequence runs in one transaction:
+//
+//  1. UPDATE the old token to consumed=1 WHERE consumed=0. The
+//     RowsAffected()==1 check is the atomic gate — a concurrent rotation
+//     that already flipped the row gets 0.
+//  2. On 0 rows, the token was reused: revoke the family and return
+//     ErrRefreshTokenReused.
+//  3. On 1 row, INSERT the new token and commit.
+func (s *Store) RotateRefreshToken(ctx context.Context, oldHash string, next *oauth2.RefreshToken) error {
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("sqlstore: begin: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	// Fetch family id (needed for the reuse-revocation path).
+	var familyID string
+
+	famRow := tx.QueryRowContext(ctx, s.dialect.rebind(
+		`SELECT family_id FROM oauth2_refresh_tokens WHERE token_hash = ?`), oldHash)
+	if err := famRow.Scan(&familyID); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return oauth2.ErrInvalidGrant.WithDescription("refresh token not found")
+		}
+
+		return fmt.Errorf("sqlstore: select refresh token: %w", err)
+	}
+
+	res, err := tx.ExecContext(ctx, s.dialect.rebind(
+		`UPDATE oauth2_refresh_tokens SET consumed = 1 WHERE token_hash = ? AND consumed = 0`), oldHash)
+	if err != nil {
+		return fmt.Errorf("sqlstore: consume refresh token: %w", err)
+	}
+
+	affected, err := res.RowsAffected()
+	if err != nil {
+		return fmt.Errorf("sqlstore: rows affected: %w", err)
+	}
+
+	if affected != 1 {
+		// Reuse: the token was already consumed. Revoke the family in a
+		// separate transaction after rolling this one back.
+		_ = tx.Rollback()
+		_ = s.RevokeRefreshFamily(ctx, familyID)
+
+		return oauth2.ErrRefreshTokenReused
+	}
+
+	if _, err := tx.ExecContext(ctx, s.dialect.rebind(
+		`INSERT INTO oauth2_refresh_tokens
+			(token_hash, client_id, subject, scope, family_id, consumed, issued_at, expires_at)
+			VALUES (?, ?, ?, ?, ?, 0, ?, ?)`),
+		next.TokenHash, next.ClientID, next.Subject, next.Scope, next.FamilyID,
+		next.IssuedAt.Unix(), next.ExpiresAt.Unix(),
+	); err != nil {
+		return fmt.Errorf("sqlstore: insert rotated refresh token: %w", err)
+	}
+
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("sqlstore: commit: %w", err)
+	}
+
+	return nil
+}
+
+// RevokeRefreshFamily implements [oauth2.RefreshTokenStore]: every refresh
+// token of the family is marked consumed and every access token of the
+// family is deleted.
+func (s *Store) RevokeRefreshFamily(ctx context.Context, familyID string) error {
+	if _, err := s.exec(ctx,
+		`UPDATE oauth2_refresh_tokens SET consumed = 1 WHERE family_id = ?`, familyID); err != nil {
+		return fmt.Errorf("sqlstore: revoke refresh family: %w", err)
+	}
+
+	if _, err := s.exec(ctx,
+		`DELETE FROM oauth2_access_tokens WHERE family_id = ?`, familyID); err != nil {
+		return fmt.Errorf("sqlstore: purge family access tokens: %w", err)
+	}
+
+	return nil
+}
+
+// rowScanner abstracts *sql.Row so scanRefresh works with QueryRow results.
+type rowScanner interface {
+	Scan(dest ...any) error
+}
+
+// scanRefresh decodes a refresh-token row.
+func scanRefresh(row rowScanner, hash string) (*oauth2.RefreshToken, error) {
+	var (
+		t                 = &oauth2.RefreshToken{TokenHash: hash}
+		consumed          int64
+		issuedAt, expires int64
+	)
+
+	if err := row.Scan(&t.ClientID, &t.Subject, &t.Scope, &t.FamilyID,
+		&consumed, &issuedAt, &expires); err != nil {
+		return nil, err //nolint:wrapcheck // caller classifies sql.ErrNoRows
+	}
+
+	t.Consumed = consumed != 0
+	t.IssuedAt = time.Unix(issuedAt, 0)
+	t.ExpiresAt = time.Unix(expires, 0)
+
+	return t, nil
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+
+	return 0
+}
+
+// Compile-time interface check.
+var _ oauth2.Storage = (*Store)(nil)
diff --git a/oauth2/store/sql/store_error_test.go b/oauth2/store/sql/store_error_test.go
new file mode 100644
index 0000000..f66c853
--- /dev/null
+++ b/oauth2/store/sql/store_error_test.go
@@ -0,0 +1,109 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore_test
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	sqlstore "github.com/hyperscale-stack/security/oauth2/store/sql"
+	"github.com/stretchr/testify/require"
+	_ "modernc.org/sqlite"
+)
+
+// unmigratedStore opens a private SQLite database WITHOUT running Migrate,
+// so every statement fails with "no such table" — the cheap way to
+// exercise the store's error-return branches. A plain ":memory:" DSN
+// (no cache=shared) keeps the database isolated from the conformance
+// suite's migrated databases.
+func unmigratedStore(t *testing.T) *sqlstore.Store {
+	t.Helper()
+
+	db, err := sql.Open("sqlite", ":memory:")
+	require.NoError(t, err)
+	db.SetMaxOpenConns(1)
+	t.Cleanup(func() { _ = db.Close() })
+
+	store, err := sqlstore.New(db, sqlstore.SQLite)
+	require.NoError(t, err)
+
+	return store
+}
+
+func TestSQLStoreReportsBackendErrors(t *testing.T) {
+	t.Parallel()
+
+	store := unmigratedStore(t)
+	ctx := context.Background()
+	now := time.Now()
+
+	code := &oauth2.AuthorizationCode{
+		CodeHash: "h", ClientID: "c", Subject: "s", RedirectURI: "u", Scope: "r",
+		IssuedAt: now, ExpiresAt: now.Add(time.Minute),
+	}
+	require.Error(t, store.SaveAuthorizationCode(ctx, code))
+
+	_, err := store.ConsumeAuthorizationCode(ctx, "h")
+	require.Error(t, err)
+
+	at := &oauth2.AccessToken{
+		TokenHash: "h", ClientID: "c", Subject: "s", Scope: "r",
+		IssuedAt: now, ExpiresAt: now.Add(time.Minute),
+	}
+	require.Error(t, store.SaveAccessToken(ctx, at))
+
+	_, err = store.LookupAccessToken(ctx, "h")
+	require.Error(t, err)
+
+	require.Error(t, store.RevokeAccessToken(ctx, "h"))
+
+	// Consumed=true also exercises the boolToInt true branch.
+	rt := &oauth2.RefreshToken{
+		TokenHash: "h", ClientID: "c", Subject: "s", Scope: "r", FamilyID: "f",
+		Consumed: true, IssuedAt: now, ExpiresAt: now.Add(time.Minute),
+	}
+	require.Error(t, store.SaveRefreshToken(ctx, rt))
+
+	_, err = store.LookupRefreshToken(ctx, "h")
+	require.Error(t, err)
+
+	require.Error(t, store.RotateRefreshToken(ctx, "h", rt))
+	require.Error(t, store.RevokeRefreshFamily(ctx, "f"))
+}
+
+func TestSQLStoreRejectsEmptyHashes(t *testing.T) {
+	t.Parallel()
+
+	store := unmigratedStore(t)
+	ctx := context.Background()
+
+	require.Error(t, store.SaveAuthorizationCode(ctx, &oauth2.AuthorizationCode{}))
+	require.Error(t, store.SaveAccessToken(ctx, &oauth2.AccessToken{}))
+	require.Error(t, store.SaveRefreshToken(ctx, &oauth2.RefreshToken{}))
+}
+
+func TestSQLStoreReportsErrorsOnClosedDB(t *testing.T) {
+	t.Parallel()
+
+	db, err := sql.Open("sqlite", ":memory:")
+	require.NoError(t, err)
+	db.SetMaxOpenConns(1)
+
+	store, err := sqlstore.New(db, sqlstore.SQLite)
+	require.NoError(t, err)
+
+	require.NoError(t, db.Close())
+
+	ctx := context.Background()
+
+	// BeginTx fails on a closed pool — exercises the "begin" error branch.
+	_, err = store.ConsumeAuthorizationCode(ctx, "h")
+	require.Error(t, err)
+
+	require.Error(t, store.RotateRefreshToken(ctx, "h", &oauth2.RefreshToken{}))
+}
diff --git a/oauth2/store/sql/store_test.go b/oauth2/store/sql/store_test.go
new file mode 100644
index 0000000..a19436c
--- /dev/null
+++ b/oauth2/store/sql/store_test.go
@@ -0,0 +1,97 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package sqlstore_test
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	sqlstore "github.com/hyperscale-stack/security/oauth2/store/sql"
+	"github.com/hyperscale-stack/security/oauth2/storetest"
+	"github.com/stretchr/testify/require"
+	_ "modernc.org/sqlite" // pure-Go SQLite driver — no cgo, no Docker
+)
+
+// newSQLiteStore opens a fresh in-memory SQLite database, migrates it, and
+// returns a ready oauth2.Storage. Each call gets an isolated database
+// (the "file::memory:" + unique cache prevents sharing across calls).
+func newSQLiteStore(t *testing.T) oauth2.Storage {
+	t.Helper()
+
+	// A private in-memory database, scoped to this *sql.DB handle.
+	db, err := sql.Open("sqlite", "file::memory:?cache=shared&_pragma=foreign_keys(1)")
+	require.NoError(t, err)
+
+	// SQLite in-memory shared-cache stays alive while at least one
+	// connection is open; cap the pool at 1 so the schema persists and
+	// writes serialise (SQLite is single-writer anyway).
+	db.SetMaxOpenConns(1)
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	store, err := sqlstore.New(db, sqlstore.SQLite)
+	require.NoError(t, err)
+
+	require.NoError(t, store.Migrate(context.Background()))
+
+	return store
+}
+
+// TestSQLiteStoreConformance runs the shared storage contract against the
+// database/sql implementation on a pure-Go SQLite backend. It exercises
+// the same suite the in-memory store passes, including the concurrency
+// races that assert atomic ConsumeAuthorizationCode / RotateRefreshToken.
+func TestSQLiteStoreConformance(t *testing.T) {
+	t.Parallel()
+
+	storetest.RunConformance(t, func() oauth2.Storage {
+		return newSQLiteStore(t)
+	})
+}
+
+// TestMigrateIsIdempotent verifies the IF NOT EXISTS DDL can run twice.
+func TestMigrateIsIdempotent(t *testing.T) {
+	t.Parallel()
+
+	db, err := sql.Open("sqlite", "file::memory:?cache=shared")
+	require.NoError(t, err)
+	db.SetMaxOpenConns(1)
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	store, err := sqlstore.New(db, sqlstore.SQLite)
+	require.NoError(t, err)
+
+	require.NoError(t, store.Migrate(context.Background()))
+	require.NoError(t, store.Migrate(context.Background()), "second Migrate must be a no-op")
+}
+
+// TestNewValidatesArguments checks the constructor guards.
+func TestNewValidatesArguments(t *testing.T) {
+	t.Parallel()
+
+	_, err := sqlstore.New(nil, sqlstore.SQLite)
+	require.Error(t, err)
+
+	db, _ := sql.Open("sqlite", "file::memory:")
+	t.Cleanup(func() { _ = db.Close() })
+
+	_, err = sqlstore.New(db, nil)
+	require.Error(t, err)
+}
+
+// TestPostgresDialectRebindsPlaceholders is a unit check on the dialect
+// abstraction — Postgres is the only dialect that rewrites "?".
+func TestPostgresDialectRebindsPlaceholders(t *testing.T) {
+	t.Parallel()
+
+	// Exercised indirectly through the store; here we just assert the
+	// dialect names are stable (used in OTel attributes / errors).
+	require.Equal(t, "postgres", sqlstore.Postgres.Name())
+	require.Equal(t, "mysql", sqlstore.MySQL.Name())
+	require.Equal(t, "sqlite", sqlstore.SQLite.Name())
+}
diff --git a/oauth2/storetest/conformance.go b/oauth2/storetest/conformance.go
new file mode 100644
index 0000000..1393d29
--- /dev/null
+++ b/oauth2/storetest/conformance.go
@@ -0,0 +1,347 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package storetest provides a black-box conformance suite that every
+// [oauth2.Storage] implementation MUST pass. The in-memory, SQL and Redis
+// stores all run RunConformance against a fresh instance so behavioral
+// drift between backends is caught at test time.
+//
+// The package imports "testing" deliberately: it is a test helper in the
+// spirit of net/http/httptest and testing/fstest, meant to be called from
+// _test.go files of the store implementations.
+package storetest
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// Factory builds a fresh, empty [oauth2.Storage]. RunConformance calls it
+// once per sub-test so cases never share state.
+type Factory func() oauth2.Storage
+
+// RunConformance executes the full storage contract against the
+// implementation produced by newStore. Call it from a Test function:
+//
+//	func TestMyStoreConformance(t *testing.T) {
+//	    storetest.RunConformance(t, func() oauth2.Storage { return New(...) })
+//	}
+func RunConformance(t *testing.T, newStore Factory) {
+	t.Helper()
+
+	cases := []struct {
+		name string
+		run  func(*testing.T, oauth2.Storage)
+	}{
+		{"AuthorizationCodeSaveConsume", testCodeSaveConsume},
+		{"AuthorizationCodeSingleUse", testCodeSingleUse},
+		{"AuthorizationCodeUnknown", testCodeUnknown},
+		{"AuthorizationCodeConcurrentConsume", testCodeConcurrentConsume},
+		{"AccessTokenSaveLookupRevoke", testAccessLifecycle},
+		{"AccessTokenLookupUnknown", testAccessUnknown},
+		{"RefreshTokenSaveLookup", testRefreshSaveLookup},
+		{"RefreshTokenRotation", testRefreshRotation},
+		{"RefreshTokenReuseRevokesFamily", testRefreshReuse},
+		{"RefreshTokenConcurrentRotation", testRefreshConcurrentRotation},
+		{"RevokeRefreshFamily", testRevokeFamily},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			c.run(t, newStore())
+		})
+	}
+}
+
+// testSubject is the fixed resource-owner subject used across the suite.
+const testSubject = "alice"
+
+// testClientID is the fixed client identifier used across the suite.
+const testClientID = "client-1"
+
+// testScope is the fixed scope used across the suite.
+const testScope = "read"
+
+func ctx() context.Context { return context.Background() }
+
+func mustNoError(t *testing.T, err error, msg string) {
+	t.Helper()
+
+	if err != nil {
+		t.Fatalf("%s: unexpected error: %v", msg, err)
+	}
+}
+
+// --- authorization codes -------------------------------------------------
+
+func sampleCode(hash string) *oauth2.AuthorizationCode {
+	now := time.Now()
+
+	return &oauth2.AuthorizationCode{
+		Code:        "raw-" + hash,
+		CodeHash:    hash,
+		ClientID:    testClientID,
+		Subject:     testSubject,
+		RedirectURI: "https://app.example/cb",
+		Scope:       testScope,
+		IssuedAt:    now,
+		ExpiresAt:   now.Add(10 * time.Minute),
+	}
+}
+
+func testCodeSaveConsume(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveAuthorizationCode(ctx(), sampleCode("code-1")), "save")
+
+	got, err := s.ConsumeAuthorizationCode(ctx(), "code-1")
+	mustNoError(t, err, "consume")
+
+	if got.ClientID != testClientID || got.Subject != testSubject || got.Scope != testScope {
+		t.Fatalf("consumed code lost fields: %+v", got)
+	}
+}
+
+func testCodeSingleUse(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveAuthorizationCode(ctx(), sampleCode("code-2")), "save")
+
+	if _, err := s.ConsumeAuthorizationCode(ctx(), "code-2"); err != nil {
+		t.Fatalf("first consume failed: %v", err)
+	}
+
+	_, err := s.ConsumeAuthorizationCode(ctx(), "code-2")
+	if err == nil {
+		t.Fatal("second consume MUST fail (single-use)")
+	}
+
+	if !errors.Is(err, oauth2.ErrCodeAlreadyUsed) &&
+		oauth2.IsCode(err) != oauth2.CodeInvalidGrant {
+		t.Fatalf("reuse error should be ErrCodeAlreadyUsed/invalid_grant, got %v", err)
+	}
+}
+
+func testCodeUnknown(t *testing.T, s oauth2.Storage) {
+	if _, err := s.ConsumeAuthorizationCode(ctx(), "never-saved"); err == nil {
+		t.Fatal("consuming an unknown code MUST fail")
+	}
+}
+
+// testCodeConcurrentConsume asserts the single-use guarantee under
+// concurrency: 50 goroutines race to consume one code, exactly one wins.
+func testCodeConcurrentConsume(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveAuthorizationCode(ctx(), sampleCode("code-race")), "save")
+
+	const n = 50
+
+	var (
+		wg   sync.WaitGroup
+		mu   sync.Mutex
+		wins int
+	)
+
+	for range n {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			if _, err := s.ConsumeAuthorizationCode(ctx(), "code-race"); err == nil {
+				mu.Lock()
+				wins++
+				mu.Unlock()
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	if wins != 1 {
+		t.Fatalf("expected exactly 1 successful consume, got %d", wins)
+	}
+}
+
+// --- access tokens -------------------------------------------------------
+
+func sampleAccess(hash, family string) *oauth2.AccessToken {
+	now := time.Now()
+
+	return &oauth2.AccessToken{
+		Token:     "raw-" + hash,
+		TokenHash: hash,
+		ClientID:  testClientID,
+		Subject:   testSubject,
+		Scope:     testScope,
+		IssuedAt:  now,
+		ExpiresAt: now.Add(time.Hour),
+		FamilyID:  family,
+		Audience:  "api",
+	}
+}
+
+func testAccessLifecycle(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveAccessToken(ctx(), sampleAccess("at-1", "")), "save")
+
+	got, err := s.LookupAccessToken(ctx(), "at-1")
+	mustNoError(t, err, "lookup")
+
+	if got.Subject != testSubject {
+		t.Fatalf("lookup lost fields: %+v", got)
+	}
+
+	mustNoError(t, s.RevokeAccessToken(ctx(), "at-1"), "revoke")
+
+	if _, err := s.LookupAccessToken(ctx(), "at-1"); err == nil {
+		t.Fatal("lookup after revoke MUST fail")
+	}
+}
+
+func testAccessUnknown(t *testing.T, s oauth2.Storage) {
+	if _, err := s.LookupAccessToken(ctx(), "missing"); err == nil {
+		t.Fatal("lookup of unknown access token MUST fail")
+	}
+}
+
+// --- refresh tokens ------------------------------------------------------
+
+func sampleRefresh(hash, family string) *oauth2.RefreshToken {
+	now := time.Now()
+
+	return &oauth2.RefreshToken{
+		Token:     "raw-" + hash,
+		TokenHash: hash,
+		ClientID:  testClientID,
+		Subject:   testSubject,
+		Scope:     testScope,
+		IssuedAt:  now,
+		ExpiresAt: now.Add(24 * time.Hour),
+		FamilyID:  family,
+	}
+}
+
+func testRefreshSaveLookup(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-1", "fam-1")), "save")
+
+	got, err := s.LookupRefreshToken(ctx(), "rt-1")
+	mustNoError(t, err, "lookup")
+
+	if got.Consumed {
+		t.Fatal("freshly saved refresh token must not be consumed")
+	}
+}
+
+func testRefreshRotation(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-old", "fam-2")), "save old")
+
+	next := sampleRefresh("rt-new", "fam-2")
+	mustNoError(t, s.RotateRefreshToken(ctx(), "rt-old", next), "rotate")
+
+	old, err := s.LookupRefreshToken(ctx(), "rt-old")
+	mustNoError(t, err, "lookup old")
+
+	if !old.Consumed {
+		t.Fatal("rotated old token MUST be marked consumed")
+	}
+
+	fresh, err := s.LookupRefreshToken(ctx(), "rt-new")
+	mustNoError(t, err, "lookup new")
+
+	if fresh.Consumed {
+		t.Fatal("new token must not be consumed")
+	}
+}
+
+func testRefreshReuse(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-r1", "fam-3")), "save")
+
+	next1 := sampleRefresh("rt-r2", "fam-3")
+	mustNoError(t, s.RotateRefreshToken(ctx(), "rt-r1", next1), "first rotate")
+
+	// Replaying rt-r1 (already consumed) MUST fail and revoke the family.
+	next2 := sampleRefresh("rt-r3", "fam-3")
+
+	err := s.RotateRefreshToken(ctx(), "rt-r1", next2)
+	if err == nil {
+		t.Fatal("rotating a consumed token MUST fail")
+	}
+
+	if !errors.Is(err, oauth2.ErrRefreshTokenReused) {
+		t.Fatalf("expected ErrRefreshTokenReused, got %v", err)
+	}
+
+	// The whole family must now be consumed.
+	for _, h := range []string{"rt-r1", "rt-r2"} {
+		rt, lookupErr := s.LookupRefreshToken(ctx(), h)
+		if lookupErr != nil {
+			continue // some backends delete revoked tokens — acceptable
+		}
+
+		if !rt.Consumed {
+			t.Fatalf("token %s should be consumed after family revocation", h)
+		}
+	}
+}
+
+// testRefreshConcurrentRotation asserts atomic rotation: 30 goroutines race
+// to rotate the same token; exactly one succeeds, the rest see reuse.
+func testRefreshConcurrentRotation(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-c0", "fam-c")), "save")
+
+	const n = 30
+
+	var (
+		wg   sync.WaitGroup
+		mu   sync.Mutex
+		wins int
+	)
+
+	for i := range n {
+		wg.Add(1)
+
+		go func(i int) {
+			defer wg.Done()
+
+			next := sampleRefresh(fmt.Sprintf("rt-c%d", i+1), "fam-c")
+			if err := s.RotateRefreshToken(ctx(), "rt-c0", next); err == nil {
+				mu.Lock()
+				wins++
+				mu.Unlock()
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	if wins != 1 {
+		t.Fatalf("expected exactly 1 successful rotation, got %d", wins)
+	}
+}
+
+func testRevokeFamily(t *testing.T, s oauth2.Storage) {
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-f1", "fam-x")), "save rt1")
+	mustNoError(t, s.SaveRefreshToken(ctx(), sampleRefresh("rt-f2", "fam-x")), "save rt2")
+	mustNoError(t, s.SaveAccessToken(ctx(), sampleAccess("at-f1", "fam-x")), "save at")
+
+	mustNoError(t, s.RevokeRefreshFamily(ctx(), "fam-x"), "revoke family")
+
+	// Access tokens of the family must be gone.
+	if _, err := s.LookupAccessToken(ctx(), "at-f1"); err == nil {
+		t.Fatal("access token of revoked family MUST be gone")
+	}
+
+	// Refresh tokens of the family must be consumed (or gone).
+	for _, h := range []string{"rt-f1", "rt-f2"} {
+		rt, err := s.LookupRefreshToken(ctx(), h)
+		if err != nil {
+			continue
+		}
+
+		if !rt.Consumed {
+			t.Fatalf("refresh token %s should be consumed after family revocation", h)
+		}
+	}
+}
diff --git a/oauth2/storetest/conformance_test.go b/oauth2/storetest/conformance_test.go
new file mode 100644
index 0000000..3be2399
--- /dev/null
+++ b/oauth2/storetest/conformance_test.go
@@ -0,0 +1,25 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package storetest_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/storage/memory"
+	"github.com/hyperscale-stack/security/oauth2/storetest"
+)
+
+// TestConformanceSuiteRunsAgainstMemory exercises the shared conformance
+// suite itself: running it against the reference in-memory store both
+// validates that store and proves the harness is internally sound. The SQL
+// and Redis modules run the same RunConformance entry point.
+func TestConformanceSuiteRunsAgainstMemory(t *testing.T) {
+	t.Parallel()
+
+	storetest.RunConformance(t, func() oauth2.Storage {
+		return memory.New()
+	})
+}
diff --git a/oauth2/token/generator.go b/oauth2/token/generator.go
new file mode 100644
index 0000000..df576e1
--- /dev/null
+++ b/oauth2/token/generator.go
@@ -0,0 +1,63 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package token ships the access-/refresh-/code-token generators used by
+// the modular OAuth2 server. Two generator families are provided:
+//
+//   - Opaque generators emit random strings stored in their hashed form
+//     in the storage layer (the default and most secure choice for refresh
+//     tokens and authorization codes).
+//   - JWT generators emit signed JSON Web Tokens for access tokens, plugged
+//     via the jwt sub-module's [jwtsec.Signer].
+package token
+
+import (
+	"context"
+	"time"
+)
+
+// AccessTokenClaims is the data passed to access-token generators. The
+// struct stays minimal; signers wishing to add custom claims should embed
+// it in their own type and project the extra fields in their Sign
+// implementation.
+type AccessTokenClaims struct {
+	// Issuer is the OAuth2 server issuer identifier.
+	Issuer string
+	// Subject is the resource-owner subject (or client-credentials sub).
+	Subject string
+	// Audience is the resource server identifier.
+	Audience string
+	// ClientID is the requesting client identifier.
+	ClientID string
+	// Scope is the granted scope.
+	Scope string
+	// FamilyID is the rotation family identifier (refresh-token family).
+	FamilyID string
+	// IssuedAt is the issuance time.
+	IssuedAt time.Time
+	// ExpiresAt is the expiry time.
+	ExpiresAt time.Time
+}
+
+// AccessTokenGenerator produces the wire form of an access token plus the
+// storage key (hash) used to look it up. Implementations decide whether
+// to emit opaque random strings or signed JWTs.
+type AccessTokenGenerator interface {
+	// Generate returns the token string handed to the client, the hash to
+	// persist in storage, and any error encountered during generation.
+	Generate(ctx context.Context, claims AccessTokenClaims) (token, hash string, err error)
+}
+
+// RefreshTokenGenerator produces opaque refresh tokens. Refresh tokens are
+// ALWAYS opaque (RFC 6749 §1.5 implies it; OAuth 2.0 BCP §8.10 makes it
+// explicit) so this interface intentionally has no JWT variant.
+type RefreshTokenGenerator interface {
+	Generate(ctx context.Context) (token, hash string, err error)
+}
+
+// AuthorizationCodeGenerator produces single-use authorization codes.
+// Codes are ALWAYS opaque and ALWAYS stored hashed (RFC 6749 §10.5).
+type AuthorizationCodeGenerator interface {
+	Generate(ctx context.Context) (code, hash string, err error)
+}
diff --git a/oauth2/token/jwt.go b/oauth2/token/jwt.go
new file mode 100644
index 0000000..9e776ae
--- /dev/null
+++ b/oauth2/token/jwt.go
@@ -0,0 +1,62 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package token
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// AccessTokenSigner is the contract a JWT signer must satisfy to plug into
+// the OAuth2 server as an access-token generator. It deliberately mirrors
+// [jwtsec.Signer.Sign] but keeps the OAuth2 module free of a hard dependency
+// on the JWT sub-module: callers wire the dependency in their composition
+// root via [JWTAccessTokenGenerator].
+type AccessTokenSigner interface {
+	// SignAccessToken signs the supplied AccessTokenClaims and returns the
+	// resulting compact-JWS string. Implementations are responsible for
+	// projecting the claims onto the JWT structure they want to emit
+	// (e.g. the RFC 9068 "JWT Profile for OAuth 2.0 Access Tokens").
+	SignAccessToken(ctx context.Context, claims AccessTokenClaims) (string, error)
+}
+
+// JWTAccessTokenGenerator adapts an [AccessTokenSigner] to the
+// [AccessTokenGenerator] interface consumed by the OAuth2 server. The
+// storage-lookup hash is [oauth2.HashToken](nil, token), so revocation and
+// introspection locate the AccessToken record without persisting the raw
+// JWT (the JWS is large; storing only the hash keeps the table compact and
+// removes the leak window). Every lookup path hashes the same way.
+type JWTAccessTokenGenerator struct {
+	signer AccessTokenSigner
+}
+
+// NewJWTAccessTokenGenerator wraps signer into an [AccessTokenGenerator].
+func NewJWTAccessTokenGenerator(signer AccessTokenSigner) *JWTAccessTokenGenerator {
+	if signer == nil {
+		panic("oauth2/token.NewJWTAccessTokenGenerator: nil AccessTokenSigner")
+	}
+
+	return &JWTAccessTokenGenerator{signer: signer}
+}
+
+// Generate implements [AccessTokenGenerator]. It delegates the JWS
+// generation to the signer and computes the storage hash on the result.
+func (g *JWTAccessTokenGenerator) Generate(ctx context.Context, claims AccessTokenClaims) (string, string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", "", fmt.Errorf("oauth2: context canceled: %w", err)
+	}
+
+	token, err := g.signer.SignAccessToken(ctx, claims)
+	if err != nil {
+		return "", "", fmt.Errorf("oauth2: sign access token: %w", err)
+	}
+
+	return token, oauth2.HashToken(nil, token), nil
+}
+
+// Compile-time interface check.
+var _ AccessTokenGenerator = (*JWTAccessTokenGenerator)(nil)
diff --git a/oauth2/token/jwt_test.go b/oauth2/token/jwt_test.go
new file mode 100644
index 0000000..d04bac6
--- /dev/null
+++ b/oauth2/token/jwt_test.go
@@ -0,0 +1,68 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package token_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeSigner is a test double for token.AccessTokenSigner.
+type fakeSigner struct {
+	token string
+	err   error
+}
+
+func (s fakeSigner) SignAccessToken(context.Context, token.AccessTokenClaims) (string, error) {
+	return s.token, s.err
+}
+
+func TestNewJWTAccessTokenGeneratorPanicsOnNilSigner(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() {
+		token.NewJWTAccessTokenGenerator(nil)
+	})
+}
+
+func TestJWTAccessTokenGeneratorGenerate(t *testing.T) {
+	t.Parallel()
+
+	gen := token.NewJWTAccessTokenGenerator(fakeSigner{token: "signed.jwt.value"})
+
+	raw, hash, err := gen.Generate(context.Background(), token.AccessTokenClaims{Subject: "alice"})
+	require.NoError(t, err)
+	assert.Equal(t, "signed.jwt.value", raw)
+	// The storage hash is the canonical hash of the raw JWT — the same one
+	// every lookup path computes.
+	assert.Equal(t, oauth2.HashToken(nil, "signed.jwt.value"), hash)
+}
+
+func TestJWTAccessTokenGeneratorSignerError(t *testing.T) {
+	t.Parallel()
+
+	gen := token.NewJWTAccessTokenGenerator(fakeSigner{err: errors.New("key unavailable")})
+
+	_, _, err := gen.Generate(context.Background(), token.AccessTokenClaims{})
+	require.Error(t, err)
+}
+
+func TestJWTAccessTokenGeneratorContextCancelled(t *testing.T) {
+	t.Parallel()
+
+	gen := token.NewJWTAccessTokenGenerator(fakeSigner{token: "x"})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, _, err := gen.Generate(ctx, token.AccessTokenClaims{})
+	require.ErrorIs(t, err, context.Canceled)
+}
diff --git a/oauth2/token/opaque.go b/oauth2/token/opaque.go
new file mode 100644
index 0000000..6338a80
--- /dev/null
+++ b/oauth2/token/opaque.go
@@ -0,0 +1,101 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package token
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+
+	"github.com/hyperscale-stack/security/oauth2"
+)
+
+// Opaque is the generator for opaque (random) access, refresh and
+// authorization-code tokens. It writes `size` random bytes (default 32),
+// encodes them as base64-url, and hashes the result for storage.
+//
+// The storage hash is [oauth2.HashToken](nil, token) — an unkeyed SHA-256.
+// Opaque tokens carry ≥ 128 bits of entropy, so a bare hash is already
+// preimage- and brute-force-resistant; every lookup path (the grants, the
+// /introspect and /revoke endpoints) hashes the same way, so a token issued
+// here is always found again.
+type Opaque struct {
+	size int
+}
+
+// NewOpaque returns an Opaque generator. size is clamped to 16 bytes
+// minimum to provide ~128 bits of entropy even for the smallest tokens;
+// 32 bytes (256 bits) is the recommended default and the value used when
+// size == 0.
+func NewOpaque(size int) *Opaque {
+	if size == 0 {
+		size = 32
+	}
+
+	if size < 16 {
+		size = 16
+	}
+
+	return &Opaque{size: size}
+}
+
+// Generate implements [AccessTokenGenerator]. The claims are ignored — the
+// opaque token carries no state; storage holds the AccessToken record.
+func (o *Opaque) Generate(ctx context.Context, _ AccessTokenClaims) (string, string, error) {
+	return o.generateRaw(ctx)
+}
+
+// GenerateRefresh implements [RefreshTokenGenerator] (the Generate(ctx)
+// signature with no claims).
+func (o *Opaque) GenerateRefresh(ctx context.Context) (string, string, error) {
+	return o.generateRaw(ctx)
+}
+
+// GenerateCode implements [AuthorizationCodeGenerator].
+func (o *Opaque) GenerateCode(ctx context.Context) (string, string, error) {
+	return o.generateRaw(ctx)
+}
+
+func (o *Opaque) generateRaw(ctx context.Context) (string, string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", "", fmt.Errorf("oauth2: context canceled: %w", err)
+	}
+
+	buf := make([]byte, o.size)
+	if _, err := rand.Read(buf); err != nil {
+		return "", "", fmt.Errorf("oauth2: read random: %w", err)
+	}
+
+	token := base64.RawURLEncoding.EncodeToString(buf)
+	hash := oauth2.HashToken(nil, token)
+
+	return token, hash, nil
+}
+
+// OpaqueRefreshAdapter wraps an [Opaque] so it satisfies
+// [RefreshTokenGenerator] with the no-claims signature.
+type OpaqueRefreshAdapter struct{ *Opaque }
+
+// Generate implements [RefreshTokenGenerator].
+func (a OpaqueRefreshAdapter) Generate(ctx context.Context) (string, string, error) {
+	return a.GenerateRefresh(ctx)
+}
+
+// OpaqueCodeAdapter wraps an [Opaque] so it satisfies
+// [AuthorizationCodeGenerator].
+type OpaqueCodeAdapter struct{ *Opaque }
+
+// Generate implements [AuthorizationCodeGenerator].
+func (a OpaqueCodeAdapter) Generate(ctx context.Context) (string, string, error) {
+	return a.GenerateCode(ctx)
+}
+
+// Compile-time interface checks.
+var (
+	_ AccessTokenGenerator       = (*Opaque)(nil)
+	_ RefreshTokenGenerator      = OpaqueRefreshAdapter{}
+	_ AuthorizationCodeGenerator = OpaqueCodeAdapter{}
+)
diff --git a/oauth2/token/opaque_test.go b/oauth2/token/opaque_test.go
new file mode 100644
index 0000000..3728c6c
--- /dev/null
+++ b/oauth2/token/opaque_test.go
@@ -0,0 +1,80 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package token_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/hyperscale-stack/security/oauth2/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestOpaqueGenerateProducesUniqueRandomTokens(t *testing.T) {
+	t.Parallel()
+
+	g := token.NewOpaque(32)
+
+	a, ha, err := g.Generate(context.Background(), token.AccessTokenClaims{})
+	require.NoError(t, err)
+	b, hb, err := g.Generate(context.Background(), token.AccessTokenClaims{})
+	require.NoError(t, err)
+
+	assert.NotEqual(t, a, b, "tokens MUST be random")
+	assert.NotEqual(t, ha, hb)
+	assert.NotEmpty(t, a)
+	assert.NotEmpty(t, ha)
+}
+
+func TestOpaqueHashMatchesPublicHelper(t *testing.T) {
+	t.Parallel()
+
+	g := token.NewOpaque(16)
+	tok, hash, err := g.Generate(context.Background(), token.AccessTokenClaims{})
+	require.NoError(t, err)
+
+	assert.Equal(t, oauth2.HashToken(nil, tok), hash,
+		"the generator's hash MUST match oauth2.HashToken(nil, …) so every lookup path agrees")
+}
+
+func TestOpaqueSizeClamps(t *testing.T) {
+	t.Parallel()
+
+	g := token.NewOpaque(4) // clamped to 16
+	tok, _, err := g.Generate(context.Background(), token.AccessTokenClaims{})
+	require.NoError(t, err)
+	// base64-url-encoded 16 bytes = 22 chars (no padding).
+	assert.Len(t, tok, 22)
+}
+
+func TestOpaqueContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	g := token.NewOpaque(0)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, _, err := g.Generate(ctx, token.AccessTokenClaims{})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, context.Canceled)
+}
+
+func TestOpaqueRefreshAndCodeAdapters(t *testing.T) {
+	t.Parallel()
+
+	g := token.NewOpaque(32)
+	r := token.OpaqueRefreshAdapter{Opaque: g}
+	c := token.OpaqueCodeAdapter{Opaque: g}
+
+	rt, _, err := r.Generate(context.Background())
+	require.NoError(t, err)
+	assert.NotEmpty(t, rt)
+
+	co, _, err := c.Generate(context.Background())
+	require.NoError(t, err)
+	assert.NotEmpty(t, co)
+}
diff --git a/oauth2/token_endpoint.go b/oauth2/token_endpoint.go
new file mode 100644
index 0000000..e622040
--- /dev/null
+++ b/oauth2/token_endpoint.go
@@ -0,0 +1,160 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+)
+
+// TokenHandler returns the http.Handler for the RFC 6749 §3.2 /token
+// endpoint. The handler:
+//
+//  1. Enforces POST + application/x-www-form-urlencoded.
+//  2. Authenticates the client via the configured ClientAuthenticators.
+//  3. Looks up the grant_type and dispatches to the matching Grant.
+//  4. Serializes the response per RFC 6749 §5.1 (success) or §5.2 (error).
+//
+// Errors are emitted as JSON: {"error":"...","error_description":"..."}.
+func (s *Server) TokenHandler() http.Handler {
+	return http.HandlerFunc(s.serveToken)
+}
+
+func (s *Server) serveToken(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("POST required"))
+
+		return
+	}
+
+	if err := r.ParseForm(); err != nil {
+		writeOAuthError(w, ErrInvalidRequest.WithCause(err))
+
+		return
+	}
+
+	client, err := s.authenticateClient(r.Context(), r)
+	if err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	grantType := r.PostFormValue("grant_type")
+	if grantType == "" {
+		writeOAuthError(w, ErrInvalidRequest.WithDescription("missing grant_type"))
+
+		return
+	}
+
+	handler, ok := s.dispatch[grantType]
+	if !ok {
+		writeOAuthError(w, ErrUnsupportedGrantType.WithDescription("grant_type "+grantType+" not supported"))
+
+		return
+	}
+
+	issuer, audience, err := s.resolveIssuer(r.Context(), r)
+	if err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	resp, err := handler.Handle(r.Context(), GrantRequest{
+		Client:   client,
+		Form:     r.PostForm,
+		Issuer:   issuer,
+		Audience: audience,
+		Now:      s.cfg.Now(),
+		Profile:  s.cfg.Profile,
+	})
+	if err != nil {
+		writeOAuthError(w, err)
+
+		return
+	}
+
+	writeTokenResponse(w, resp)
+}
+
+// tokenResponse is the on-wire JSON body per RFC 6749 §5.1. The
+// AccessToken / RefreshToken field names are mandated by the RFC; gosec
+// flags them under G117 because they look like credentials at rest, but
+// here they describe a transient outbound payload.
+type tokenResponse struct {
+	AccessToken  string `json:"access_token"` //nolint:gosec // wire field name mandated by RFC 6749
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int    `json:"expires_in,omitempty"`
+	RefreshToken string `json:"refresh_token,omitempty"` //nolint:gosec // wire field name mandated by RFC 6749
+	Scope        string `json:"scope,omitempty"`
+}
+
+// writeTokenResponse serializes resp to the standard JSON body and adds
+// Cache-Control / Pragma headers per RFC 6749 §5.1.
+func writeTokenResponse(w http.ResponseWriter, resp *GrantResponse) {
+	body := tokenResponse{
+		AccessToken: resp.Pair.Access.Token,
+		TokenType:   resp.TokenType,
+		ExpiresIn:   int(time.Until(resp.Pair.Access.ExpiresAt).Seconds()),
+		Scope:       resp.Scope,
+	}
+
+	if resp.Pair.Refresh != nil {
+		body.RefreshToken = resp.Pair.Refresh.Token
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Pragma", "no-cache")
+	w.WriteHeader(http.StatusOK)
+
+	//nolint:gosec // G117: token response wire fields are mandated by RFC 6749 §5.1
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		// Best-effort: the status code is already on the wire so there's
+		// nothing actionable left to do.
+		_ = err
+	}
+}
+
+// errorResponse is the on-wire JSON body per RFC 6749 §5.2.
+type errorResponse struct {
+	Error            string `json:"error"`
+	ErrorDescription string `json:"error_description,omitempty"`
+	ErrorURI         string `json:"error_uri,omitempty"`
+}
+
+// writeOAuthError serializes err as an RFC 6749 §5.2 envelope. Non-OAuth
+// errors collapse to server_error so the wire response stays compliant.
+func writeOAuthError(w http.ResponseWriter, err error) {
+	var oe *Error
+	if !errors.As(err, &oe) {
+		oe = ErrServerError.WithCause(err)
+	}
+
+	body := errorResponse{
+		Error:            oe.Code,
+		ErrorDescription: oe.Description,
+		ErrorURI:         oe.URI,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Pragma", "no-cache")
+
+	if oe.Code == CodeInvalidClient {
+		// RFC 6749 §5.2: invalid_client MUST be paired with WWW-Authenticate
+		// Basic when the client used HTTP Basic.
+		w.Header().Set("WWW-Authenticate", `Basic realm="oauth2"`)
+	}
+
+	w.WriteHeader(oe.HTTPStatus())
+
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		_ = err
+	}
+}
diff --git a/oauth2/values_test.go b/oauth2/values_test.go
new file mode 100644
index 0000000..00c2afa
--- /dev/null
+++ b/oauth2/values_test.go
@@ -0,0 +1,208 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package oauth2_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/oauth2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestErrorError(t *testing.T) {
+	t.Parallel()
+
+	withDesc := &oauth2.Error{Code: oauth2.CodeInvalidGrant, Description: "expired"}
+	assert.Equal(t, "oauth2: invalid_grant: expired", withDesc.Error())
+
+	bare := &oauth2.Error{Code: oauth2.CodeInvalidGrant}
+	assert.Equal(t, "oauth2: invalid_grant", bare.Error())
+}
+
+func TestErrorUnwrapAndIs(t *testing.T) {
+	t.Parallel()
+
+	// The sentinels wrap a core security sentinel via the cause chain.
+	assert.ErrorIs(t, oauth2.ErrInvalidClient, security.ErrClientSecretMismatch)
+	assert.ErrorIs(t, oauth2.ErrInvalidGrant, security.ErrInvalidCredentials)
+	assert.ErrorIs(t, oauth2.ErrUnsupportedGrantType, security.ErrUnsupportedCredential)
+	assert.ErrorIs(t, oauth2.ErrAccessDenied, security.ErrAccessDenied)
+
+	// ErrServerError has a nil cause: Unwrap returns nil, no panic.
+	assert.NoError(t, oauth2.ErrServerError.Unwrap())
+}
+
+func TestErrorHTTPStatus(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		code string
+		want int
+	}{
+		{oauth2.CodeInvalidClient, http.StatusUnauthorized},
+		{oauth2.CodeAccessDenied, http.StatusForbidden},
+		{oauth2.CodeServerError, http.StatusInternalServerError},
+		{oauth2.CodeTemporarilyUnavailable, http.StatusServiceUnavailable},
+		{oauth2.CodeInvalidRequest, http.StatusBadRequest},
+		{oauth2.CodeInvalidGrant, http.StatusBadRequest},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.code, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tc.want, (&oauth2.Error{Code: tc.code}).HTTPStatus())
+		})
+	}
+}
+
+func TestIsCode(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, oauth2.CodeInvalidGrant, oauth2.IsCode(oauth2.ErrInvalidGrant))
+	assert.Equal(t, oauth2.CodeInvalidGrant,
+		oauth2.IsCode(fmt.Errorf("wrapped: %w", oauth2.ErrInvalidGrant)))
+	assert.Empty(t, oauth2.IsCode(errors.New("not an oauth2 error")))
+	assert.Empty(t, oauth2.IsCode(nil))
+}
+
+func TestErrorWithDescription(t *testing.T) {
+	t.Parallel()
+
+	got := oauth2.ErrInvalidGrant.WithDescription("code expired")
+	assert.Equal(t, "code expired", got.Description)
+	assert.Equal(t, oauth2.CodeInvalidGrant, got.Code)
+	// The sentinel stays immutable.
+	assert.NotEqual(t, "code expired", oauth2.ErrInvalidGrant.Description)
+}
+
+func TestErrorWithCause(t *testing.T) {
+	t.Parallel()
+
+	root := errors.New("disk on fire")
+	got := oauth2.ErrServerError.WithCause(root)
+
+	assert.ErrorIs(t, got, root)
+	assert.Equal(t, oauth2.CodeServerError, got.Code)
+	// Original sentinel untouched.
+	assert.NotErrorIs(t, oauth2.ErrServerError, root)
+
+	// WithCause on a sentinel that already has a cause keeps both reachable.
+	chained := oauth2.ErrInvalidGrant.WithCause(root)
+	assert.ErrorIs(t, chained, root)
+	assert.ErrorIs(t, chained, security.ErrInvalidCredentials)
+}
+
+func TestProfileString(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "oauth2.0-bcp", oauth2.Profile20BCP.String())
+	assert.Equal(t, "oauth2.0", oauth2.Profile20.String())
+	assert.Equal(t, "oauth2.1-draft", oauth2.Profile21Draft.String())
+	assert.Equal(t, "unknown", oauth2.Profile(99).String())
+}
+
+func TestProfilePredicates(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		profile                                        oauth2.Profile
+		legacy, pkce, rotation, plainPKCE              bool
+	}{
+		{oauth2.Profile20, true, false, false, true},
+		{oauth2.Profile20BCP, false, true, true, false},
+		{oauth2.Profile21Draft, false, true, true, false},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.profile.String(), func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tc.legacy, tc.profile.AllowsLegacyGrant())
+			assert.Equal(t, tc.pkce, tc.profile.RequiresPKCE())
+			assert.Equal(t, tc.rotation, tc.profile.RequiresRefreshRotation())
+			assert.Equal(t, tc.plainPKCE, tc.profile.AllowsPKCEPlain())
+		})
+	}
+}
+
+func TestModelsIsExpired(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	past := now.Add(-time.Minute)
+	future := now.Add(time.Minute)
+
+	code := &oauth2.AuthorizationCode{ExpiresAt: past}
+	assert.True(t, code.IsExpired(now))
+	assert.False(t, (&oauth2.AuthorizationCode{ExpiresAt: future}).IsExpired(now))
+
+	at := &oauth2.AccessToken{ExpiresAt: past}
+	assert.True(t, at.IsExpired(now))
+	assert.False(t, (&oauth2.AccessToken{ExpiresAt: future}).IsExpired(now))
+
+	rt := &oauth2.RefreshToken{ExpiresAt: past}
+	assert.True(t, rt.IsExpired(now))
+	assert.False(t, (&oauth2.RefreshToken{ExpiresAt: future}).IsExpired(now))
+}
+
+func TestHashToken(t *testing.T) {
+	t.Parallel()
+
+	pepper := []byte("server-wide-secret")
+
+	// Deterministic for the same (pepper, token).
+	assert.Equal(t, oauth2.HashToken(pepper, "tok"), oauth2.HashToken(pepper, "tok"))
+	// Different token -> different hash.
+	assert.NotEqual(t, oauth2.HashToken(pepper, "tok"), oauth2.HashToken(pepper, "other"))
+	// Different pepper -> different hash.
+	assert.NotEqual(t, oauth2.HashToken(pepper, "tok"), oauth2.HashToken([]byte("x"), "tok"))
+	// SHA-256 HMAC hex output is 64 characters.
+	assert.Len(t, oauth2.HashToken(pepper, "tok"), 64)
+}
+
+func TestDefaultClient(t *testing.T) {
+	t.Parallel()
+
+	c := &oauth2.DefaultClient{
+		IDValue:           "client-1",
+		Secret:            "s3cr3t",
+		TypeValue:         oauth2.ClientConfidential,
+		RedirectURIValues: []string{"https://app.example/cb"},
+		GrantTypeValues:   []string{"authorization_code"},
+		ScopeValues:       []string{"read"},
+		AuthMethodValues:  []string{"client_secret_basic"},
+	}
+
+	assert.Equal(t, "client-1", c.ID())
+	assert.Equal(t, oauth2.ClientConfidential, c.Type())
+	assert.Equal(t, []string{"https://app.example/cb"}, c.RedirectURIs())
+	assert.Equal(t, []string{"authorization_code"}, c.GrantTypes())
+	assert.Equal(t, []string{"read"}, c.Scopes())
+	assert.Equal(t, []string{"client_secret_basic"}, c.AuthMethods())
+
+	assert.True(t, c.SecretMatches("s3cr3t"))
+	assert.False(t, c.SecretMatches("wrong"))
+	assert.False(t, c.SecretMatches(""))
+}
+
+func TestStaticIssuer(t *testing.T) {
+	t.Parallel()
+
+	resolver := oauth2.StaticIssuer("https://auth.example", "api")
+
+	req := httptest.NewRequest(http.MethodGet, "/.well-known/oauth-authorization-server", nil)
+
+	iss, aud, err := resolver.Resolve(context.Background(), req)
+	require.NoError(t, err)
+	assert.Equal(t, "https://auth.example", iss)
+	assert.Equal(t, "api", aud)
+}
diff --git a/otel.go b/otel.go
new file mode 100644
index 0000000..9da6a8d
--- /dev/null
+++ b/otel.go
@@ -0,0 +1,64 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import (
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// trAttrName is a tiny helper that wraps a name into an event option to keep
+// span.AddEvent calls succinct.
+func trAttrName(name string) trace.EventOption {
+	return trace.WithAttributes(AttrAuthenticatorName.String(name))
+}
+
+// tracerName is the OTel instrumentation scope name for the core package.
+// Sub-modules MUST use their own scope (e.g. github.com/hyperscale-stack/security/http)
+// to keep span attribution unambiguous.
+const tracerName = "github.com/hyperscale-stack/security"
+
+// tracer returns the package-level tracer. Callers should not cache it across
+// goroutines; the OTel SDK already memoizes the returned tracer.
+func tracer() trace.Tracer { return otel.Tracer(tracerName) }
+
+// Span attribute keys used across the core. They are kept here as typed
+// constants so that documentation in docs/observability.md can be diffed
+// against the source of truth.
+const (
+	// AttrAuthenticated reports whether the resulting Authentication is
+	// authenticated. Value: bool.
+	AttrAuthenticated = attribute.Key("security.authenticated")
+
+	// AttrPrincipalSubject is the principal subject. Emission is gated by the
+	// subject-redaction policy (see SetSubjectAttributeMode) to avoid leaking
+	// personal data into trace backends; the default is a hashed prefix.
+	AttrPrincipalSubject = attribute.Key("security.principal.subject")
+
+	// AttrExtractorsCount counts the extractors tried by an Engine call.
+	// Value: int.
+	AttrExtractorsCount = attribute.Key("security.extractors.count")
+
+	// AttrAuthenticatorsCount counts the authenticators tried by a Manager.
+	// Value: int.
+	AttrAuthenticatorsCount = attribute.Key("security.authenticators.count")
+
+	// AttrAuthenticatorName names the authenticator that produced the final
+	// authenticated value, when known. Value: string.
+	AttrAuthenticatorName = attribute.Key("security.authenticator.name")
+
+	// AttrStrategy names the AccessDecisionManager strategy that took the
+	// final decision. Value: "affirmative" | "consensus" | "unanimous".
+	AttrStrategy = attribute.Key("security.strategy")
+
+	// AttrDecision is the final authorization decision.
+	// Value: "permit" | "deny" | "abstain".
+	AttrDecision = attribute.Key("security.decision")
+
+	// AttrAttributes is the joined String() form of the Attributes considered
+	// for an authorization decision. Value: string.
+	AttrAttributes = attribute.Key("security.attributes")
+)
diff --git a/otel_testing_test.go b/otel_testing_test.go
new file mode 100644
index 0000000..8927980
--- /dev/null
+++ b/otel_testing_test.go
@@ -0,0 +1,57 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"sync"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/sdk/trace/tracetest"
+)
+
+// otelMu serialises every test that installs a TracerProvider so that
+// concurrent t.Parallel runs do not stomp on each other's recorders.
+// Any test that calls spanRecorder MUST NOT call t.Parallel().
+var otelMu sync.Mutex
+
+// spanRecorder installs an in-memory OTel exporter as the global tracer
+// provider for the duration of a test, and returns the spans captured during
+// the call to fn.
+//
+// The exporter is goroutine-safe; callers passing fn that spawns goroutines
+// should Synchronize via the SpanRecorder's flush mechanics — out of scope
+// for the current tests.
+func spanRecorder(fn func()) []sdktrace.ReadOnlySpan {
+	otelMu.Lock()
+	defer otelMu.Unlock()
+
+	previous := otel.GetTracerProvider()
+
+	rec := tracetest.NewSpanRecorder()
+	tp := sdktrace.NewTracerProvider(sdktrace.WithSpanProcessor(rec))
+	otel.SetTracerProvider(tp)
+
+	defer otel.SetTracerProvider(previous)
+
+	fn()
+
+	_ = tp.Shutdown(context.Background())
+
+	return rec.Ended()
+}
+
+// findAttr returns the value of attr in attrs as a string, or "" if missing.
+func findAttr(attrs []attribute.KeyValue, key attribute.Key) string {
+	for _, a := range attrs {
+		if a.Key == key {
+			return a.Value.Emit()
+		}
+	}
+
+	return ""
+}
diff --git a/password/argon2id.go b/password/argon2id.go
new file mode 100644
index 0000000..5e43a36
--- /dev/null
+++ b/password/argon2id.go
@@ -0,0 +1,248 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package password
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/crypto/argon2"
+)
+
+// Argon2idParams configures Argon2id. Values follow the PHC string format
+// (memory in KiB, time in iterations, parallelism in threads).
+//
+// The default profile (see [DefaultArgon2idParams]) is RFC 9106 §4 / OWASP
+// 2024: memory=19 MiB, time=2, parallelism=1, key length 32 bytes, salt
+// length 16 bytes. This profile aims at ~50 ms on a contemporary x86 core.
+type Argon2idParams struct {
+	// MemoryKiB is the memory cost in kibibytes. Higher values strengthen
+	// the hash against GPU/ASIC attacks but slow login down proportionally.
+	MemoryKiB uint32
+	// Time is the iteration count.
+	Time uint32
+	// Parallelism is the lane count.
+	Parallelism uint8
+	// KeyLen is the output length in bytes.
+	KeyLen uint32
+	// SaltLen is the salt length in bytes. The salt is generated with
+	// crypto/rand on every Hash call.
+	SaltLen uint32
+}
+
+// DefaultArgon2idParams returns the OWASP 2024 / RFC 9106 §4 profile.
+// Operators free to harden it for their threat model via NewArgon2idHasher.
+func DefaultArgon2idParams() Argon2idParams {
+	return Argon2idParams{
+		MemoryKiB:   19 * 1024, // 19 MiB
+		Time:        2,
+		Parallelism: 1,
+		KeyLen:      32,
+		SaltLen:     16,
+	}
+}
+
+// Argon2idHasher implements [Hasher] using Argon2id from
+// golang.org/x/crypto/argon2.
+type Argon2idHasher struct {
+	params Argon2idParams
+}
+
+// NewArgon2idHasher returns a [Hasher] configured with params. Zero-valued
+// fields are replaced with [DefaultArgon2idParams] equivalents to keep the
+// hasher usable from `&Argon2idHasher{}` without surprising silent zeroes.
+func NewArgon2idHasher(params Argon2idParams) *Argon2idHasher {
+	d := DefaultArgon2idParams()
+
+	if params.MemoryKiB == 0 {
+		params.MemoryKiB = d.MemoryKiB
+	}
+
+	if params.Time == 0 {
+		params.Time = d.Time
+	}
+
+	if params.Parallelism == 0 {
+		params.Parallelism = d.Parallelism
+	}
+
+	if params.KeyLen == 0 {
+		params.KeyLen = d.KeyLen
+	}
+
+	if params.SaltLen == 0 {
+		params.SaltLen = d.SaltLen
+	}
+
+	return &Argon2idHasher{params: params}
+}
+
+// Params returns the hasher's effective parameters. Useful in tests and for
+// observability.
+func (h *Argon2idHasher) Params() Argon2idParams { return h.params }
+
+// Hash implements [Hasher]. The output follows the PHC string format:
+//
+//	$argon2id$v=19$m=<KiB>,t=<iter>,p=<threads>$<base64salt>$<base64hash>
+//
+// The format is interoperable with libsodium, OpenSSH, and most modern
+// argon2id implementations.
+func (h *Argon2idHasher) Hash(ctx context.Context, password string) (string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", fmt.Errorf("password: context canceled: %w", err)
+	}
+
+	salt := make([]byte, h.params.SaltLen)
+	if _, err := rand.Read(salt); err != nil {
+		return "", fmt.Errorf("password: read salt: %w", err)
+	}
+
+	key := argon2.IDKey(
+		[]byte(password), salt,
+		h.params.Time, h.params.MemoryKiB, h.params.Parallelism, h.params.KeyLen,
+	)
+
+	return encodeArgon2idPHC(h.params, salt, key), nil
+}
+
+// Verify implements [Hasher]. It returns (false, nil) on plain mismatch and
+// an error only when the hash is malformed or the algorithm prefix differs.
+func (h *Argon2idHasher) Verify(ctx context.Context, encodedHash, password string) (bool, error) {
+	if err := ctx.Err(); err != nil {
+		return false, fmt.Errorf("password: context canceled: %w", err)
+	}
+
+	p, salt, expected, err := decodeArgon2idPHC(encodedHash)
+	if err != nil {
+		return false, err
+	}
+
+	got := argon2.IDKey([]byte(password), salt, p.Time, p.MemoryKiB, p.Parallelism, p.KeyLen)
+
+	if subtle.ConstantTimeCompare(expected, got) == 1 {
+		return true, nil
+	}
+
+	return false, nil
+}
+
+// NeedsRehash implements [Hasher]: true when the algorithm is not argon2id
+// or when any stored parameter is strictly weaker than the current
+// configuration.
+func (h *Argon2idHasher) NeedsRehash(encodedHash string) bool {
+	p, _, _, err := decodeArgon2idPHC(encodedHash)
+	if err != nil {
+		return true
+	}
+
+	return p.MemoryKiB < h.params.MemoryKiB ||
+		p.Time < h.params.Time ||
+		p.Parallelism < h.params.Parallelism ||
+		p.KeyLen < h.params.KeyLen
+}
+
+// encodeArgon2idPHC formats the parameters, salt and key in the PHC string
+// format. base64 padding is intentionally stripped (PHC convention).
+func encodeArgon2idPHC(p Argon2idParams, salt, key []byte) string {
+	enc := base64.RawStdEncoding
+
+	var b strings.Builder
+
+	b.Grow(96)
+	b.WriteString("$argon2id$v=")
+	b.WriteString(strconv.Itoa(argon2.Version))
+	b.WriteString("$m=")
+	b.WriteString(strconv.FormatUint(uint64(p.MemoryKiB), 10))
+	b.WriteString(",t=")
+	b.WriteString(strconv.FormatUint(uint64(p.Time), 10))
+	b.WriteString(",p=")
+	b.WriteString(strconv.FormatUint(uint64(p.Parallelism), 10))
+	b.WriteByte('$')
+	b.WriteString(enc.EncodeToString(salt))
+	b.WriteByte('$')
+	b.WriteString(enc.EncodeToString(key))
+
+	return b.String()
+}
+
+// decodeArgon2idPHC parses a PHC-formatted argon2id hash. Strict on prefix
+// and field shape; tolerant of base64 padding to interop with implementations
+// that emit RawStdEncoding output.
+func decodeArgon2idPHC(s string) (Argon2idParams, []byte, []byte, error) {
+	parts := strings.Split(s, "$")
+	// Expected layout: ["", "argon2id", "v=19", "m=...,t=...,p=...", salt, key]
+	// Algorithm check first so cross-algorithm inputs (bcrypt, scrypt) get a
+	// clear ErrUnsupportedAlgorithm even when their layout has fewer fields.
+	if len(parts) < 2 {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	if parts[1] != "argon2id" {
+		return Argon2idParams{}, nil, nil, ErrUnsupportedAlgorithm
+	}
+
+	if len(parts) != 6 {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	if !strings.HasPrefix(parts[2], "v=") {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	version, err := strconv.Atoi(parts[2][2:])
+	if err != nil || version != argon2.Version {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	var (
+		mem, tim uint64
+		par      uint64
+	)
+
+	for _, kv := range strings.Split(parts[3], ",") {
+		switch {
+		case strings.HasPrefix(kv, "m="):
+			mem, err = strconv.ParseUint(kv[2:], 10, 32)
+		case strings.HasPrefix(kv, "t="):
+			tim, err = strconv.ParseUint(kv[2:], 10, 32)
+		case strings.HasPrefix(kv, "p="):
+			par, err = strconv.ParseUint(kv[2:], 10, 8)
+		default:
+			err = errors.New("unknown key")
+		}
+
+		if err != nil {
+			return Argon2idParams{}, nil, nil, ErrMalformedHash
+		}
+	}
+
+	salt, err := base64.RawStdEncoding.DecodeString(parts[4])
+	if err != nil {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	key, err := base64.RawStdEncoding.DecodeString(parts[5])
+	if err != nil {
+		return Argon2idParams{}, nil, nil, ErrMalformedHash
+	}
+
+	// len() on a decoded base64 string is bounded by the input length
+	// (a few hundred bytes at most for a sane hash). The uint32 conversion
+	// cannot overflow in practice — gosec's static analyser cannot prove
+	// that, hence the explicit annotation.
+	return Argon2idParams{
+		MemoryKiB:   uint32(mem),
+		Time:        uint32(tim),
+		Parallelism: uint8(par),
+		KeyLen:      uint32(len(key)),  //nolint:gosec // bounded by base64 of <= 64-byte key
+		SaltLen:     uint32(len(salt)), //nolint:gosec // bounded by base64 of <= 64-byte salt
+	}, salt, key, nil
+}
diff --git a/password/argon2id_test.go b/password/argon2id_test.go
new file mode 100644
index 0000000..1717bff
--- /dev/null
+++ b/password/argon2id_test.go
@@ -0,0 +1,158 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package password_test
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/hyperscale-stack/security/password"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fast2idParams is a deliberately cheap parameter set used in unit tests so
+// the whole suite stays under a few hundred ms while still exercising every
+// code path.
+func fast2idParams() password.Argon2idParams {
+	return password.Argon2idParams{
+		MemoryKiB:   8 * 1024, // 8 MiB
+		Time:        1,
+		Parallelism: 1,
+		KeyLen:      32,
+		SaltLen:     16,
+	}
+}
+
+func TestArgon2idRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+
+	encoded, err := h.Hash(context.Background(), "p4ssw0rd")
+	require.NoError(t, err)
+	assert.True(t, strings.HasPrefix(encoded, "$argon2id$"), "got %q", encoded)
+
+	ok, err := h.Verify(context.Background(), encoded, "p4ssw0rd")
+	require.NoError(t, err)
+	assert.True(t, ok)
+}
+
+func TestArgon2idMismatchReturnsFalseNilError(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+	encoded, _ := h.Hash(context.Background(), "right")
+
+	ok, err := h.Verify(context.Background(), encoded, "wrong")
+	require.NoError(t, err)
+	assert.False(t, ok)
+}
+
+func TestArgon2idVerifyRejectsWrongAlgorithm(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+
+	_, err := h.Verify(context.Background(), "$2a$04$abc", "x")
+	assert.ErrorIs(t, err, password.ErrUnsupportedAlgorithm)
+}
+
+func TestArgon2idVerifyRejectsMalformedHash(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+
+	cases := []string{
+		"",
+		"$argon2id$v=19",                       // too few fields
+		"$argon2id$v=99$m=8,t=1,p=1$aaa$bbb",   // wrong version
+		"$argon2id$v=19$m=x,t=1,p=1$aaa$bbb",   // bad memory
+		"$argon2id$v=19$m=8,t=1,p=1$!!$bbb",    // bad base64 salt
+		"$argon2id$v=19$m=8,t=1,p=1$aGVsbG8$!!",// bad base64 key
+	}
+	for _, c := range cases {
+		_, err := h.Verify(context.Background(), c, "x")
+		assert.ErrorIsf(t, err, password.ErrMalformedHash, "input %q", c)
+	}
+}
+
+func TestArgon2idNeedsRehashOnWeakerParameters(t *testing.T) {
+	t.Parallel()
+
+	lo := password.NewArgon2idHasher(password.Argon2idParams{
+		MemoryKiB: 8 * 1024, Time: 1, Parallelism: 1, KeyLen: 32, SaltLen: 16,
+	})
+	hi := password.NewArgon2idHasher(password.Argon2idParams{
+		MemoryKiB: 16 * 1024, Time: 2, Parallelism: 1, KeyLen: 32, SaltLen: 16,
+	})
+
+	encoded, _ := lo.Hash(context.Background(), "x")
+	assert.False(t, lo.NeedsRehash(encoded))
+	assert.True(t, hi.NeedsRehash(encoded), "stored params weaker than configured")
+	assert.True(t, lo.NeedsRehash("$2a$04$xxx"), "cross-algorithm triggers rehash")
+}
+
+func TestArgon2idHashIsRandomized(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+	a, _ := h.Hash(context.Background(), "same")
+	b, _ := h.Hash(context.Background(), "same")
+	assert.NotEqual(t, a, b, "fresh salt per call must produce different hashes")
+}
+
+func TestDefaultArgon2idParamsMatchOWASP(t *testing.T) {
+	t.Parallel()
+
+	p := password.DefaultArgon2idParams()
+	assert.Equal(t, uint32(19*1024), p.MemoryKiB, "OWASP 2024 baseline = 19 MiB")
+	assert.Equal(t, uint32(2), p.Time)
+	assert.Equal(t, uint8(1), p.Parallelism)
+	assert.Equal(t, uint32(32), p.KeyLen)
+	assert.Equal(t, uint32(16), p.SaltLen)
+}
+
+func TestArgon2idZeroParamsAreReplacedWithDefaults(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(password.Argon2idParams{})
+	def := password.DefaultArgon2idParams()
+	assert.Equal(t, def, h.Params(), "all-zero input must reuse the OWASP defaults")
+}
+
+func TestArgon2idIsRaceSafe(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewArgon2idHasher(fast2idParams())
+	encoded, _ := h.Hash(context.Background(), "x")
+
+	var wg sync.WaitGroup
+	for range 32 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+			ok, err := h.Verify(context.Background(), encoded, "x")
+			assert.NoError(t, err)
+			assert.True(t, ok)
+		}()
+	}
+
+	wg.Wait()
+}
+
+func TestArgon2idContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := password.NewArgon2idHasher(fast2idParams()).Hash(ctx, "x")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, context.Canceled)
+}
diff --git a/password/bcrypt.go b/password/bcrypt.go
new file mode 100644
index 0000000..25093d5
--- /dev/null
+++ b/password/bcrypt.go
@@ -0,0 +1,103 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package password
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+// BCryptHasher implements [Hasher] on top of golang.org/x/crypto/bcrypt.
+// It is the most widely deployed password hash and a good default for
+// projects that do not need argon2id-level memory hardness.
+type BCryptHasher struct {
+	cost int
+}
+
+// NewBCryptHasher returns a [Hasher] backed by bcrypt at the given cost.
+// Cost values below [bcrypt.MinCost] are clamped to bcrypt.MinCost; values
+// above [bcrypt.MaxCost] are clamped to bcrypt.MaxCost. Passing 0 yields
+// [bcrypt.DefaultCost] (12 as of bcrypt v0.x).
+func NewBCryptHasher(cost int) *BCryptHasher {
+	switch {
+	case cost == 0:
+		cost = bcrypt.DefaultCost
+	case cost < bcrypt.MinCost:
+		cost = bcrypt.MinCost
+	case cost > bcrypt.MaxCost:
+		cost = bcrypt.MaxCost
+	}
+
+	return &BCryptHasher{cost: cost}
+}
+
+// Cost returns the configured bcrypt cost. Useful in tests and for
+// observability.
+func (h *BCryptHasher) Cost() int { return h.cost }
+
+// Hash implements [Hasher].
+func (h *BCryptHasher) Hash(ctx context.Context, password string) (string, error) {
+	if err := ctx.Err(); err != nil {
+		return "", fmt.Errorf("password: context canceled: %w", err)
+	}
+
+	out, err := bcrypt.GenerateFromPassword([]byte(password), h.cost)
+	if err != nil {
+		return "", fmt.Errorf("password: bcrypt hash: %w", err)
+	}
+
+	return string(out), nil
+}
+
+// Verify implements [Hasher]. A plain mismatch returns (false, nil).
+func (h *BCryptHasher) Verify(ctx context.Context, encodedHash, password string) (bool, error) {
+	if err := ctx.Err(); err != nil {
+		return false, fmt.Errorf("password: context canceled: %w", err)
+	}
+
+	if !looksLikeBCrypt(encodedHash) {
+		return false, ErrUnsupportedAlgorithm
+	}
+
+	err := bcrypt.CompareHashAndPassword([]byte(encodedHash), []byte(password))
+	if err == nil {
+		return true, nil
+	}
+
+	if errors.Is(err, bcrypt.ErrMismatchedHashAndPassword) {
+		return false, nil
+	}
+
+	return false, fmt.Errorf("password: bcrypt compare: %w", err)
+}
+
+// NeedsRehash implements [Hasher]: it returns true when the stored cost is
+// strictly below the hasher's configured cost (the case after the operator
+// raised the security baseline) or when the encoded hash is not a bcrypt
+// blob at all (e.g. migration from another algorithm).
+func (h *BCryptHasher) NeedsRehash(encodedHash string) bool {
+	if !looksLikeBCrypt(encodedHash) {
+		return true
+	}
+
+	cost, err := bcrypt.Cost([]byte(encodedHash))
+	if err != nil {
+		return true
+	}
+
+	return cost < h.cost
+}
+
+// looksLikeBCrypt is a cheap discriminator: every bcrypt blob starts with
+// "$2", whether it's $2a (Wing/Sun reference), $2b (OpenBSD ≥ 5.5) or $2y
+// (PHP-friendly variant). Other algorithms (argon2id, scrypt, plain) start
+// with another prefix.
+func looksLikeBCrypt(h string) bool {
+	return strings.HasPrefix(h, "$2")
+}
diff --git a/password/bcrypt_hasher.go b/password/bcrypt_hasher.go
deleted file mode 100644
index 96b19cf..0000000
--- a/password/bcrypt_hasher.go
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package password
-
-import "golang.org/x/crypto/bcrypt"
-
-var _ Hasher = (*BCryptHasher)(nil)
-
-// BCryptHasher is a implementation of Hasher that uses the BCrypt strong hashing function.
-type BCryptHasher struct {
-	cost int
-}
-
-// NewBCryptHasher constructor.
-func NewBCryptHasher(cost int) Hasher {
-	return &BCryptHasher{
-		cost: cost,
-	}
-}
-
-// Hash the raw password.
-func (e *BCryptHasher) Hash(password string) (string, error) {
-	pwd, err := bcrypt.GenerateFromPassword([]byte(password), e.cost)
-
-	return string(pwd), err
-}
-
-// Verify the hashed and clear password is equals.
-func (e *BCryptHasher) Verify(hashed string, password string) bool {
-	err := bcrypt.CompareHashAndPassword([]byte(hashed), []byte(password))
-
-	return err == nil
-}
diff --git a/password/bcrypt_hasher_test.go b/password/bcrypt_hasher_test.go
deleted file mode 100644
index 796ee4f..0000000
--- a/password/bcrypt_hasher_test.go
+++ /dev/null
@@ -1,29 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package password
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"golang.org/x/crypto/bcrypt"
-)
-
-func TestBCryptHasherHash(t *testing.T) {
-	e := NewBCryptHasher(10)
-
-	hash, err := e.Hash("foo")
-	assert.NoError(t, err)
-
-	cost, err := bcrypt.Cost([]byte(hash))
-	assert.NoError(t, err)
-
-	assert.Equal(t, 10, cost)
-
-	err = bcrypt.CompareHashAndPassword([]byte(hash), []byte("foo"))
-	assert.NoError(t, err)
-
-	assert.True(t, e.Verify(hash, "foo"))
-}
diff --git a/password/bcrypt_test.go b/password/bcrypt_test.go
new file mode 100644
index 0000000..3b73b45
--- /dev/null
+++ b/password/bcrypt_test.go
@@ -0,0 +1,115 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package password_test
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/hyperscale-stack/security/password"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBCryptRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewBCryptHasher(4) // MinCost for fast tests
+
+	encoded, err := h.Hash(context.Background(), "p4ssw0rd")
+	require.NoError(t, err)
+	assert.True(t, strings.HasPrefix(encoded, "$2"), "got %q", encoded)
+
+	ok, err := h.Verify(context.Background(), encoded, "p4ssw0rd")
+	require.NoError(t, err)
+	assert.True(t, ok)
+}
+
+func TestBCryptMismatchReturnsFalseNilError(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewBCryptHasher(4)
+	encoded, _ := h.Hash(context.Background(), "correct")
+
+	ok, err := h.Verify(context.Background(), encoded, "wrong")
+	require.NoError(t, err, "mismatch must not surface as an error")
+	assert.False(t, ok)
+}
+
+func TestBCryptVerifyRejectsNonBCryptHash(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewBCryptHasher(4)
+
+	_, err := h.Verify(context.Background(), "not-a-bcrypt", "anything")
+	assert.ErrorIs(t, err, password.ErrUnsupportedAlgorithm)
+}
+
+func TestBCryptNeedsRehash(t *testing.T) {
+	t.Parallel()
+
+	lo := password.NewBCryptHasher(4)
+	hi := password.NewBCryptHasher(6)
+
+	encodedLo, _ := lo.Hash(context.Background(), "x")
+
+	assert.False(t, lo.NeedsRehash(encodedLo), "same cost, no rehash needed")
+	assert.True(t, hi.NeedsRehash(encodedLo), "stored cost < hi.cost, rehash needed")
+
+	assert.True(t, lo.NeedsRehash("$argon2id$v=19$m=...$xx$yy"),
+		"different algorithm always triggers rehash")
+	assert.True(t, lo.NeedsRehash("garbage"))
+}
+
+func TestBCryptCostClamps(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		give, want int
+	}{
+		{0, 10},  // bcrypt.DefaultCost (x/crypto/bcrypt)
+		{3, 4},   // clamp to MinCost
+		{50, 31}, // clamp to MaxCost
+		{7, 7},
+	}
+	for _, c := range cases {
+		got := password.NewBCryptHasher(c.give).Cost()
+		assert.Equal(t, c.want, got, "input %d", c.give)
+	}
+}
+
+func TestBCryptContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := password.NewBCryptHasher(4).Hash(ctx, "x")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, context.Canceled)
+}
+
+func TestBCryptIsRaceSafe(t *testing.T) {
+	t.Parallel()
+
+	h := password.NewBCryptHasher(4)
+	encoded, _ := h.Hash(context.Background(), "x")
+
+	var wg sync.WaitGroup
+	for range 50 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+			ok, err := h.Verify(context.Background(), encoded, "x")
+			assert.NoError(t, err)
+			assert.True(t, ok)
+		}()
+	}
+
+	wg.Wait()
+}
diff --git a/password/doc.go b/password/doc.go
new file mode 100644
index 0000000..68720e1
--- /dev/null
+++ b/password/doc.go
@@ -0,0 +1,28 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package password provides password hashing primitives for the security
+// library.
+//
+// The Hasher interface is intentionally minimal: it covers hashing (with
+// cancellable context), verification (returning a typed boolean plus an
+// error for malformed input), and a NeedsRehash hook so applications can
+// upgrade hashes transparently when the configured cost / KDF parameters
+// drift away from the stored ones.
+//
+// Two implementations are shipped:
+//
+//   - BCryptHasher       — bcrypt via golang.org/x/crypto/bcrypt, default
+//     cost is bcrypt.DefaultCost.
+//   - Argon2idHasher     — Argon2id via golang.org/x/crypto/argon2, with
+//     parameters encoded into the hash so downstream
+//     consumers can decode and verify without
+//     out-of-band configuration.
+//
+// Both implementations are safe for concurrent use and never log secrets.
+//
+// Allowed dependencies:
+//   - golang.org/x/crypto
+//   - stdlib only
+package password
diff --git a/password/errors.go b/password/errors.go
new file mode 100644
index 0000000..1823052
--- /dev/null
+++ b/password/errors.go
@@ -0,0 +1,28 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package password
+
+import "errors"
+
+// Sentinel errors.
+var (
+	// ErrMismatch is returned by Verify when the password does not match the
+	// hash. Callers SHOULD NOT distinguish ErrMismatch from "user not found"
+	// in user-facing messages to avoid account-enumeration leaks; the typed
+	// error is only here so application code can branch on it for metrics
+	// or rate-limiting.
+	ErrMismatch = errors.New("password: mismatch")
+
+	// ErrUnsupportedAlgorithm is returned by Verify / NeedsRehash when the
+	// encoded hash uses an algorithm the hasher does not know how to parse.
+	// It typically signals a mistake in the application's storage layer
+	// (mixing bcrypt and argon2id without an algorithm-aware dispatcher).
+	ErrUnsupportedAlgorithm = errors.New("password: unsupported algorithm")
+
+	// ErrMalformedHash is returned by Verify when the encoded hash exists
+	// for the right algorithm but cannot be decoded (truncated, corrupted,
+	// wrong number of fields, …). It is typically a storage-corruption bug.
+	ErrMalformedHash = errors.New("password: malformed hash")
+)
diff --git a/password/go.mod b/password/go.mod
new file mode 100644
index 0000000..632736c
--- /dev/null
+++ b/password/go.mod
@@ -0,0 +1,16 @@
+module github.com/hyperscale-stack/security/password
+
+go 1.26
+
+require golang.org/x/crypto v0.51.0
+
+require (
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/stretchr/testify v1.11.1
+	golang.org/x/sys v0.44.0 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
diff --git a/password/go.sum b/password/go.sum
new file mode 100644
index 0000000..4c4fd02
--- /dev/null
+++ b/password/go.sum
@@ -0,0 +1,27 @@
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/password/hasher.go b/password/hasher.go
index 2028d7c..c2cd94a 100644
--- a/password/hasher.go
+++ b/password/hasher.go
@@ -1,11 +1,36 @@
-// Copyright 2020 Hyperscale. All rights reserved.
+// Copyright 2026 Hyperscale. All rights reserved.
 // Use of this source code is governed by a MIT
 // license that can be found in the LICENSE file.
 
 package password
 
-// Hasher interface for encoding passwords.
+import "context"
+
+// Hasher is the password-hashing primitive consumed by authentication
+// providers. Implementations encode the algorithm identifier and any tuning
+// parameters into the returned string so that Verify and NeedsRehash can
+// operate without out-of-band configuration.
+//
+// Hasher implementations MUST be safe for concurrent use.
+//
+// Two implementations are shipped: NewBCryptHasher and NewArgon2idHasher.
 type Hasher interface {
-	Hash(password string) (string, error)
-	Verify(hashed string, password string) bool
+	// Hash returns a self-describing encoded hash of password. The ctx
+	// allows cancellation of slow KDF iterations; bcrypt is bounded by its
+	// cost factor (low ms), Argon2id by its time/memory parameters (tens
+	// of ms). Hash MUST NOT log or otherwise emit the cleartext password.
+	Hash(ctx context.Context, password string) (string, error)
+
+	// Verify reports whether password matches encodedHash. A plain mismatch
+	// returns (false, nil); errors are reserved for malformed input
+	// (ErrMalformedHash), unknown algorithms (ErrUnsupportedAlgorithm), or
+	// context cancellation. Verify uses constant-time comparison on its
+	// final step to avoid timing attacks.
+	Verify(ctx context.Context, encodedHash, password string) (bool, error)
+
+	// NeedsRehash reports whether encodedHash uses parameters weaker than
+	// the hasher's current configuration. Callers SHOULD invoke it after a
+	// successful Verify so that login flows can transparently upgrade
+	// stored hashes when the operator bumps cost factors.
+	NeedsRehash(encodedHash string) bool
 }
diff --git a/principal.go b/principal.go
new file mode 100644
index 0000000..8a3cbd5
--- /dev/null
+++ b/principal.go
@@ -0,0 +1,30 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+// Principal identifies the subject of an [Authentication]. Implementations
+// represent end users, service clients, devices, or any other authenticatable
+// entity.
+//
+// The interface is intentionally minimal: any authorisation-specific data
+// (roles, scopes, claims, ...) is carried by [Authentication.Authorities]
+// or by attaching a concrete implementation via [Authentication.Attribute].
+// This keeps the core decoupled from any user store schema.
+type Principal interface {
+	// Subject returns the stable, unique identifier of the principal. It is
+	// the value that authorisation checks key off (`sub` claim, user ID,
+	// client ID, ...). Implementations MUST return the same value across
+	// calls for the lifetime of a request.
+	Subject() string
+}
+
+// AnonymousPrincipal is the singleton principal returned by the core when no
+// credentials were extracted from a [Carrier]. Authorisation voters use it to
+// distinguish "no authentication attempt" from "authentication failed".
+var AnonymousPrincipal Principal = anonymousPrincipal{}
+
+type anonymousPrincipal struct{}
+
+func (anonymousPrincipal) Subject() string { return anonymousSubject }
diff --git a/session/authentication.go b/session/authentication.go
new file mode 100644
index 0000000..e08d79e
--- /dev/null
+++ b/session/authentication.go
@@ -0,0 +1,74 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import "github.com/hyperscale-stack/security"
+
+// Authentication is the [security.Authentication] produced by the session
+// [Extractor]. Before validation it only carries the decoded [Session];
+// the [Authenticator] resolves the principal and returns a new,
+// authenticated value.
+type Authentication struct {
+	session     *Session
+	principal   security.Principal
+	authorities []string
+	authed      bool
+}
+
+// newPending wraps a freshly decoded session in an unauthenticated
+// Authentication.
+func newPending(s *Session) Authentication {
+	return Authentication{session: s}
+}
+
+// Session returns the underlying [Session]. Always non-nil for values
+// produced by this package.
+func (a Authentication) Session() *Session { return a.session }
+
+// withAuthenticated returns a new, authenticated Authentication carrying
+// the resolved principal and authorities.
+func (a Authentication) withAuthenticated(p security.Principal, authorities []string) Authentication {
+	cp := authorities
+	if authorities != nil {
+		cp = make([]string, len(authorities))
+		copy(cp, authorities)
+	}
+
+	return Authentication{
+		session:     a.session,
+		principal:   p,
+		authorities: cp,
+		authed:      true,
+	}
+}
+
+// Principal implements [security.Authentication].
+func (a Authentication) Principal() security.Principal {
+	if a.principal != nil {
+		return a.principal
+	}
+
+	return security.AnonymousPrincipal
+}
+
+// Credentials implements [security.Authentication]. A session is not a
+// bearer secret the handler should read, so this is always nil.
+func (a Authentication) Credentials() any { return nil }
+
+// Authorities implements [security.Authentication].
+func (a Authentication) Authorities() []string { return a.authorities }
+
+// IsAuthenticated implements [security.Authentication].
+func (a Authentication) IsAuthenticated() bool { return a.authed }
+
+// Name implements [security.Authentication]. Returns the principal subject
+// once authenticated, "session" beforehand.
+func (a Authentication) Name() string {
+	if a.principal != nil {
+		return a.principal.Subject()
+	}
+
+	return schemeName
+}
diff --git a/session/authentication_internal_test.go b/session/authentication_internal_test.go
new file mode 100644
index 0000000..1dede9a
--- /dev/null
+++ b/session/authentication_internal_test.go
@@ -0,0 +1,36 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+type stubPrincipal struct{ sub string }
+
+func (p stubPrincipal) Subject() string { return p.sub }
+
+func TestAuthenticationValue(t *testing.T) {
+	t.Parallel()
+
+	sess := &Session{ID: "sid", Values: map[string]any{"sub": "alice"}}
+	pending := newPending(sess)
+
+	// Pre-authentication.
+	assert.Same(t, sess, pending.Session())
+	assert.False(t, pending.IsAuthenticated())
+	assert.Nil(t, pending.Credentials(), "a session is never exposed as a credential")
+	assert.Equal(t, schemeName, pending.Name())
+	assert.Nil(t, pending.Authorities())
+
+	// Post-authentication.
+	authed := pending.withAuthenticated(stubPrincipal{sub: "alice"}, []string{"ROLE_USER"})
+	assert.True(t, authed.IsAuthenticated())
+	assert.Equal(t, "alice", authed.Name())
+	assert.Equal(t, []string{"ROLE_USER"}, authed.Authorities())
+	assert.Nil(t, authed.Credentials())
+}
diff --git a/session/authenticator.go b/session/authenticator.go
new file mode 100644
index 0000000..c461f18
--- /dev/null
+++ b/session/authenticator.go
@@ -0,0 +1,81 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// PrincipalLoader resolves the decoded session values into a live
+// [security.Principal]. Implementations live in the application layer
+// (they hit the user store); this module ships none so it stays
+// storage-agnostic.
+//
+// A typical loader reads values["sub"] and fetches the user record:
+//
+//	func (l myLoader) Load(ctx context.Context, v map[string]any) (security.Principal, []string, error) {
+//	    sub, _ := v["sub"].(string)
+//	    user, err := l.db.FindUser(ctx, sub)
+//	    ...
+//	}
+type PrincipalLoader interface {
+	// Load resolves the principal and its authorities from the session
+	// values. Returning an error fails authentication; the error SHOULD
+	// wrap security.ErrInvalidCredentials so the error mappers route it.
+	Load(ctx context.Context, values map[string]any) (security.Principal, []string, error)
+}
+
+// Authenticator implements [security.Authenticator] for the cookie-session
+// scheme. It takes the pending [Authentication] produced by the
+// [Extractor] and resolves the live principal through a [PrincipalLoader].
+type Authenticator struct {
+	loader PrincipalLoader
+}
+
+// NewAuthenticator returns an [Authenticator]. A nil loader panics at
+// construction time — a session authenticator with nothing to resolve the
+// principal would silently authenticate every cookie as anonymous.
+func NewAuthenticator(loader PrincipalLoader) *Authenticator {
+	if loader == nil {
+		panic("session: NewAuthenticator: nil PrincipalLoader")
+	}
+
+	return &Authenticator{loader: loader}
+}
+
+// AuthenticatorName implements [security.NamedAuthenticator].
+func (a *Authenticator) AuthenticatorName() string { return schemeName }
+
+// Supports reports whether auth is a session [Authentication].
+func (a *Authenticator) Supports(auth security.Authentication) bool {
+	_, ok := auth.(Authentication)
+
+	return ok
+}
+
+// Authenticate implements [security.Authenticator].
+func (a *Authenticator) Authenticate(ctx context.Context, auth security.Authentication) (security.Authentication, error) {
+	in, ok := auth.(Authentication)
+	if !ok {
+		return auth, security.ErrUnsupportedCredential
+	}
+
+	principal, authorities, err := a.loader.Load(ctx, in.session.Values)
+	if err != nil {
+		return auth, fmt.Errorf("session: load principal: %w", err)
+	}
+
+	if principal == nil {
+		return auth, fmt.Errorf("session: loader returned nil principal: %w", security.ErrInvalidCredentials)
+	}
+
+	return in.withAuthenticated(principal, authorities), nil
+}
+
+// Compile-time interface check.
+var _ security.Authenticator = (*Authenticator)(nil)
diff --git a/session/authenticator_test.go b/session/authenticator_test.go
new file mode 100644
index 0000000..c01e043
--- /dev/null
+++ b/session/authenticator_test.go
@@ -0,0 +1,130 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// stubLoader resolves the "sub" value to a principal, optionally failing.
+type stubLoader struct {
+	authorities []string
+	err         error
+	nilPrincipal bool
+}
+
+func (l stubLoader) Load(_ context.Context, values map[string]any) (security.Principal, []string, error) {
+	if l.err != nil {
+		return nil, nil, l.err
+	}
+
+	if l.nilPrincipal {
+		return nil, nil, nil
+	}
+
+	sub, _ := values["sub"].(string)
+
+	return principal{sub: sub}, l.authorities, nil
+}
+
+// engineFor wires the session extractor + authenticator into an Engine.
+func engineFor(mgr *session.Manager, loader session.PrincipalLoader) security.Engine {
+	return security.NewEngine(
+		security.NewManager(session.NewAuthenticator(loader)),
+		session.NewExtractor(mgr),
+	)
+}
+
+func TestSessionEngineEndToEnd(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	// Establish a session.
+	loginCarrier := newCarrier()
+	_, err := mgr.Login(context.Background(), loginCarrier, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	// Next request: the engine extracts + authenticates from the cookie.
+	engine := engineFor(mgr, stubLoader{authorities: []string{"ROLE_USER"}})
+
+	_, auth, err := engine.Process(context.Background(), loginCarrier.replay())
+	require.NoError(t, err)
+	assert.True(t, auth.IsAuthenticated())
+	assert.Equal(t, "alice", auth.Principal().Subject())
+	assert.Equal(t, []string{"ROLE_USER"}, auth.Authorities())
+}
+
+func TestSessionEngineNoCookieIsAnonymous(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+	engine := engineFor(mgr, stubLoader{})
+
+	_, auth, err := engine.Process(context.Background(), newCarrier())
+	require.NoError(t, err)
+	assert.False(t, auth.IsAuthenticated(), "no cookie -> anonymous")
+}
+
+func TestSessionAuthenticatorLoaderError(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+	loginCarrier := newCarrier()
+	_, err := mgr.Login(context.Background(), loginCarrier, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	boom := errors.New("user store down")
+	engine := engineFor(mgr, stubLoader{err: boom})
+
+	_, _, err = engine.Process(context.Background(), loginCarrier.replay())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, boom)
+}
+
+func TestSessionAuthenticatorNilPrincipal(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+	loginCarrier := newCarrier()
+	_, err := mgr.Login(context.Background(), loginCarrier, principal{sub: "ghost"})
+	require.NoError(t, err)
+
+	engine := engineFor(mgr, stubLoader{nilPrincipal: true})
+
+	_, _, err = engine.Process(context.Background(), loginCarrier.replay())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrInvalidCredentials)
+}
+
+func TestSessionAuthenticatorName(t *testing.T) {
+	t.Parallel()
+
+	a := session.NewAuthenticator(stubLoader{})
+	assert.Equal(t, "session", a.AuthenticatorName())
+}
+
+func TestNewAuthenticatorPanicsOnNilLoader(t *testing.T) {
+	t.Parallel()
+
+	assert.Panics(t, func() { session.NewAuthenticator(nil) })
+}
+
+func TestSessionAuthenticatorRejectsForeignAuthentication(t *testing.T) {
+	t.Parallel()
+
+	a := session.NewAuthenticator(stubLoader{})
+
+	_, err := a.Authenticate(context.Background(), security.Anonymous())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrUnsupportedCredential)
+}
diff --git a/session/codec.go b/session/codec.go
new file mode 100644
index 0000000..ada9145
--- /dev/null
+++ b/session/codec.go
@@ -0,0 +1,121 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+)
+
+// Codec encrypts and authenticates a [Session] into an opaque cookie value
+// and back. It uses AES-256-GCM: GCM is an AEAD construction, so a single
+// pass provides BOTH confidentiality and integrity — no separate HMAC is
+// needed (a tampered ciphertext fails the GCM tag check on Open).
+//
+// Codec supports key rotation. The first key is the ACTIVE key, used to
+// encrypt; every key is tried on decrypt, so an operator can prepend a new
+// key and keep decoding cookies sealed with the previous one. Each input
+// key is run through SHA-256 so keys of any length yield a valid 32-byte
+// AES-256 key.
+type Codec struct {
+	aeads []cipher.AEAD
+}
+
+// ErrInvalidKeys is returned by [NewCodec] when no key is supplied.
+var ErrInvalidKeys = errors.New("session: at least one encryption key is required")
+
+// ErrDecode is returned by [Codec.Decode] when the cookie value cannot be
+// authenticated with any configured key (tampering, expired key, garbage).
+var ErrDecode = errors.New("session: cookie could not be decoded")
+
+// NewCodec builds a [Codec] from one or more raw key bytes. keys[0] is the
+// active encryption key; the rest are decrypt-only (rotation). At least one
+// key is mandatory.
+func NewCodec(keys ...[]byte) (*Codec, error) {
+	if len(keys) == 0 {
+		return nil, ErrInvalidKeys
+	}
+
+	aeads := make([]cipher.AEAD, 0, len(keys))
+
+	for _, k := range keys {
+		derived := sha256.Sum256(k)
+
+		block, err := aes.NewCipher(derived[:])
+		if err != nil {
+			return nil, fmt.Errorf("session: build cipher: %w", err)
+		}
+
+		gcm, err := cipher.NewGCM(block)
+		if err != nil {
+			return nil, fmt.Errorf("session: build GCM: %w", err)
+		}
+
+		aeads = append(aeads, gcm)
+	}
+
+	return &Codec{aeads: aeads}, nil
+}
+
+// Encode serializes s to JSON and seals it with the active key. The output
+// is base64url(nonce || ciphertext||tag), safe for a cookie value.
+func (c *Codec) Encode(s *Session) (string, error) {
+	plaintext, err := json.Marshal(s)
+	if err != nil {
+		return "", fmt.Errorf("session: marshal: %w", err)
+	}
+
+	active := c.aeads[0]
+
+	nonce := make([]byte, active.NonceSize())
+	if _, err := rand.Read(nonce); err != nil {
+		return "", fmt.Errorf("session: read nonce: %w", err)
+	}
+
+	sealed := active.Seal(nonce, nonce, plaintext, nil)
+
+	return base64.RawURLEncoding.EncodeToString(sealed), nil
+}
+
+// Decode reverses [Codec.Encode]. It tries every configured key so that a
+// cookie sealed before a key rotation still opens. Any failure (bad
+// base64, wrong key, tampered ciphertext) collapses to [ErrDecode] — the
+// caller MUST NOT distinguish the causes (it would be a padding-oracle-
+// style information leak).
+func (c *Codec) Decode(value string) (*Session, error) {
+	raw, err := base64.RawURLEncoding.DecodeString(value)
+	if err != nil {
+		return nil, ErrDecode
+	}
+
+	for _, aead := range c.aeads {
+		ns := aead.NonceSize()
+		if len(raw) < ns {
+			continue
+		}
+
+		nonce, ciphertext := raw[:ns], raw[ns:]
+
+		plaintext, err := aead.Open(nil, nonce, ciphertext, nil)
+		if err != nil {
+			continue // wrong key or tampered — try the next key
+		}
+
+		var s Session
+		if err := json.Unmarshal(plaintext, &s); err != nil {
+			return nil, ErrDecode
+		}
+
+		return &s, nil
+	}
+
+	return nil, ErrDecode
+}
diff --git a/session/codec_test.go b/session/codec_test.go
new file mode 100644
index 0000000..3471e5b
--- /dev/null
+++ b/session/codec_test.go
@@ -0,0 +1,119 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func sampleSession() *session.Session {
+	now := time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC)
+
+	return &session.Session{
+		ID:           "sid-1",
+		Values:       map[string]any{"sub": "alice", "tenant": "acme"},
+		CSRFToken:    "csrf-token-value",
+		CreatedAt:    now,
+		LastAccessed: now,
+		ExpiresAt:    now.Add(time.Hour),
+	}
+}
+
+func TestCodecRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	codec, err := session.NewCodec(testKey)
+	require.NoError(t, err)
+
+	encoded, err := codec.Encode(sampleSession())
+	require.NoError(t, err)
+	assert.NotEmpty(t, encoded)
+
+	got, err := codec.Decode(encoded)
+	require.NoError(t, err)
+	assert.Equal(t, "sid-1", got.ID)
+	assert.Equal(t, "alice", got.GetString("sub"))
+	assert.Equal(t, "csrf-token-value", got.CSRFToken)
+}
+
+func TestCodecEncodeIsRandomised(t *testing.T) {
+	t.Parallel()
+
+	codec, _ := session.NewCodec(testKey)
+
+	a, _ := codec.Encode(sampleSession())
+	b, _ := codec.Encode(sampleSession())
+	assert.NotEqual(t, a, b, "a fresh GCM nonce per call must change the ciphertext")
+}
+
+func TestCodecRejectsTamperedValue(t *testing.T) {
+	t.Parallel()
+
+	codec, _ := session.NewCodec(testKey)
+	encoded, _ := codec.Encode(sampleSession())
+
+	// Flip the last byte — the GCM tag check must fail.
+	tampered := encoded[:len(encoded)-1] + flipChar(encoded[len(encoded)-1])
+
+	_, err := codec.Decode(tampered)
+	assert.ErrorIs(t, err, session.ErrDecode)
+}
+
+func TestCodecRejectsGarbage(t *testing.T) {
+	t.Parallel()
+
+	codec, _ := session.NewCodec(testKey)
+
+	for _, bad := range []string{"", "!!!not base64!!!", "c2hvcnQ"} {
+		_, err := codec.Decode(bad)
+		assert.ErrorIs(t, err, session.ErrDecode, "input %q", bad)
+	}
+}
+
+func TestCodecKeyRotation(t *testing.T) {
+	t.Parallel()
+
+	oldKey := []byte("old-key-old-key-old-key-old-key!")
+	newKey := []byte("new-key-new-key-new-key-new-key!")
+
+	// A cookie sealed by the old codec...
+	oldCodec, _ := session.NewCodec(oldKey)
+	sealed, err := oldCodec.Encode(sampleSession())
+	require.NoError(t, err)
+
+	// ...still decodes after rotation when the old key is kept as a
+	// decrypt-only key (new key first = active for encryption).
+	rotated, err := session.NewCodec(newKey, oldKey)
+	require.NoError(t, err)
+
+	got, err := rotated.Decode(sealed)
+	require.NoError(t, err)
+	assert.Equal(t, "sid-1", got.ID)
+
+	// A codec that dropped the old key can no longer read the cookie.
+	newOnly, _ := session.NewCodec(newKey)
+	_, err = newOnly.Decode(sealed)
+	assert.ErrorIs(t, err, session.ErrDecode)
+}
+
+func TestNewCodecRequiresAKey(t *testing.T) {
+	t.Parallel()
+
+	_, err := session.NewCodec()
+	assert.ErrorIs(t, err, session.ErrInvalidKeys)
+}
+
+func flipChar(b byte) string {
+	if b == 'A' {
+		return "B"
+	}
+
+	return "A"
+}
diff --git a/session/csrf.go b/session/csrf.go
new file mode 100644
index 0000000..60411f2
--- /dev/null
+++ b/session/csrf.go
@@ -0,0 +1,38 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import "crypto/subtle"
+
+// CSRFToken returns the per-session CSRF token. The application embeds it
+// into rendered forms (a hidden field) or a <meta> tag so the browser can
+// echo it back on state-changing requests. The token lives inside the
+// encrypted, HttpOnly session cookie, so it is never directly readable by
+// page JavaScript — only the server, which decrypts the cookie, knows it.
+func CSRFToken(s *Session) string {
+	if s == nil {
+		return ""
+	}
+
+	return s.CSRFToken
+}
+
+// VerifyCSRF reports whether presented matches the session's CSRF token.
+// The comparison is constant-time to avoid leaking the token through
+// response-timing analysis.
+//
+// This is the synchronizer-token pattern: the server holds the canonical
+// token in the (encrypted) session and checks the value the client echoed
+// back in, e.g., the "X-CSRF-Token" header or a form field. Unlike the
+// plain double-submit-cookie pattern it does not rely on a second,
+// JavaScript-readable cookie, so it is robust even against subdomain
+// cookie-injection.
+func VerifyCSRF(s *Session, presented string) bool {
+	if s == nil || s.CSRFToken == "" || presented == "" {
+		return false
+	}
+
+	return subtle.ConstantTimeCompare([]byte(s.CSRFToken), []byte(presented)) == 1
+}
diff --git a/session/csrf_test.go b/session/csrf_test.go
new file mode 100644
index 0000000..8825b2b
--- /dev/null
+++ b/session/csrf_test.go
@@ -0,0 +1,70 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCSRFTokenAndVerify(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	s, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	token := session.CSRFToken(s)
+	assert.NotEmpty(t, token, "Login must mint a CSRF token")
+
+	assert.True(t, session.VerifyCSRF(s, token), "the minted token must verify")
+	assert.False(t, session.VerifyCSRF(s, "wrong-token"), "a wrong token must be rejected")
+	assert.False(t, session.VerifyCSRF(s, ""), "an empty presented token must be rejected")
+}
+
+func TestCSRFNilSessionSafe(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "", session.CSRFToken(nil))
+	assert.False(t, session.VerifyCSRF(nil, "anything"))
+}
+
+func TestCSRFTokenSurvivesCookieRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	original, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	reloaded, err := mgr.Get(context.Background(), c.replay())
+	require.NoError(t, err)
+
+	assert.Equal(t, session.CSRFToken(original), session.CSRFToken(reloaded),
+		"the CSRF token must survive the cookie encrypt/decrypt round-trip")
+}
+
+func TestCSRFTokenChangesOnRotate(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	original, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	rotated, err := mgr.Rotate(context.Background(), c.replay())
+	require.NoError(t, err)
+
+	assert.NotEqual(t, session.CSRFToken(original), session.CSRFToken(rotated),
+		"Rotate mints a fresh session, hence a fresh CSRF token")
+}
diff --git a/session/doc.go b/session/doc.go
new file mode 100644
index 0000000..2d94546
--- /dev/null
+++ b/session/doc.go
@@ -0,0 +1,17 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package session provides cookie-based session management for browser apps:
+// signed/encrypted cookie store, session ID rotation after login (defense
+// against session fixation), logout, CSRF helper.
+//
+// Defaults are secure: Secure=true, HttpOnly=true, SameSite=Lax. The cookie
+// store uses AES-GCM with HMAC and supports key rotation (multi-key reader,
+// single active writer).
+//
+// Allowed dependencies:
+//   - github.com/hyperscale-stack/security (core)
+//   - golang.org/x/crypto
+//   - stdlib only
+package session
diff --git a/session/example_test.go b/session/example_test.go
new file mode 100644
index 0000000..b32726f
--- /dev/null
+++ b/session/example_test.go
@@ -0,0 +1,59 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security/session"
+)
+
+// Example demonstrates the cookie-session life cycle: Login writes an
+// encrypted cookie, Get replays it, Rotate changes the ID after a
+// privilege change, and Logout clears it.
+func Example() {
+	codec, err := session.NewCodec([]byte("a-32-byte-or-longer-secret-key!!"))
+	if err != nil {
+		panic(err)
+	}
+
+	mgr := session.NewManager(codec,
+		session.WithSecure(false), // demo runs over plain HTTP
+	)
+
+	// --- login -----------------------------------------------------------
+	login := newCarrier()
+
+	s, err := mgr.Login(context.Background(), login, principal{sub: "alice"})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("logged in:", s.GetString("sub"))
+
+	// --- subsequent request reads the cookie -----------------------------
+	got, err := mgr.Get(context.Background(), login.replay())
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("session sub:", got.GetString("sub"))
+	fmt.Println("csrf present:", session.CSRFToken(got) != "")
+
+	// --- rotate after a privilege change ---------------------------------
+	rotated, err := mgr.Rotate(context.Background(), login.replay())
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("id changed on rotate:", rotated.ID != s.ID)
+
+	// Output:
+	// logged in: alice
+	// session sub: alice
+	// csrf present: true
+	// id changed on rotate: true
+}
diff --git a/session/extractor.go b/session/extractor.go
new file mode 100644
index 0000000..1c63f51
--- /dev/null
+++ b/session/extractor.go
@@ -0,0 +1,36 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Extractor implements [security.Extractor] for the cookie-session scheme.
+// It reads the session cookie via the [Manager], decodes it, and returns a
+// pending [Authentication]. Validation (expiry, principal resolution) is
+// the [Authenticator]'s job.
+type Extractor struct {
+	mgr *Manager
+}
+
+// NewExtractor returns an [Extractor] bound to mgr.
+func NewExtractor(mgr *Manager) Extractor { return Extractor{mgr: mgr} }
+
+// Extract implements [security.Extractor]. Returns (nil, nil) when the
+// request carries no decodable session cookie, so the engine moves on to
+// the next extractor / anonymous flow.
+func (e Extractor) Extract(ctx context.Context, c security.Carrier) (security.Authentication, error) {
+	s, err := e.mgr.Get(ctx, c)
+	if err != nil {
+		// ErrNoSession and expiry both mean "no usable session here" —
+		// the engine treats a nil result as "extractor did not apply".
+		return nil, nil //nolint:nilerr // absent/expired session is not an extraction error
+	}
+
+	return newPending(s), nil
+}
diff --git a/session/go.mod b/session/go.mod
new file mode 100644
index 0000000..a0f95d7
--- /dev/null
+++ b/session/go.mod
@@ -0,0 +1,23 @@
+module github.com/hyperscale-stack/security/session
+
+go 1.26
+
+require (
+	github.com/hyperscale-stack/security v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.11.1
+	go.opentelemetry.io/otel v1.43.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/hyperscale-stack/security => ../
diff --git a/session/go.sum b/session/go.sum
new file mode 100644
index 0000000..56bdaa2
--- /dev/null
+++ b/session/go.sum
@@ -0,0 +1,40 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/session/manager.go b/session/manager.go
new file mode 100644
index 0000000..2458279
--- /dev/null
+++ b/session/manager.go
@@ -0,0 +1,280 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+const tracerName = "github.com/hyperscale-stack/security/session"
+
+// ErrNoSession is returned by [Manager.Get] when the request carries no
+// session cookie (or one that fails to decode).
+var ErrNoSession = errors.New("session: no session on request")
+
+// Manager owns the session lifecycle on top of a cookie. It reads and
+// writes the cookie through a [security.Carrier], so it works behind the
+// HTTP adapter (httpsec) without importing it.
+//
+// Cookie security defaults are conservative: Secure, HttpOnly, SameSite=Lax.
+type Manager struct {
+	codec       *Codec
+	cookieName  string
+	path        string
+	domain      string
+	secure      bool
+	httpOnly    bool
+	sameSite    http.SameSite
+	ttl         time.Duration
+	idleTimeout time.Duration
+	clock       func() time.Time
+}
+
+// Option configures a [Manager].
+type Option func(*Manager)
+
+// WithCookieName overrides the cookie name. Default: "session".
+func WithCookieName(name string) Option {
+	return func(m *Manager) { m.cookieName = name }
+}
+
+// WithPath overrides the cookie Path attribute. Default: "/".
+func WithPath(path string) Option {
+	return func(m *Manager) { m.path = path }
+}
+
+// WithDomain sets the cookie Domain attribute. Default: empty (host-only).
+func WithDomain(domain string) Option {
+	return func(m *Manager) { m.domain = domain }
+}
+
+// WithSecure overrides the Secure attribute. Default: true. Disable it ONLY
+// for local plain-HTTP development.
+func WithSecure(secure bool) Option {
+	return func(m *Manager) { m.secure = secure }
+}
+
+// WithSameSite overrides the SameSite attribute. Default: http.SameSiteLaxMode.
+func WithSameSite(mode http.SameSite) Option {
+	return func(m *Manager) { m.sameSite = mode }
+}
+
+// WithTTL overrides the absolute session lifetime. Default: 24h.
+func WithTTL(ttl time.Duration) Option {
+	return func(m *Manager) { m.ttl = ttl }
+}
+
+// WithIdleTimeout enables an idle-timeout: a session untouched for longer
+// than d is treated as expired. Default: 0 (disabled).
+func WithIdleTimeout(d time.Duration) Option {
+	return func(m *Manager) { m.idleTimeout = d }
+}
+
+// WithClock injects a clock for deterministic tests. Default: time.Now.
+func WithClock(now func() time.Time) Option {
+	return func(m *Manager) {
+		if now != nil {
+			m.clock = now
+		}
+	}
+}
+
+// NewManager builds a [Manager] sealing sessions with codec.
+func NewManager(codec *Codec, opts ...Option) *Manager {
+	m := &Manager{
+		codec:      codec,
+		cookieName: schemeName,
+		path:       "/",
+		secure:     true,
+		httpOnly:   true,
+		sameSite:   http.SameSiteLaxMode,
+		ttl:        24 * time.Hour,
+		clock:      time.Now,
+	}
+
+	for _, o := range opts {
+		o(m)
+	}
+
+	return m
+}
+
+// Login mints a fresh authenticated session for principal, stores its
+// subject under the "sub" value, and writes the session cookie via the
+// carrier. Any prior session is replaced (a fresh ID defeats fixation).
+func (m *Manager) Login(ctx context.Context, c security.Carrier, principal security.Principal) (*Session, error) {
+	_, span := otel.Tracer(tracerName).Start(ctx, "session.Manager.Login")
+	defer span.End()
+
+	now := m.clock()
+
+	s, err := newSession(now, m.ttl)
+	if err != nil {
+		return nil, fmt.Errorf("session: mint: %w", err)
+	}
+
+	if principal != nil {
+		s.Values["sub"] = principal.Subject()
+	}
+
+	if err := m.writeCookie(c, s); err != nil {
+		return nil, err
+	}
+
+	span.SetAttributes(attribute.String("session.id_hash", hashID(s.ID)))
+
+	return s, nil
+}
+
+// Get decodes and validates the session carried by the request. It returns
+// [ErrNoSession] when the cookie is absent / undecodable and a wrapped
+// expiry error when the session is past its absolute or idle deadline.
+// On success it refreshes LastAccessed but does NOT rewrite the cookie —
+// call [Manager.Touch] when sliding expiry is desired.
+func (m *Manager) Get(ctx context.Context, c security.Carrier) (*Session, error) {
+	_, span := otel.Tracer(tracerName).Start(ctx, "session.Manager.Get")
+	defer span.End()
+
+	raw := c.Get(m.cookieName)
+	if raw == "" {
+		return nil, ErrNoSession
+	}
+
+	s, err := m.codec.Decode(raw)
+	if err != nil {
+		return nil, ErrNoSession
+	}
+
+	now := m.clock()
+	if s.IsExpired(now) || s.IdleExpired(now, m.idleTimeout) {
+		return nil, fmt.Errorf("session: %w", security.ErrTokenExpired)
+	}
+
+	s.LastAccessed = now
+	span.SetAttributes(attribute.String("session.id_hash", hashID(s.ID)))
+
+	return s, nil
+}
+
+// Touch re-writes the cookie with a refreshed LastAccessed, implementing
+// sliding-window idle expiry. Call it after a successful Get when the
+// idle-timeout should reset on activity.
+func (m *Manager) Touch(ctx context.Context, c security.Carrier, s *Session) error {
+	_, span := otel.Tracer(tracerName).Start(ctx, "session.Manager.Touch")
+	defer span.End()
+
+	s.LastAccessed = m.clock()
+
+	return m.writeCookie(c, s)
+}
+
+// Rotate issues a new session ID for the current session while preserving
+// its Values — the canonical defense against session fixation, to be
+// called right after a privilege change (login, step-up auth).
+func (m *Manager) Rotate(ctx context.Context, c security.Carrier) (*Session, error) {
+	_, span := otel.Tracer(tracerName).Start(ctx, "session.Manager.Rotate")
+	defer span.End()
+
+	current, err := m.Get(ctx, c)
+	if err != nil {
+		return nil, err
+	}
+
+	rotated, err := newSession(m.clock(), m.ttl)
+	if err != nil {
+		return nil, fmt.Errorf("session: mint: %w", err)
+	}
+
+	rotated.Values = current.Values
+	rotated.CreatedAt = current.CreatedAt
+
+	if err := m.writeCookie(c, rotated); err != nil {
+		return nil, err
+	}
+
+	span.SetAttributes(
+		attribute.String("session.old_id_hash", hashID(current.ID)),
+		attribute.String("session.new_id_hash", hashID(rotated.ID)),
+	)
+
+	return rotated, nil
+}
+
+// Logout clears the session cookie by writing an immediately-expired one.
+func (m *Manager) Logout(ctx context.Context, c security.Carrier) {
+	_, span := otel.Tracer(tracerName).Start(ctx, "session.Manager.Logout")
+	defer span.End()
+
+	//nolint:gosec // G124: Secure/HttpOnly/SameSite come from the Manager config (secure-by-default: Secure, HttpOnly, SameSiteLax)
+	expired := &http.Cookie{
+		Name:     m.cookieName,
+		Value:    "",
+		Path:     m.path,
+		Domain:   m.domain,
+		Secure:   m.secure,
+		HttpOnly: m.httpOnly,
+		SameSite: m.sameSite,
+		MaxAge:   -1, // tell the browser to delete it now
+	}
+
+	c.Add("Set-Cookie", expired.String())
+}
+
+// CookieName returns the configured cookie name (handy for extractors and
+// tests).
+func (m *Manager) CookieName() string { return m.cookieName }
+
+// writeCookie encodes s and stages a Set-Cookie header on the carrier.
+func (m *Manager) writeCookie(c security.Carrier, s *Session) error {
+	value, err := m.codec.Encode(s)
+	if err != nil {
+		return fmt.Errorf("session: encode: %w", err)
+	}
+
+	// MaxAge is derived from the injected clock, not time.Now, so tests
+	// driving a fixed clock observe a coherent cookie lifetime. It is
+	// floored at 1s — a zero/negative MaxAge would tell the browser to
+	// delete the cookie, which is Logout's job, not Login's.
+	maxAge := int(s.ExpiresAt.Sub(m.clock()).Seconds())
+	if maxAge < 1 {
+		maxAge = 1
+	}
+
+	//nolint:gosec // G124: Secure/HttpOnly/SameSite come from the Manager config (secure-by-default: Secure, HttpOnly, SameSiteLax)
+	cookie := &http.Cookie{
+		Name:     m.cookieName,
+		Value:    value,
+		Path:     m.path,
+		Domain:   m.domain,
+		Secure:   m.secure,
+		HttpOnly: m.httpOnly,
+		SameSite: m.sameSite,
+		Expires:  s.ExpiresAt,
+		MaxAge:   maxAge,
+	}
+
+	c.Add("Set-Cookie", cookie.String())
+
+	return nil
+}
+
+// hashID returns a short, non-reversible fingerprint of a session ID for
+// OTel attributes — the raw ID is a credential and must never hit a trace
+// backend.
+func hashID(id string) string {
+	sum := sha256.Sum256([]byte(id))
+
+	return hex.EncodeToString(sum[:8])
+}
diff --git a/session/manager_more_test.go b/session/manager_more_test.go
new file mode 100644
index 0000000..07aa024
--- /dev/null
+++ b/session/manager_more_test.go
@@ -0,0 +1,46 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestManagerCookieOptions(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t,
+		session.WithCookieName("sid"),
+		session.WithPath("/app"),
+		session.WithDomain("example.com"),
+	)
+
+	assert.Equal(t, "sid", mgr.CookieName())
+}
+
+func TestManagerTouchRewritesCookie(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+	ctx := context.Background()
+	c := newCarrier()
+
+	sess, err := mgr.Login(ctx, c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	// Replay the login cookie onto the next request, then Touch slides the
+	// idle window by re-writing it.
+	next := c.replay()
+	require.NoError(t, mgr.Touch(ctx, next, sess))
+
+	reloaded, err := mgr.Get(ctx, next.replay())
+	require.NoError(t, err)
+	assert.Equal(t, sess.ID, reloaded.ID)
+}
diff --git a/session/manager_test.go b/session/manager_test.go
new file mode 100644
index 0000000..1c8bd02
--- /dev/null
+++ b/session/manager_test.go
@@ -0,0 +1,213 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// principal is a tiny security.Principal for the Login tests.
+type principal struct{ sub string }
+
+func (p principal) Subject() string { return p.sub }
+
+func newManager(t *testing.T, opts ...session.Option) *session.Manager {
+	t.Helper()
+
+	codec, err := session.NewCodec(testKey)
+	require.NoError(t, err)
+
+	return session.NewManager(codec, opts...)
+}
+
+func TestManagerLoginGetRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	s, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+	assert.Equal(t, "alice", s.GetString("sub"))
+
+	// Replay the cookie on the next request.
+	got, err := mgr.Get(context.Background(), c.replay())
+	require.NoError(t, err)
+	assert.Equal(t, "alice", got.GetString("sub"))
+	assert.Equal(t, s.ID, got.ID)
+}
+
+func TestManagerCookieSecurityAttributes(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	assert.True(t, c.hasAttr("HttpOnly"), "cookie must be HttpOnly")
+	assert.True(t, c.hasAttr("Secure"), "cookie must be Secure by default")
+	assert.True(t, c.hasAttr("SameSite=Lax"), "cookie must default to SameSite=Lax")
+}
+
+func TestManagerGetWithoutCookie(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	_, err := mgr.Get(context.Background(), newCarrier())
+	assert.ErrorIs(t, err, session.ErrNoSession)
+}
+
+func TestManagerLogoutClearsCookie(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	// New carrier carrying the live cookie; Logout writes a deletion cookie.
+	live := c.replay()
+	mgr.Logout(context.Background(), live)
+
+	// The deletion cookie has Max-Age<0, so replay() drops it: the next
+	// request has no session.
+	_, err = mgr.Get(context.Background(), live.replay())
+	assert.ErrorIs(t, err, session.ErrNoSession)
+}
+
+func TestManagerRotateChangesIDKeepsValues(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	original, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	rotated, err := mgr.Rotate(context.Background(), c.replay())
+	require.NoError(t, err)
+
+	assert.NotEqual(t, original.ID, rotated.ID, "Rotate must mint a new session ID (anti-fixation)")
+	assert.Equal(t, "alice", rotated.GetString("sub"), "Rotate must preserve session values")
+	// CreatedAt round-trips through JSON, which drops the monotonic clock —
+	// compare instants with time.Time.Equal, not assert.Equal.
+	assert.True(t, original.CreatedAt.Equal(rotated.CreatedAt), "Rotate keeps the original creation time")
+}
+
+func TestManagerExpiredSessionRejected(t *testing.T) {
+	t.Parallel()
+
+	// Clock starts at T; the session lives 1h. We Login at T then Get at
+	// T+2h with the same fixed clock advanced.
+	base := time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC)
+	now := base
+
+	mgr := newManager(t,
+		session.WithTTL(time.Hour),
+		session.WithClock(func() time.Time { return now }),
+	)
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	now = base.Add(2 * time.Hour) // past the 1h TTL
+
+	_, err = mgr.Get(context.Background(), c.replay())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrTokenExpired)
+}
+
+func TestManagerIdleTimeout(t *testing.T) {
+	t.Parallel()
+
+	base := time.Date(2026, 5, 20, 12, 0, 0, 0, time.UTC)
+	now := base
+
+	mgr := newManager(t,
+		session.WithTTL(24*time.Hour),
+		session.WithIdleTimeout(15*time.Minute),
+		session.WithClock(func() time.Time { return now }),
+	)
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	now = base.Add(20 * time.Minute) // idle past the 15m window
+
+	_, err = mgr.Get(context.Background(), c.replay())
+	require.Error(t, err)
+	assert.ErrorIs(t, err, security.ErrTokenExpired)
+}
+
+func TestManagerTamperedCookieRejected(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	// Corrupt the stored cookie value.
+	replayed := c.replay()
+	for name := range replayed.cookies {
+		replayed.cookies[name] += "x"
+	}
+
+	_, err = mgr.Get(context.Background(), replayed)
+	assert.ErrorIs(t, err, session.ErrNoSession, "a tampered cookie must not decode")
+}
+
+func TestManagerWithSecureFalseForDevelopment(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t, session.WithSecure(false), session.WithSameSite(http.SameSiteStrictMode))
+
+	c := newCarrier()
+	_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+	require.NoError(t, err)
+
+	assert.False(t, c.hasAttr("Secure"))
+	assert.True(t, c.hasAttr("SameSite=Strict"))
+}
+
+func TestManagerIsRaceSafe(t *testing.T) {
+	t.Parallel()
+
+	mgr := newManager(t)
+
+	var wg sync.WaitGroup
+	for range 50 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			c := newCarrier()
+			_, err := mgr.Login(context.Background(), c, principal{sub: "alice"})
+			assert.NoError(t, err)
+
+			_, err = mgr.Get(context.Background(), c.replay())
+			assert.NoError(t, err)
+		}()
+	}
+
+	wg.Wait()
+}
diff --git a/session/session.go b/session/session.go
new file mode 100644
index 0000000..6c8c1ee
--- /dev/null
+++ b/session/session.go
@@ -0,0 +1,98 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"time"
+)
+
+// schemeName is the canonical label of this authentication scheme: the
+// default cookie name, the [Authenticator]'s name, and the fallback
+// [Authentication.Name] before a principal is resolved.
+const schemeName = "session"
+
+// Session is the unit of state carried across requests of the same browser
+// client. With the cookie-backed [Manager] the whole struct is encrypted
+// into the cookie value — there is no server-side storage to look up.
+type Session struct {
+	// ID is a random, unguessable session identifier. It is rotated on
+	// privilege changes (see [Manager.Rotate]) to defeat session fixation.
+	ID string
+	// Values holds application data (user id, tenant, feature flags…).
+	// Keep it small: the whole map is JSON-encoded into the cookie, and
+	// browsers cap a cookie at ~4 KiB.
+	Values map[string]any
+	// CSRFToken is a random token minted with the session. It is never
+	// exposed to JavaScript (the cookie is HttpOnly); the application
+	// echoes it into forms / a meta tag and the csrf helpers verify it.
+	CSRFToken string
+	// CreatedAt is the session creation time.
+	CreatedAt time.Time
+	// LastAccessed is refreshed on every successful load; idle-timeout
+	// enforcement keys off it.
+	LastAccessed time.Time
+	// ExpiresAt is the absolute expiry time.
+	ExpiresAt time.Time
+}
+
+// newSession mints a fresh Session with random ID + CSRF token and the
+// supplied lifetimes.
+func newSession(now time.Time, ttl time.Duration) (*Session, error) {
+	id, err := randomToken(18) // 144 bits
+	if err != nil {
+		return nil, err
+	}
+
+	csrf, err := randomToken(32) // 256 bits
+	if err != nil {
+		return nil, err
+	}
+
+	return &Session{
+		ID:           id,
+		Values:       map[string]any{},
+		CSRFToken:    csrf,
+		CreatedAt:    now,
+		LastAccessed: now,
+		ExpiresAt:    now.Add(ttl),
+	}, nil
+}
+
+// IsExpired reports whether the session has passed its absolute expiry.
+func (s *Session) IsExpired(now time.Time) bool {
+	return now.After(s.ExpiresAt)
+}
+
+// IdleExpired reports whether more than idle has elapsed since the session
+// was last accessed. A zero idle disables the idle-timeout check.
+func (s *Session) IdleExpired(now time.Time, idle time.Duration) bool {
+	if idle <= 0 {
+		return false
+	}
+
+	return now.After(s.LastAccessed.Add(idle))
+}
+
+// GetString returns the string value stored under key, or "" when absent or
+// not a string. The cookie round-trips through JSON, so values written as
+// strings come back as strings.
+func (s *Session) GetString(key string) string {
+	v, _ := s.Values[key].(string)
+
+	return v
+}
+
+// randomToken returns n cryptographically-random bytes, base64url-encoded
+// without padding.
+func randomToken(n int) (string, error) {
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		return "", err //nolint:wrapcheck // caller wraps with package context
+	}
+
+	return base64.RawURLEncoding.EncodeToString(b), nil
+}
diff --git a/session/testing_helpers_test.go b/session/testing_helpers_test.go
new file mode 100644
index 0000000..21c51e2
--- /dev/null
+++ b/session/testing_helpers_test.go
@@ -0,0 +1,89 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package session_test
+
+import (
+	"net/http"
+	"strings"
+)
+
+// mapCarrier is a minimal security.Carrier for the session tests. It models
+// a browser cookie jar: cookies set via Add("Set-Cookie", …) on one
+// "response" are parsed and replayed as readable cookie values on the next
+// "request" via replay().
+type mapCarrier struct {
+	// cookies are the request-side cookies the Manager reads via Get(name).
+	cookies map[string]string
+	// setCookies are the Set-Cookie headers the Manager staged via Add.
+	setCookies []string
+}
+
+func newCarrier() *mapCarrier {
+	return &mapCarrier{cookies: map[string]string{}}
+}
+
+func (c *mapCarrier) Get(key string) string {
+	// The session Manager only ever reads cookies by name.
+	return c.cookies[key]
+}
+
+func (c *mapCarrier) Values(key string) []string {
+	if v, ok := c.cookies[key]; ok {
+		return []string{v}
+	}
+
+	return nil
+}
+
+func (c *mapCarrier) Set(key, value string) {
+	if key == "Set-Cookie" {
+		c.setCookies = []string{value}
+
+		return
+	}
+}
+
+func (c *mapCarrier) Add(key, value string) {
+	if key == "Set-Cookie" {
+		c.setCookies = append(c.setCookies, value)
+	}
+}
+
+// replay parses the Set-Cookie headers staged on c and returns a fresh
+// carrier whose request-side cookies carry them — the next request of the
+// same browser. Deleted cookies (Max-Age<0) are dropped.
+func (c *mapCarrier) replay() *mapCarrier {
+	next := newCarrier()
+
+	resp := http.Response{Header: http.Header{"Set-Cookie": c.setCookies}}
+	for _, ck := range resp.Cookies() {
+		if ck.MaxAge < 0 {
+			continue // logout / expired cookie
+		}
+
+		next.cookies[ck.Name] = ck.Value
+	}
+
+	return next
+}
+
+// lastSetCookie returns the most recent Set-Cookie header value (for
+// attribute assertions: Secure, HttpOnly, SameSite, Max-Age).
+func (c *mapCarrier) lastSetCookie() string {
+	if len(c.setCookies) == 0 {
+		return ""
+	}
+
+	return c.setCookies[len(c.setCookies)-1]
+}
+
+// hasAttr reports whether the last Set-Cookie header carries attr
+// (case-insensitive substring match — fine for the fixed attribute names).
+func (c *mapCarrier) hasAttr(attr string) bool {
+	return strings.Contains(strings.ToLower(c.lastSetCookie()), strings.ToLower(attr))
+}
+
+// testKey is a fixed 32-byte codec key used across the suite.
+var testKey = []byte("0123456789abcdef0123456789abcdef")
diff --git a/testing_helpers_test.go b/testing_helpers_test.go
new file mode 100644
index 0000000..1c3f70c
--- /dev/null
+++ b/testing_helpers_test.go
@@ -0,0 +1,181 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security_test
+
+import (
+	"context"
+	"net/textproto"
+	"strings"
+	"sync/atomic"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// fakePrincipal is a minimal Principal used across core tests.
+type fakePrincipal struct{ subject string }
+
+func (p fakePrincipal) Subject() string { return p.subject }
+
+// fakeAuthentication is a minimal, immutable Authentication used by tests.
+// Each "mutation" returns a new value.
+type fakeAuthentication struct {
+	principal     security.Principal
+	credentials   any
+	authorities   []string
+	authenticated bool
+	name          string
+}
+
+func newFakeAuth(subject string, authorities ...string) fakeAuthentication {
+	return fakeAuthentication{
+		principal:   fakePrincipal{subject: subject},
+		authorities: authorities,
+		name:        subject,
+	}
+}
+
+func (a fakeAuthentication) Principal() Principal { //nolint:revive,unused-receiver
+	return a.principal
+}
+
+// Reproduce Authentication interface using the exported alias below so test
+// helpers do not need to import the package on every line.
+
+type (
+	// Principal/Authentication aliases keep the test file readable.
+	Principal      = security.Principal
+	Authentication = security.Authentication
+)
+
+func (a fakeAuthentication) Credentials() any     { return a.credentials }
+func (a fakeAuthentication) Authorities() []string { return a.authorities }
+func (a fakeAuthentication) IsAuthenticated() bool { return a.authenticated }
+func (a fakeAuthentication) Name() string          { return a.name }
+
+func (a fakeAuthentication) withAuthenticated() fakeAuthentication {
+	a.authenticated = true
+
+	return a
+}
+
+func (a fakeAuthentication) withCredentials(c any) fakeAuthentication {
+	a.credentials = c
+
+	return a
+}
+
+// mapCarrier is a hash-backed [Carrier] used by tests. Keys are normalised
+// using textproto.CanonicalMIMEHeaderKey to mirror HTTP semantics.
+type mapCarrier struct {
+	values map[string][]string
+}
+
+func newMapCarrier() *mapCarrier {
+	return &mapCarrier{values: make(map[string][]string)}
+}
+
+func (c *mapCarrier) key(k string) string { return textproto.CanonicalMIMEHeaderKey(k) }
+
+func (c *mapCarrier) Get(k string) string {
+	vs := c.values[c.key(k)]
+	if len(vs) == 0 {
+		return ""
+	}
+
+	return vs[0]
+}
+
+func (c *mapCarrier) Values(k string) []string {
+	vs := c.values[c.key(k)]
+	if vs == nil {
+		return nil
+	}
+
+	out := make([]string, len(vs))
+	copy(out, vs)
+
+	return out
+}
+
+func (c *mapCarrier) Set(k, v string) { c.values[c.key(k)] = []string{v} }
+func (c *mapCarrier) Add(k, v string) {
+	ck := c.key(k)
+	c.values[ck] = append(c.values[ck], v)
+}
+
+// scriptedExtractor returns a pre-recorded (auth, err) tuple on every call,
+// useful for asserting Engine wiring.
+type scriptedExtractor struct {
+	auth Authentication
+	err  error
+}
+
+func (s scriptedExtractor) Extract(_ context.Context, _ security.Carrier) (Authentication, error) {
+	return s.auth, s.err
+}
+
+// countingExtractor records how many times Extract was called and proxies to
+// an underlying scripted result.
+type countingExtractor struct {
+	scripted scriptedExtractor
+	calls    int
+}
+
+func (c *countingExtractor) Extract(ctx context.Context, car security.Carrier) (Authentication, error) {
+	c.calls++
+
+	return c.scripted.Extract(ctx, car)
+}
+
+// scriptedAuthenticator validates by returning the configured result. It
+// supports filtering via the supports closure. Race-safe via atomic counter.
+type scriptedAuthenticator struct {
+	name     string
+	supports func(Authentication) bool
+	result   Authentication
+	err      error
+	callsN   atomic.Int32
+}
+
+func (s *scriptedAuthenticator) AuthenticatorName() string { return s.name }
+
+func (s *scriptedAuthenticator) Supports(a Authentication) bool {
+	if s.supports == nil {
+		return true
+	}
+
+	return s.supports(a)
+}
+
+func (s *scriptedAuthenticator) Authenticate(_ context.Context, _ Authentication) (Authentication, error) {
+	s.callsN.Add(1)
+
+	return s.result, s.err
+}
+
+func (s *scriptedAuthenticator) calls() int { return int(s.callsN.Load()) }
+
+// scriptedVoter returns a fixed verdict; Supports matches when the attribute
+// has the given prefix (e.g. "scope:read").
+type scriptedVoter struct {
+	prefix string
+	vote   security.Decision
+	calls  int
+}
+
+func (s *scriptedVoter) Supports(a security.Attribute) bool {
+	return strings.HasPrefix(a.String(), s.prefix)
+}
+
+func (s *scriptedVoter) Vote(_ context.Context, _ Authentication, _ []security.Attribute) security.Decision {
+	s.calls++
+
+	return s.vote
+}
+
+// stringAttr is the smallest possible Attribute implementation.
+type stringAttr string
+
+func (s stringAttr) String() string { return string(s) }
diff --git a/user/user.go b/user/user.go
deleted file mode 100644
index e5504b7..0000000
--- a/user/user.go
+++ /dev/null
@@ -1,41 +0,0 @@
-// Copyright 2020 Hyperscale. All rights reserved.
-// Use of this source code is governed by a MIT
-// license that can be found in the LICENSE file.
-
-package user
-
-// User interface provides core user information.
-type User interface {
-	// GetRoles returns the roles granted to the user.
-	GetRoles() []string
-
-	// GetPassword returns the password used to authenticate the user
-	GetPassword() string
-
-	// GetUsername returns the username used to authenticate the user
-	GetUsername() string
-
-	// IsExpired indicates whether the user's account has expired.
-	IsExpired() bool
-
-	// IsLocked indicates whether the user is locked or unlocked.
-	IsLocked() bool
-
-	// IsEnabled indicates whether the user is enabled or disabled.
-	IsEnabled() bool
-
-	// IsCredentialsExpired indicates whether the user's credentials (password) has expired.
-	IsCredentialsExpired() bool
-}
-
-// PasswordSalt interface.
-type PasswordSalt interface {
-	GetSalt() string
-	SaltPassword(password string, salt string) string
-}
-
-// UserPasswordSalt interface.
-type UserPasswordSalt interface {
-	User
-	PasswordSalt
-}
diff --git a/voter.go b/voter.go
new file mode 100644
index 0000000..1f4036b
--- /dev/null
+++ b/voter.go
@@ -0,0 +1,55 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package security
+
+import "context"
+
+// Decision is the verdict returned by a [Voter] for a given authentication
+// and attribute set. Three values are defined:
+//
+//   - [DecisionGrant] — the voter explicitly grants access.
+//   - [DecisionDeny]  — the voter explicitly denies access.
+//   - [DecisionAbstain] — the voter has no opinion (e.g. it does not support
+//     any of the attributes presented). The
+//     [AccessDecisionManager] strategy decides what to
+//     do when every voter abstains.
+type Decision int
+
+// Voting verdicts. The numeric layout (-1/0/1) is deliberate so that
+// algorithms summing decisions remain readable.
+const (
+	DecisionDeny    Decision = -1
+	DecisionAbstain Decision = 0
+	DecisionGrant   Decision = 1
+)
+
+// String returns a stable lowercase form ("permit", "deny", "abstain") used
+// for OTel attribute values. "permit" is preferred over "grant" to match the
+// XACML vocabulary widely understood by security teams.
+func (d Decision) String() string {
+	switch d {
+	case DecisionGrant:
+		return "permit"
+	case DecisionDeny:
+		return "deny"
+	case DecisionAbstain:
+		return "abstain"
+	default:
+		return "unknown"
+	}
+}
+
+// Voter is the unit of authorisation logic. It inspects an [Authentication]
+// against a set of [Attribute]s and returns a [Decision]. Voters MUST be
+// pure (no I/O) and safe for concurrent use.
+//
+// Supports is a fast-path filter: a voter that does not recognize any of the
+// passed attributes SHOULD return false to short-circuit the call. When
+// Supports returns false, the [AccessDecisionManager] records an abstention
+// for the voter without invoking Vote.
+type Voter interface {
+	Supports(attr Attribute) bool
+	Vote(ctx context.Context, auth Authentication, attrs []Attribute) Decision
+}
diff --git a/voter/auth_state.go b/voter/auth_state.go
new file mode 100644
index 0000000..8be0647
--- /dev/null
+++ b/voter/auth_state.go
@@ -0,0 +1,57 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// Authenticated returns a voter that grants when the request carries an
+// authenticated [security.Authentication]. Useful as the universal
+// "must be logged in" check before more specific role/scope voters run.
+func Authenticated() security.Voter { return authStateVoter{requireAuth: true} }
+
+// Anonymous returns a voter that grants when the request is NOT
+// authenticated. Useful for endpoints reserved to logged-out clients
+// (signup, password-reset request, ...).
+func Anonymous() security.Voter { return authStateVoter{requireAuth: false} }
+
+// FullyAuthenticated is a stricter variant of [Authenticated] reserved for
+// flows where "remember-me" / passive sessions must NOT be enough (e.g.
+// password change, billing changes). It currently behaves like
+// Authenticated; it is the hook a future "remember-me" session flag would
+// key off to refuse passively-authenticated requests.
+func FullyAuthenticated() security.Voter { return authStateVoter{requireAuth: true, fully: true} }
+
+type authStateVoter struct {
+	requireAuth bool
+	fully       bool
+}
+
+// Supports always returns true: the auth-state voters do not need a specific
+// attribute; they observe the request itself.
+func (authStateVoter) Supports(security.Attribute) bool { return true }
+
+func (v authStateVoter) Vote(_ context.Context, auth security.Authentication, _ []security.Attribute) security.Decision {
+	if v.requireAuth {
+		if !auth.IsAuthenticated() {
+			return security.DecisionDeny
+		}
+
+		// The "fully" flag will gain teeth when session.Authentication
+		// exposes IsRememberMe(); for now any authenticated value qualifies.
+		_ = v.fully
+
+		return security.DecisionGrant
+	}
+
+	if auth.IsAuthenticated() {
+		return security.DecisionDeny
+	}
+
+	return security.DecisionGrant
+}
diff --git a/voter/auth_state_test.go b/voter/auth_state_test.go
new file mode 100644
index 0000000..8f4b46b
--- /dev/null
+++ b/voter/auth_state_test.go
@@ -0,0 +1,56 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAuthenticatedGrantsLoggedIn(t *testing.T) {
+	t.Parallel()
+
+	v := voter.Authenticated()
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a"), nil))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAnonymous(), nil))
+}
+
+func TestAnonymousGrantsLoggedOut(t *testing.T) {
+	t.Parallel()
+
+	v := voter.Anonymous()
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAnonymous(), nil))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a"), nil))
+}
+
+func TestFullyAuthenticatedCurrentlyTracksAuthenticated(t *testing.T) {
+	t.Parallel()
+
+	v := voter.FullyAuthenticated()
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a"), nil))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAnonymous(), nil))
+}
+
+func TestAuthStateVotersSupportEverything(t *testing.T) {
+	t.Parallel()
+
+	// auth-state voters do not consume attribute-specific information;
+	// they observe the Authentication itself, so Supports must return true
+	// regardless of attribute family (the ADM will still call Vote).
+	for _, v := range []security.Voter{voter.Authenticated(), voter.Anonymous(), voter.FullyAuthenticated()} {
+		assert.True(t, v.Supports(security.Role("X")))
+		assert.True(t, v.Supports(security.Scope("y")))
+	}
+}
diff --git a/voter/authority.go b/voter/authority.go
new file mode 100644
index 0000000..2e33ad0
--- /dev/null
+++ b/voter/authority.go
@@ -0,0 +1,54 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+	"slices"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// HasAuthority returns a [security.Voter] that grants when the authenticated
+// principal carries the given authority verbatim. No prefix normalisation
+// (use [HasRole] / [HasScope] when you want the conventions of those types).
+func HasAuthority(name string) security.Voter {
+	return authorityVoter{wanted: []string{name}, anyOf: false}
+}
+
+// HasAnyAuthority grants when the principal carries at least one of the
+// listed authorities.
+func HasAnyAuthority(names ...string) security.Voter {
+	return authorityVoter{wanted: names, anyOf: true}
+}
+
+type authorityVoter struct {
+	wanted []string
+	anyOf  bool
+}
+
+func (v authorityVoter) Supports(a security.Attribute) bool {
+	_, ok := a.(security.AuthorityAttribute)
+
+	return ok
+}
+
+func (v authorityVoter) Vote(_ context.Context, auth security.Authentication, _ []security.Attribute) security.Decision {
+	if !auth.IsAuthenticated() {
+		return security.DecisionDeny
+	}
+
+	for _, want := range v.wanted {
+		if slices.Contains(auth.Authorities(), want) {
+			return security.DecisionGrant
+		}
+
+		if !v.anyOf {
+			break
+		}
+	}
+
+	return security.DecisionDeny
+}
diff --git a/voter/authority_test.go b/voter/authority_test.go
new file mode 100644
index 0000000..857ce37
--- /dev/null
+++ b/voter/authority_test.go
@@ -0,0 +1,48 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasAuthorityVerbatim(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasAuthority("billing:write")
+	attrs := []security.Attribute{security.Authority("billing:write")}
+
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a", "billing:write"), attrs))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a", "billing:read"), attrs))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAnonymous(), attrs))
+}
+
+func TestHasAuthoritySupportsOnlyAuthorityAttribute(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasAuthority("x")
+	assert.True(t, v.Supports(security.Authority("x")))
+	assert.False(t, v.Supports(security.Role("ADMIN")))
+}
+
+func TestHasAnyAuthorityMatchesOne(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasAnyAuthority("alpha", "beta")
+	attrs := []security.Attribute{security.Authority("alpha")}
+
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a", "beta"), attrs))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a", "gamma"), attrs))
+}
diff --git a/voter/composite.go b/voter/composite.go
new file mode 100644
index 0000000..3af3bcd
--- /dev/null
+++ b/voter/composite.go
@@ -0,0 +1,118 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// And combines voters with conjunction semantics:
+//
+//   - Any inner Deny  => Deny.
+//   - At least one Grant and no Deny => Grant.
+//   - All inner voters Abstain      => Abstain.
+//
+// Inner abstentions never block the conjunction: a permission voter that
+// does not apply to the current attributes should not single-handedly veto.
+func And(voters ...security.Voter) security.Voter {
+	return compositeVoter{voters: voters, mode: composeAnd}
+}
+
+// Or combines voters with disjunction semantics:
+//
+//   - Any inner Grant => Grant.
+//   - No Grant and at least one Deny => Deny.
+//   - All inner voters Abstain      => Abstain.
+func Or(voters ...security.Voter) security.Voter {
+	return compositeVoter{voters: voters, mode: composeOr}
+}
+
+// Not inverts an inner voter: Grant <-> Deny; Abstain stays Abstain.
+func Not(inner security.Voter) security.Voter {
+	return compositeVoter{voters: []security.Voter{inner}, mode: composeNot}
+}
+
+type composeMode int
+
+const (
+	composeAnd composeMode = iota
+	composeOr
+	composeNot
+)
+
+type compositeVoter struct {
+	voters []security.Voter
+	mode   composeMode
+}
+
+// Supports returns true when at least one inner voter does, plus always for
+// the auth-state voters embedded inside the composite (they Supports anything).
+func (c compositeVoter) Supports(a security.Attribute) bool {
+	for _, v := range c.voters {
+		if v.Supports(a) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (c compositeVoter) Vote(ctx context.Context, auth security.Authentication, attrs []security.Attribute) security.Decision {
+	if c.mode == composeNot {
+		switch c.voters[0].Vote(ctx, auth, attrs) {
+		case security.DecisionGrant:
+			return security.DecisionDeny
+		case security.DecisionDeny:
+			return security.DecisionGrant
+		case security.DecisionAbstain:
+			return security.DecisionAbstain
+		}
+	}
+
+	var (
+		sawGrant bool
+		sawDeny  bool
+	)
+
+	for _, v := range c.voters {
+		switch v.Vote(ctx, auth, attrs) {
+		case security.DecisionGrant:
+			sawGrant = true
+		case security.DecisionDeny:
+			sawDeny = true
+		case security.DecisionAbstain:
+			// ignore
+		}
+	}
+
+	switch c.mode {
+	case composeAnd:
+		switch {
+		case sawDeny:
+			return security.DecisionDeny
+		case sawGrant:
+			return security.DecisionGrant
+		default:
+			return security.DecisionAbstain
+		}
+	case composeOr:
+		switch {
+		case sawGrant:
+			return security.DecisionGrant
+		case sawDeny:
+			return security.DecisionDeny
+		default:
+			return security.DecisionAbstain
+		}
+	case composeNot:
+		// Unreachable: composeNot is handled by the early return above; the
+		// case is here only to make the switch exhaustive.
+		return security.DecisionAbstain
+	}
+
+	return security.DecisionAbstain
+}
diff --git a/voter/composite_test.go b/voter/composite_test.go
new file mode 100644
index 0000000..79218cd
--- /dev/null
+++ b/voter/composite_test.go
@@ -0,0 +1,93 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+// constVoter is a tiny voter returning a fixed verdict; only useful to
+// drive the composite tests without setting up real authentications/attrs.
+type constVoter struct{ d security.Decision }
+
+func (c constVoter) Supports(security.Attribute) bool { return true }
+func (c constVoter) Vote(context.Context, security.Authentication, []security.Attribute) security.Decision {
+	return c.d
+}
+
+func TestAndTruthTable(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		in   []security.Decision
+		want security.Decision
+	}{
+		{"all_grant", []security.Decision{security.DecisionGrant, security.DecisionGrant}, security.DecisionGrant},
+		{"one_deny", []security.Decision{security.DecisionGrant, security.DecisionDeny}, security.DecisionDeny},
+		{"all_abstain", []security.Decision{security.DecisionAbstain, security.DecisionAbstain}, security.DecisionAbstain},
+		{"grant_with_abstain", []security.Decision{security.DecisionGrant, security.DecisionAbstain}, security.DecisionGrant},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			vs := make([]security.Voter, len(c.in))
+			for i, d := range c.in {
+				vs[i] = constVoter{d: d}
+			}
+
+			got := voter.And(vs...).Vote(context.Background(), newAuth("a"), nil)
+			assert.Equal(t, c.want, got)
+		})
+	}
+}
+
+func TestOrTruthTable(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		in   []security.Decision
+		want security.Decision
+	}{
+		{"all_deny", []security.Decision{security.DecisionDeny, security.DecisionDeny}, security.DecisionDeny},
+		{"one_grant", []security.Decision{security.DecisionGrant, security.DecisionDeny}, security.DecisionGrant},
+		{"all_abstain", []security.Decision{security.DecisionAbstain, security.DecisionAbstain}, security.DecisionAbstain},
+		{"deny_with_abstain", []security.Decision{security.DecisionDeny, security.DecisionAbstain}, security.DecisionDeny},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			vs := make([]security.Voter, len(c.in))
+			for i, d := range c.in {
+				vs[i] = constVoter{d: d}
+			}
+
+			got := voter.Or(vs...).Vote(context.Background(), newAuth("a"), nil)
+			assert.Equal(t, c.want, got)
+		})
+	}
+}
+
+func TestNotInvertsGrantAndDeny(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct{ in, want security.Decision }{
+		{security.DecisionGrant, security.DecisionDeny},
+		{security.DecisionDeny, security.DecisionGrant},
+		{security.DecisionAbstain, security.DecisionAbstain},
+	}
+	for _, c := range cases {
+		got := voter.Not(constVoter{d: c.in}).Vote(context.Background(), newAuth("a"), nil)
+		assert.Equal(t, c.want, got, "in=%v", c.in)
+	}
+}
diff --git a/voter/doc.go b/voter/doc.go
new file mode 100644
index 0000000..ea91291
--- /dev/null
+++ b/voter/doc.go
@@ -0,0 +1,13 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+// Package voter ships the catalog of stock [security.Voter]
+// implementations consumed by [security.AccessDecisionManager].
+//
+// Each voter Supports a single attribute family (roles, scopes,
+// authorities, permissions, or authentication state). Compose them through
+// And/Or/Not for richer policies.
+//
+// Voters are pure (no I/O) and safe for concurrent use.
+package voter
diff --git a/voter/example_test.go b/voter/example_test.go
new file mode 100644
index 0000000..a7cf9ac
--- /dev/null
+++ b/voter/example_test.go
@@ -0,0 +1,56 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+)
+
+// Example shows the canonical authorization pipeline: bind the expected
+// permission into the voter at construction time and call Decide on the
+// known authentication. Attributes are matched against Voter.Supports to
+// activate the voter; the voter itself knows what to check.
+func Example() {
+	adminOnly := security.NewAffirmativeDecisionManager(
+		voter.HasRole("ADMIN"),
+	)
+	writeMail := security.NewAffirmativeDecisionManager(
+		voter.HasScope("write:mail"),
+	)
+
+	auth := newAuth("alice", "ROLE_ADMIN", "scope:read:mail")
+	roleAttrs := []security.Attribute{security.Role("ADMIN")}
+	scopeAttrs := []security.Attribute{security.Scope("write:mail")}
+
+	fmt.Println("admin only:", adminOnly.Decide(context.Background(), auth, roleAttrs))
+	fmt.Println("write:mail:", writeMail.Decide(context.Background(), auth, scopeAttrs))
+
+	// Output:
+	// admin only: <nil>
+	// write:mail: security: access denied
+}
+
+// Example_compose demonstrates the And/Or/Not combinators.
+func Example_compose() {
+	adm := security.NewAffirmativeDecisionManager(
+		voter.And(
+			voter.Authenticated(),
+			voter.HasAnyRole("ADMIN", "MANAGER"),
+		),
+	)
+
+	auth := newAuth("bob", "ROLE_MANAGER")
+	err := adm.Decide(context.Background(), auth, []security.Attribute{
+		security.Role("ADMIN"),
+	})
+	fmt.Println("manager:", err)
+
+	// Output:
+	// manager: <nil>
+}
diff --git a/voter/permission.go b/voter/permission.go
new file mode 100644
index 0000000..583fd5f
--- /dev/null
+++ b/voter/permission.go
@@ -0,0 +1,63 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// HasPermission returns a [security.Voter] that evaluates every
+// [security.PermissionAttribute] passed to it via its embedded predicate.
+//
+// Vote semantics:
+//   - Unauthenticated => Deny.
+//   - No PermissionAttribute in attrs => Abstain (Supports() will short-
+//     circuit before reaching Vote in practice).
+//   - Any predicate returning false => Deny.
+//   - Every predicate returning true => Grant.
+//   - A nil predicate is treated as Deny (defensive default; refusing to
+//     authorize on an empty rule is safer than the alternative).
+func HasPermission() security.Voter { return permissionVoter{} }
+
+type permissionVoter struct{}
+
+func (permissionVoter) Supports(a security.Attribute) bool {
+	_, ok := a.(security.PermissionAttribute)
+
+	return ok
+}
+
+func (permissionVoter) Vote(ctx context.Context, auth security.Authentication, attrs []security.Attribute) security.Decision {
+	if !auth.IsAuthenticated() {
+		return security.DecisionDeny
+	}
+
+	saw := false
+
+	for _, a := range attrs {
+		p, ok := a.(security.PermissionAttribute)
+		if !ok {
+			continue
+		}
+
+		saw = true
+
+		if p.Predicate == nil {
+			return security.DecisionDeny
+		}
+
+		if !p.Predicate(ctx, auth) {
+			return security.DecisionDeny
+		}
+	}
+
+	if !saw {
+		return security.DecisionAbstain
+	}
+
+	return security.DecisionGrant
+}
diff --git a/voter/permission_supports_test.go b/voter/permission_supports_test.go
new file mode 100644
index 0000000..57a9fa7
--- /dev/null
+++ b/voter/permission_supports_test.go
@@ -0,0 +1,24 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasPermissionSupports(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasPermission()
+
+	// The permission voter opts in only for PermissionAttribute.
+	assert.True(t, v.Supports(security.Permission("owns-doc", nil)))
+	assert.False(t, v.Supports(security.Role("ADMIN")))
+	assert.False(t, v.Supports(security.Scope("read")))
+}
diff --git a/voter/permission_test.go b/voter/permission_test.go
new file mode 100644
index 0000000..ddc2928
--- /dev/null
+++ b/voter/permission_test.go
@@ -0,0 +1,66 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasPermissionEvaluatesPredicate(t *testing.T) {
+	t.Parallel()
+
+	owner := security.Permission("owner", func(_ context.Context, a security.Authentication) bool {
+		return a.Principal().Subject() == "alice"
+	})
+
+	v := voter.HasPermission()
+
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("alice"), []security.Attribute{owner}))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("bob"), []security.Attribute{owner}))
+}
+
+func TestHasPermissionDeniesUnauthenticated(t *testing.T) {
+	t.Parallel()
+
+	always := security.Permission("ok", func(context.Context, security.Authentication) bool { return true })
+	v := voter.HasPermission()
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAnonymous(), []security.Attribute{always}))
+}
+
+func TestHasPermissionAllPredicatesMustGrant(t *testing.T) {
+	t.Parallel()
+
+	pass := security.Permission("pass", func(context.Context, security.Authentication) bool { return true })
+	fail := security.Permission("fail", func(context.Context, security.Authentication) bool { return false })
+	v := voter.HasPermission()
+
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a"), []security.Attribute{pass, fail}))
+}
+
+func TestHasPermissionAbstainsWhenNoPermissionAttribute(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasPermission()
+	assert.Equal(t, security.DecisionAbstain,
+		v.Vote(context.Background(), newAuth("a"), []security.Attribute{security.Role("X")}))
+}
+
+func TestHasPermissionNilPredicateIsDeny(t *testing.T) {
+	t.Parallel()
+
+	bad := security.PermissionAttribute{Name: "bad", Predicate: nil}
+	v := voter.HasPermission()
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a"), []security.Attribute{bad}))
+}
diff --git a/voter/role.go b/voter/role.go
new file mode 100644
index 0000000..d443f73
--- /dev/null
+++ b/voter/role.go
@@ -0,0 +1,76 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+	"slices"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// HasRole returns a [security.Voter] that grants when the authenticated
+// principal carries the given role (matched on Authorities() with the
+// Spring-style ROLE_ prefix). Unauthenticated requests always vote Deny;
+// foreign attribute families produce Abstain.
+//
+// The voter compares against [security.Authentication.Authorities] in two
+// shapes: with and without the ROLE_ prefix, so applications can use either
+// convention in their user store.
+func HasRole(role string) security.Voter {
+	return roleVoter{wanted: []string{role}, anyOf: false}
+}
+
+// HasAnyRole grants when the principal carries at least one of the listed
+// roles. Same comparison rules as [HasRole].
+func HasAnyRole(roles ...string) security.Voter {
+	return roleVoter{wanted: roles, anyOf: true}
+}
+
+type roleVoter struct {
+	wanted []string
+	anyOf  bool
+}
+
+func (v roleVoter) Supports(a security.Attribute) bool {
+	_, ok := a.(security.RoleAttribute)
+
+	return ok
+}
+
+func (v roleVoter) Vote(_ context.Context, auth security.Authentication, attrs []security.Attribute) security.Decision {
+	if !auth.IsAuthenticated() {
+		return security.DecisionDeny
+	}
+
+	for _, want := range v.wanted {
+		if hasRole(auth.Authorities(), want) {
+			return security.DecisionGrant
+		}
+
+		if !v.anyOf {
+			// Single-role mode: every wanted role MUST match; one miss is
+			// enough to deny. But there's only one entry, so the loop is
+			// degenerate — fall through to deny below.
+			break
+		}
+	}
+	// Touch attrs to keep the parameter meaningful in tests that supply
+	// attributes; voters do not need to inspect them when the role list
+	// is pre-bound.
+	_ = attrs
+
+	return security.DecisionDeny
+}
+
+// hasRole reports whether authorities contains role either verbatim or with
+// the Spring-style ROLE_ prefix.
+func hasRole(authorities []string, role string) bool {
+	if slices.Contains(authorities, role) {
+		return true
+	}
+
+	return slices.Contains(authorities, "ROLE_"+role)
+}
diff --git a/voter/role_test.go b/voter/role_test.go
new file mode 100644
index 0000000..d303493
--- /dev/null
+++ b/voter/role_test.go
@@ -0,0 +1,68 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasRoleSupportsOnlyRoleAttribute(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasRole("ADMIN")
+	assert.True(t, v.Supports(security.Role("ADMIN")))
+	assert.False(t, v.Supports(security.Scope("read")))
+}
+
+func TestHasRoleMatchesEitherPrefixedOrBare(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasRole("ADMIN")
+	attrs := []security.Attribute{security.Role("ADMIN")}
+
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a", "ADMIN"), attrs))
+	assert.Equal(t, security.DecisionGrant,
+		v.Vote(context.Background(), newAuth("a", "ROLE_ADMIN"), attrs))
+	assert.Equal(t, security.DecisionDeny,
+		v.Vote(context.Background(), newAuth("a", "USER"), attrs))
+}
+
+func TestHasRoleDeniesUnauthenticated(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasRole("ADMIN")
+	got := v.Vote(context.Background(), newAnonymous(), []security.Attribute{security.Role("ADMIN")})
+	assert.Equal(t, security.DecisionDeny, got)
+}
+
+func TestHasAnyRoleMatchesAtLeastOne(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasAnyRole("ADMIN", "OWNER")
+	attrs := []security.Attribute{security.Role("ADMIN")}
+
+	cases := []struct {
+		name string
+		auth fakeAuth
+		want security.Decision
+	}{
+		{"first_matches", newAuth("a", "ROLE_ADMIN"), security.DecisionGrant},
+		{"second_matches", newAuth("a", "OWNER"), security.DecisionGrant},
+		{"neither", newAuth("a", "USER"), security.DecisionDeny},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, c.want, v.Vote(context.Background(), c.auth, attrs))
+		})
+	}
+}
diff --git a/voter/scope.go b/voter/scope.go
new file mode 100644
index 0000000..d2cb780
--- /dev/null
+++ b/voter/scope.go
@@ -0,0 +1,85 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter
+
+import (
+	"context"
+	"slices"
+	"strings"
+
+	"github.com/hyperscale-stack/security"
+)
+
+// HasScope returns a [security.Voter] that grants when the authenticated
+// principal carries the given OAuth2 scope. Scope matching is exact and
+// supports two storage conventions on [security.Authentication.Authorities]:
+//
+//   - bare scope name ("read:mail")
+//   - "scope:" prefix ("scope:read:mail")
+//
+// Unauthenticated requests always vote Deny; non-scope attributes Abstain.
+func HasScope(scope string) security.Voter {
+	return scopeVoter{wanted: []string{scope}, anyOf: false}
+}
+
+// HasAnyScope grants when the principal carries at least one of the listed
+// scopes. Same comparison rules as [HasScope].
+func HasAnyScope(scopes ...string) security.Voter {
+	return scopeVoter{wanted: scopes, anyOf: true}
+}
+
+type scopeVoter struct {
+	wanted []string
+	anyOf  bool
+}
+
+func (v scopeVoter) Supports(a security.Attribute) bool {
+	_, ok := a.(security.ScopeAttribute)
+
+	return ok
+}
+
+func (v scopeVoter) Vote(_ context.Context, auth security.Authentication, _ []security.Attribute) security.Decision {
+	if !auth.IsAuthenticated() {
+		return security.DecisionDeny
+	}
+
+	for _, want := range v.wanted {
+		if hasScope(auth.Authorities(), want) {
+			return security.DecisionGrant
+		}
+
+		if !v.anyOf {
+			break
+		}
+	}
+
+	return security.DecisionDeny
+}
+
+func hasScope(authorities []string, scope string) bool {
+	if slices.Contains(authorities, scope) {
+		return true
+	}
+
+	prefixed := "scope:" + scope
+
+	for _, a := range authorities {
+		if a == prefixed {
+			return true
+		}
+		// Also accept the OAuth2 "scope" claim packaged as a
+		// space-separated string in a single authority.
+		if strings.HasPrefix(a, "scope:") {
+			for _, s := range strings.Split(a[len("scope:"):], " ") {
+				if s == scope {
+					return true
+				}
+			}
+		}
+	}
+
+	return false
+}
diff --git a/voter/scope_test.go b/voter/scope_test.go
new file mode 100644
index 0000000..eec2a98
--- /dev/null
+++ b/voter/scope_test.go
@@ -0,0 +1,72 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hyperscale-stack/security"
+	"github.com/hyperscale-stack/security/voter"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasScopeMatchesStorageConventions(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasScope("read:mail")
+	attrs := []security.Attribute{security.Scope("read:mail")}
+
+	cases := []struct {
+		name string
+		auth fakeAuth
+		want security.Decision
+	}{
+		{"bare_match", newAuth("a", "read:mail"), security.DecisionGrant},
+		{"prefixed_match", newAuth("a", "scope:read:mail"), security.DecisionGrant},
+		{"space_packed_match", newAuth("a", "scope:foo read:mail write:mail"), security.DecisionGrant},
+		{"miss", newAuth("a", "write:mail"), security.DecisionDeny},
+		{"unauthenticated", newAnonymous(), security.DecisionDeny},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, c.want, v.Vote(context.Background(), c.auth, attrs))
+		})
+	}
+}
+
+func TestHasScopeSupportsOnlyScopeAttribute(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasScope("read")
+	assert.True(t, v.Supports(security.Scope("read")))
+	assert.False(t, v.Supports(security.Role("ADMIN")))
+}
+
+func TestHasAnyScopeMatchesAtLeastOne(t *testing.T) {
+	t.Parallel()
+
+	v := voter.HasAnyScope("read", "write")
+	attrs := []security.Attribute{security.Scope("read")}
+
+	cases := []struct {
+		name string
+		auth fakeAuth
+		want security.Decision
+	}{
+		{"first", newAuth("a", "read"), security.DecisionGrant},
+		{"second", newAuth("a", "write"), security.DecisionGrant},
+		{"none", newAuth("a", "admin"), security.DecisionDeny},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, c.want, v.Vote(context.Background(), c.auth, attrs))
+		})
+	}
+}
diff --git a/voter/testing_helpers_test.go b/voter/testing_helpers_test.go
new file mode 100644
index 0000000..27d8896
--- /dev/null
+++ b/voter/testing_helpers_test.go
@@ -0,0 +1,33 @@
+// Copyright 2026 Hyperscale. All rights reserved.
+// Use of this source code is governed by a MIT
+// license that can be found in the LICENSE file.
+
+package voter_test
+
+import "github.com/hyperscale-stack/security"
+
+// fakePrincipal / fakeAuth mirror the minimal Principal+Authentication used
+// across other packages' test suites.
+type fakePrincipal struct{ sub string }
+
+func (p fakePrincipal) Subject() string { return p.sub }
+
+type fakeAuth struct {
+	pr            security.Principal
+	authorities   []string
+	authenticated bool
+}
+
+func newAuth(sub string, authorities ...string) fakeAuth {
+	return fakeAuth{pr: fakePrincipal{sub: sub}, authorities: authorities, authenticated: true}
+}
+
+func newAnonymous() fakeAuth {
+	return fakeAuth{pr: security.AnonymousPrincipal}
+}
+
+func (a fakeAuth) Principal() security.Principal { return a.pr }
+func (a fakeAuth) Credentials() any              { return nil }
+func (a fakeAuth) Authorities() []string         { return a.authorities }
+func (a fakeAuth) IsAuthenticated() bool         { return a.authenticated }
+func (a fakeAuth) Name() string                  { return a.pr.Subject() }