hex-restapi-auth
Use when an HTTP entrypoint must authenticate its caller or gate a route on a role. Owns the caller identity, the token-verifier port and adapter, the `get_current_user` / `require_role` route depende
SKILL.mdplugins/pyhouse-hex/skills/hex-restapi-auth/SKILL.md
GitHubHex REST — Auth
Authentication and transport-level authorization for a hexagonal REST service. Everything here is
optional: a service whose routes need no caller identity — a public API, an internal worker-facing
one, or one behind a gateway that authenticates for it and passes nothing inward — declares no auth and
never loads this skill; one that reads the caller from a gateway's header takes the gateway binding
under Other bindings. The REST core (hex-restapi-app, hex-restapi-endpoint,
hex-restapi-schema) is complete without it.
Auth is conditional, not presumed. An app has auth when some endpoint is non-anonymous, or a token-verifier capability is wired — there is no separate flag for it. "Adding auth" means adding the artifacts below; an app whose every endpoint is anonymous has no auth layer at all, which is the absence of the feature rather than "skipping auth".
The principle this binds: the entrypoint authenticates the caller, resolves a caller identity, and passes it inward as ordinary data on a command or query DTO. No layer below the entrypoint knows how authentication happened. Authorization that is a business rule is a domain concern; authorization that is a transport rule — a single role-rank check — belongs here.
When to use vs. neighbours
- The app shell, middleware, the central error translator and
schemas/errors.py→hex-restapi-app. - A route's signature and body →
hex-restapi-endpoint. - Which error codes a route advertises for non-auth reasons →
hex-restapi-endpoint, in its siblingCONTRACTS.md; registering a status a middleware introduces →hex-restapi-app, Registering a middleware's status. UnauthorizedError/ForbiddenErrorthemselves, and boundary translation →exception-catalog.- Enum and value-object form in general →
hex-domain-model. - How to write the capability protocol the verifier satisfies →
hex-domain-ports. - Adapter form in general — constructor injection, secrets, no logging, no business logic →
hex-capability-adapter; this skill carries only the verifier instance of it. - What a settings class declares →
python-settings; binding lifetimes and composition-root declaration order →hex-wiring. - Authorization finer than a single role-rank check →
hex-application; the handler raisesForbiddenError. - The fixtures that mint tokens, the
authenticated_client, and the unauthenticated-probe invariant →hex-test-restapi-auth. - A login or token-refresh request/response model, or any other per-resource wire schema →
hex-restapi-schema; this skill owns the dependencies, not the bodies.
The caller identity
CurrentUser is what the entrypoint resolves and what every auth-derived DTO field is stamped from.
It is a domain value object under a cross-cutting subdomain package (domain/auth/, per
hex-domain-ports' placement rule for cross-cutting capabilities).
domain/auth/current_user.py
from dataclasses import dataclass
__all__ = ["CurrentUser"]
@dataclass(frozen=True, slots=True)
class CurrentUser:
id: str
id is the credential's subject exactly as the issuer states it. It is converted to the app's own id
type only where the issuer guarantees that form; otherwise a subject the app did not mint would fail
to parse and lock a valid caller out. A rank app adds a role (Rank apps only, below); a tenant is
added the same way, and which DTO fields are stamped from the identity, and how a handler scopes by
them, are hex-application's.
The token-verifier port
domain/auth/i_can_verify_token.py
from typing import Protocol
from .current_user import CurrentUser
__all__ = ["ICanVerifyToken"]
class ICanVerifyToken(Protocol):
def verify(self, token: str) -> CurrentUser: ...
Signature verification is pure CPU, so the method is sync, not async — the capability-shape rule in
hex-domain-ports. The port names no claim. Its contract is credential in, identity out; which
keys, headers or certificate fields a scheme yields, and how they map onto the identity's fields, is the
adapter's alone (rule 12).
The verifier adapter
Template — PyJWT
Placement (infrastructure/jwt/, the external technology), constructor injection, secret handling, the
no-logging rule and not importing the port it satisfies (ICanVerifyToken) are
hex-capability-adapter's; this is the sync pure-CPU adapter that skill describes in prose, bound to
PyJWT. Translation of the library's parse/verify errors follows exception-catalog.
import jwt
from myapp.domain.auth import CurrentUser
from myapp.domain.exceptions import UnauthorizedError
from .jwt_settings import JwtSettings
__all__ = ["PyJwtTokenVerifier"]
class PyJwtTokenVerifier:
def __init__(self, settings: JwtSettings) -> None:
self._public_key = settings.public_key.get_secret_value()
self._algorithm = settings.algorithm
self._issuer = settings.issuer
self._audience = settings.audience
def verify(self, token: str) -> CurrentUser:
try:
claims = jwt.decode(
token,
self._public_key,
algorithms=[self._algorithm],
issuer=self._issuer,
audience=self._audience,
options={"require": ["exp", "sub"]},
)
return CurrentUser(id=claims["sub"])
except jwt.ExpiredSignatureError as exc:
raise UnauthorizedError("token expired", {"reason": "expired"}) from exc
except jwt.InvalidTokenError as exc:
raise UnauthorizedError("invalid token", {"reason": "invalid"}) from exc
algorithms=[...] is a list of one, read from settings — never the token's own alg header. A
verifier that trusts the header accepts none and accepts a symmetric algorithm signed with the public
key it published; the settings-side allowlist validator below is what keeps that list honest.
The identity is built inside the translated scope. A token can carry a valid signature and still
not describe a caller — a claim missing, a subject of the wrong type. Each of those is an unverifiable
credential and answers 401 like a bad signature, never a 500. Here require turns an absent claim into
the library's own InvalidTokenError, and PyJWT (2.10 and later) rejects a non-string sub the same
way. The library is declared with that floor, pyjwt>=2.10, wherever this verifier is
(python-toolchain rule 9). A token that states no expiry is refused rather than trusted for ever:
the library checks exp only when the claim is present, so the verifier requires it.
reason is one of a fixed set the app owns — expired, invalid, missing_credentials, and
invalid_claims in a rank app — never the library's exception class name: context reaches the
response body verbatim, where a client keys on it, and a library upgrade renames its classes
(exception-catalog rule 11).
infrastructure/jwt/jwt_settings.py
from pydantic import SecretStr, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
__all__ = ["JwtSettings"]
_ALLOWED_ALGORITHMS = frozenset({"RS256", "RS384", "RS512", "ES256", "EdDSA"})
class JwtSettings(BaseSettings):
model_config = SettingsConfigDict(
env_prefix="MYAPP_JWT_",
env_file=".env", # only where the project keeps a dotenv file for development
extra="ignore",
hide_input_in_errors=True,
)
algorithm: str = "RS256"
public_key: SecretStr
issuer: str
audience: str
@field_validator("algorithm")
@classmethod
def _reject_unlisted_algorithm(cls, value: str) -> str:
if value not in _ALLOWED_ALGORITHMS:
raise ValueError(f"JWT algorithm {value!r} is not in the allowlist {sorted(_ALLOWED_ALGORITHMS)}")
return value
The allowlist is python-settings rule 12's rejection validator: an alg of none, or HS256 against
a published public key, verifies happily and forges every identity in the system, so the settings refuse
it when they are built, before any token is verified. A service that is its own issuer may allow one HMAC algorithm with a secret
key instead, never beside a published public key. Where the deployment can pass the key only on one
line, restoring its newlines is python-settings rule 12's normalization. The allowlist, the
Authorization header and the RFC-7235 challenge are this scheme's own — an opaque token, a session
cookie and a gateway header have none of them — which is why they sit with this binding; the header is
read in one place (rule 3) and the challenge carries the scheme alone (rule 8).
The route dependencies
restapi/dependencies.py
dependencies.py is FastAPI's home for shared route dependencies; the auth dependency is its first
occupant, so an auth-less app has no such file (hex-restapi-app).
from dishka.integrations.fastapi import FromDishka, inject
from fastapi import Depends
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from myapp.domain.auth import CurrentUser, ICanVerifyToken
from myapp.domain.exceptions import UnauthorizedError
__all__ = ["get_current_user"]
_bearer_scheme = HTTPBearer(auto_error=False)
@inject
async def get_current_user(
verifier: FromDishka[ICanVerifyToken],
credentials: HTTPAuthorizationCredentials | None = Depends(_bearer_scheme),
) -> CurrentUser:
if credentials is None:
raise UnauthorizedError("Missing bearer token", {"reason": "missing_credentials"})
return verifier.verify(credentials.credentials)
The bearer scheme is declared once at module level. get_current_user receives the verifier by
its port type — never instantiate verifiers in routes or dependencies. The @inject decorator is
required here even though the routers carry route_class=DishkaRoute: that route class injects route
functions, not the Depends functions behind them (hex-restapi-endpoint). The verifier arrives typed,
so nothing is cast.
Rank apps only — the role gate
Where some route gates on rank, four things are added; an app whose routes only authenticate has none
of them. CurrentUser gains role: Role. The verifier requires the claim ("require": ["exp", "sub", "role"]), builds CurrentUser(id=claims["sub"], role=Role(claims["role"])), and gains one arm —
except ValueError → UnauthorizedError("invalid token claims", {"reason": "invalid_claims"}) —
because a role the app does not declare is an unverifiable credential, never a 500.
domain/auth/role.py holds the ladder:
from enum import StrEnum
__all__ = ["Role"]
_RANK = {"LOWER": 0, "HIGHER": 1}
class Role(StrEnum):
LOWER = "LOWER"
HIGHER = "HIGHER"
def satisfies(self, required: "Role") -> bool:
return _RANK[self.value] >= _RANK[required.value]
The self-reference is quoted because the name is not bound until the class statement finishes and the
catalogue bans from __future__ import annotations (python-style). LOWER and HIGHER are
placeholder ranks, the way Foo is the placeholder aggregate: substitute the app's own members,
however many it has; a route template names the slot — Role.<MIN_RANK> — never a member. Its unit
test covers satisfies at, above and below the bar (hex-test-domain).
restapi/dependencies.py gains the gate below get_current_user, and require_role joins its
__all__. The gate is a callable class, not a closure, so the role it gates on is a typed attribute:
from fastapi import Depends
from myapp.domain.auth import CurrentUser, Role
from myapp.domain.exceptions import ForbiddenError
class _RoleDependency:
def __init__(self, required: Role) -> None:
self.required_role = required
def __call__(self, user: CurrentUser = Depends(get_current_user)) -> CurrentUser:
if not user.role.satisfies(self.required_role):
raise ForbiddenError(
"Insufficient role",
{"required": self.required_role.value, "actual": user.role.value},
)
return user
def require_role(required: Role) -> _RoleDependency:
return _RoleDependency(required)
The error-handler auth branch
hex-restapi-app's primary error_handler.py is the auth-less one. An app that declares auth uses the
authenticated variant instead: the UnauthorizedError import is added and the translator grows its
one isinstance branch, attaching the RFC-7235 challenge. Nothing else in the file changes, and
hex-restapi-app rule 3 caps it at at most one branch.
from myapp.domain.exceptions import MyappError, NotFoundError, UnauthorizedError, ValidationError
headers: dict[str, str] = {}
if isinstance(exc, UnauthorizedError):
headers["WWW-Authenticate"] = "Bearer"
return JSONResponse(status_code=status, content=body, headers=headers or None)
restapi/schemas/errors.py maps UnauthorizedError to 401 in STATUS_BY_ERROR, and ForbiddenError
to 403 once something raises it (hex-restapi-app).
The challenge carries the Bearer scheme alone, which is the load-bearing part (RFC 7235) and what
hex-test-restapi-auth asserts. A realm is optional and app-specific: an app that wants one reads it
from its settings — never a literal frozen into the template (rule 8).
401 says who are you — the credential was missing, malformed, expired or unverifiable, so the client
may retry with a better one, and RFC 7235 obliges the response to say how. 403 says I know who you
are and you may not — retrying with the same credential is pointless, and there is no challenge to
issue. Those are two different answers, not two spellings of one; exception-catalog owns both classes.
The route's auth dependency and codes
Read ROUTES.md before writing or changing any route in an app that declares auth — only this
file is loaded automatically. It is the half consulted every time a route is written: the decision
table for which dependency an operation takes, the _-vs-user binding rule and the stamp-from-the-identity rule,
how an authenticated route is derived from an auth-free one, and the coordinated
advertisement rule joining the chosen dependency to the codes the route declares.
The composition-root wiring
The verifier and its settings are two bindings in the composition root — an add-on a project that
declares auth merges into hex-wiring's base, each line into the provider class of the same name.
Placement follows hex-wiring's declaration order: settings first, then long-lived infrastructure — a verifier is process-lifetime
(stateless, parses its key once).
from dishka import Provider, Scope, provide
from myapp.domain.auth import ICanVerifyToken
from myapp.infrastructure.jwt import JwtSettings, PyJwtTokenVerifier
class SettingsProvider(Provider):
scope = Scope.APP
@provide
def jwt_settings(self) -> JwtSettings:
return JwtSettings()
class InfrastructureProvider(Provider):
scope = Scope.APP
jwt_verifier = provide(PyJwtTokenVerifier, provides=ICanVerifyToken)
ICanVerifyToken — the port, not the adapter class — is what get_current_user asks for and what
hex-test-restapi-auth substitutes, so the adapter can be swapped without touching either. Lifetimes,
ordering and the settings lifecycle follow hex-wiring.
Other bindings
- JWKS endpoint. The issuer publishes its key set rather than one key. Fetching and caching it by
kidis a key-set client the adapter is built on, injected like any client, since an adapter does not cache (hex-capability-adapter); the adapter selects the verifying key by the token'skid, never by itsalg. The port, the identity, the gate and the codes are unchanged. - Opaque token + introspection endpoint. The port,
CurrentUser,require_role, the dependency pair and the whole advertisement half are unchanged. What changes: the adapter does IO, so the capability method becomesasync(hex-domain-ports' async capability shape) and the provider is built on an HTTP client rather than a key; the adapter form ishex-capability-adapter's async HTTP-gateway one. A network call per request also makes a cache a real question — which the adapter may not answer itself —hex-capability-adapter's adapters-are-thin rule (no retries, no caching); it is a separate wrapper. - Session cookie.
HTTPBeareris replaced by reading a signed cookie, and the RFC-7235 branch goes away — a cookie scheme has noWWW-Authenticatechallenge, so a 401 carries no header. Everything else — the port, the identity, the role gate, the two dependencies, the code sets — is unchanged. - Gateway- or mTLS-authenticated. The gateway has already authenticated, so there is no verifier and
no port;
get_current_userbuildsCurrentUserfrom a trusted header or the peer certificate. The gate, the codes and the 401/403 split stand. The load-bearing extra rule: the app must be unreachable except through the gateway, or the trusted header is a forgery primitive. dependency-injectoras the wiring mechanism. The port, the adapter, the dependency pair and the codes are unchanged. What changes is two lines ofdependencies.py:get_current_usertakesrequest: Requestinstead of the injected parameter, drops@inject, and reaches the verifier by the binding's attribute name off the app state — which resolves untyped, so the result has to be narrowed with acastto keep the-> CurrentUsercontract.hex-wiring's mapping table has the rest.
Rules
- The entrypoint authenticates; nothing below it knows how. The caller identity crosses inward as
ordinary data on a command or query DTO — never a request object, a header, a token string or a
framework dependency.
hex-applicationowns the DTO field. - One name for credential rejection. Every missing, malformed, expired or unverifiable credential
raises the catalogue's single unauthorized class, and the challenge branch keys on that one class; a
second parallel class for the same case silently skips the challenge (
exception-catalog). - Identity is resolved once, at one place. A route never parses the authorization header, decodes a token, or constructs a verifier. The verifier reaches the dependency from the composition root, by its port type, like anything else.
- The gate is a declared dependency, not code in the route body. No hand-rolled rank comparison after the identity is bound. A rule more nuanced than a single role rank is a handler concern; the handler raises the forbidden class.
- The required rank is visible at the call site.
require_role(Role.X)is called inline at each route; do not memoize it at module level (_gate = require_role(Role.HIGHER)) — the role is the most important detail in a route review. - Two dependencies, and they are exhaustive: authenticate-only, and authenticate-plus-rank. Do not combine the authenticate-only form with a role check — use the rank form.
- The advertised codes match the chosen dependency. Authenticate-only advertises the
unauthenticated code; rank-gated advertises the unauthenticated and the forbidden code; no
dependency advertises neither. A code no route can produce is a lie in the published document
(
hex-restapi-endpoint). - A challenge, where the scheme defines one, carries the scheme and nothing else. The realm is app-specific: drive it from settings or omit it, and never freeze a literal realm in a template or a test. The challenge belongs to the unauthenticated response alone — a forbidden response has no challenge to issue, and a scheme that defines no challenge sends none at all.
- In an app that has auth, authentication is the default for a non-public route. A "trusted internal" route that skips auth is forbidden; internal-only access is enforced at the network or gateway layer. This does not manufacture auth on an app that has none.
- A rank ladder is the app's own — a rank-ordered enum with a rank-satisfaction method, whose members and their number belong to the app; a route template names the slot, never a member.
- Auth-derived values come from the resolved identity, never from the request. Which DTO fields
they are, and how a handler scopes by them, are
hex-application's. - The identity type is a domain type. The verifier returns it; the credential's own wire shape — a claims mapping, an introspection payload, a header set — never leaves the adapter, and no layer above it sees one.
Inlined typing / import rules
- No cast at the injection boundary. The verifier arrives as
FromDishka[ICanVerifyToken], which is a real annotation the checker follows, soget_current_userhonours its-> CurrentUsercontract with nocastand no# type: ignore. A cast here means something is being reached through an untyped attribute — fix the injection instead. Dependsfromfastapi;HTTPAuthorizationCredentials,HTTPBearerfromfastapi.security.- Domain imports absolute (
from myapp.domain.auth import CurrentUser). The verifier adapter never imports the protocol it satisfies (hex-architecturerule 7). - Full annotations on every dependency, the callable class's
__call__, and the verifier's methods. Nofrom __future__ import annotations(python-style).
Package wiring
domain/auth/ is a subdomain package — its __init__.py re-exports CurrentUser and
ICanVerifyToken (and Role in a rank app), which every from myapp.domain.auth import ... above resolves against — and
infrastructure/jwt/ an infrastructure one; both follow python-packaging, with the layer placement
in hex-architecture. restapi/dependencies.py sits in the entrypoint package hex-restapi-app creates, under that package's entrypoint carve-out.
Hard stops
- The app declares no auth (every endpoint anonymous, no token-verifier capability) → stop, produce none
of this; there is no
dependencies.py, nodomain/auth/, noUnauthorizedError, and every route is auth-free by construction. domain/exceptions.pyhas noUnauthorizedError→ stop, useexception-catalogfirst;ForbiddenErroris added with the first thing that raises it — the role gate, or a handler's finer check.- The translator is asked to branch on more than the unauthorized class → stop, use
hex-restapi-app(rule 3). - The verifier is asked to log, retry or cache → stop, use
hex-capability-adapter; an adapter is thin. - Asked for authorization finer than a single role rank — per-row ownership, a policy matrix, a third
kind of auth dependency → stop, use
hex-application; the handler raisesForbiddenError.