Sentinel is production-hardened with defense-in-depth across transport, authentication, token lifecycle, and input validation. This page documents the full security architecture.

Middleware is applied in a specific order. The outermost layer processes requests first:

Request
  |
  v
MaxBodySizeMiddleware        -- reject bodies > 10 MB
  |
  v
GlobalRateLimitMiddleware    -- 30 req/min per IP
  |
  v
SecurityHeadersMiddleware    -- security response headers + HSTS
  |
  v
SessionMiddleware            -- encrypted cookie for OAuth2 state
  |
  v
TrustedHostMiddleware        -- Host header validation (production)
  |
  v
DynamicCORSMiddleware        -- cross-origin request policy
  |
  v
Rate Limiting (slowapi)      -- per-endpoint throttling
  |
  v
Application Routes

Source: service/src/main.py

Every response includes 11 security headers set by SecurityHeadersMiddleware:

Sensitive paths (/auth, /admin, /users) additionally receive Cache-Control: no-store and Pragma: no-cache.

When COOKIE_SECURE=true, HSTS is enabled:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

This enforces HTTPS for two years and is eligible for the HSTS preload list.

Source: service/src/middleware/security_headers.py

Four tiers, applied by endpoint sensitivity:

Service keys are database-managed (service_apps table), not environment variables. Each key is stored as a SHA-256 hash with a display prefix (e.g., sk_abc1****). Keys are validated by service_app_service.validate_key() with Redis caching.

All tokens use RS256 (RSA + SHA-256). The private key signs tokens; any service with the public key can verify without contacting Sentinel.

openssl genrsa -out keys/private.pem 2048
openssl rsa -in keys/private.pem -pubout -out keys/public.pem

The public key is also available at /.well-known/jwks.json.

Every token carries a kid (RFC-7638 thumbprint) header, and JWKS publishes the current key plus any retired keys (JWT_PREVIOUS_PUBLIC_KEY_PATHS). Verifiers select the key by kid, so a new key can sign while old tokens still verify — graceful, zero-downtime rotation. SDK middlewares refetch JWKS on an unknown kid. See the runbook: deployment/key-rotation.md.

Tokens carry a type claim that prevents cross-use:

Every token includes a jti (UUID). This enables per-token revocation via the Redis denylist without invalidating all tokens for a user.

Modeled after Auth0's refresh rotation:

1. Issuance -- on authentication, the service issues an access + refresh token pair. The refresh token's jti is stored in Redis with a family_id.
2. Rotation -- POST /auth/refresh atomically consumes the token (GETDEL), issues a new pair in the same family.
3. Reuse detection -- a consumed token presented again signals theft. The entire family is revoked.
4. Family revocation -- on theft detection or user deactivation, all jti entries in the family set are deleted.

Redis keys:

After OAuth callback, Sentinel issues a short-lived authorization code (not raw user IDs in redirects):

1. Frontend sends code_challenge + code_challenge_method=S256 on GET /auth/login/{provider}
2. Callback stores the code in Redis with a 5-minute TTL alongside the code_challenge
3. GET /auth/workspaces?code=X peeks at the code (non-destructive)
4. POST /auth/token verifies SHA256(code_verifier) == code_challenge, then consumes the code via GETDEL

Redis key: ac:{code} -- JSON {user_id, provider, code_challenge, code_challenge_method}, 5-minute TTL.

On logout, the jti is added to a Redis denylist with TTL equal to the token's remaining lifetime. Every authenticated request checks the denylist. Entries self-expire when the token would have expired anyway.

Redis key: bl:{jti} -- value "1", TTL = remaining seconds.

POST /auth/logout performs two actions:

1. Blacklists the access token (jti to denylist)
2. Revokes all refresh token families for the user (revoke_all_user_tokens)

This prevents an attacker with a captured refresh token from obtaining new access tokens after the user logs out.

Admin cookies are configured for defense in depth:

Two layers:

1. SameSite=Strict -- the admin_token cookie is never sent on cross-site requests.
2. Custom header -- all mutation requests (POST/PATCH/PUT/DELETE) to /admin/* require X-Requested-With: XMLHttpRequest. This header cannot be set by cross-origin forms, and CORS preflight blocks cross-origin JavaScript from adding it.

SessionMiddleware provides encrypted session cookies used exclusively during OAuth2 flows. The session stores state and PKCE code_verifier between redirect and callback. Sessions expire after 10 minutes (max_age=600).

# Generate a session secret (required for production)
python -c "import secrets; print(secrets.token_urlsafe(32))"

Two layers:

1. Global -- GlobalRateLimitMiddleware enforces 30 requests/minute per IP across all endpoints (except /health). Uses a Redis-backed atomic counter (Lua INCR+EXPIRE).
2. Per-endpoint -- slowapi applies stricter limits on sensitive endpoints.

When BEHIND_PROXY=true, the rate limiter reads client IP from X-Forwarded-For instead of the TCP connection address.

Exceeding either limit returns 429 Too Many Requests with a Retry-After header.

PKCE prevents authorization code interception. Sentinel uses S256 where supported:

PKCE is configured at the Authlib client registration level. Authlib generates code_verifier and code_challenge automatically.

Applications must be registered as client apps before using Sentinel. GET /auth/login/{provider} requires a client_id query parameter naming the ClientApp initiating the flow. Sentinel validates that the supplied redirect_uri is listed on that specific app's redirect_uris — not any active app. The client_id is stored in the session and re-verified on callback before an auth code is issued.

This prevents authorization-code interception where an attacker crafted a login URL with their own code_challenge and another app's redirect_uri, then redeemed the resulting code against their own verifier. Without client_id binding, a single compromised or attacker-controllable redirect URI anywhere in the allowlist would have been enough; with it, the (client_id, redirect_uri) pair must match.

Redirect URIs (and ServiceApp origins) are parsed with urlparse and must have:

• Scheme http or https
• Non-empty host
• No @ userinfo, no fragment, no query (URIs); no path/query/fragment (origins)
• No wildcards, no "null", no malformed round-trip

Stricter than a prefix check — rejects values like https://good@evil.com/cb or https:// at write time.

All OAuth2 flows use state (managed by Authlib via SessionMiddleware) to prevent CSRF during authorization code exchange.

DynamicCORSMiddleware combines two origin sources:

1. Static -- from CORS_ORIGINS environment variable
2. Dynamic -- derived from client_apps.redirect_uris in the database

Policy: credentials enabled, methods GET/POST/PUT/PATCH/DELETE/OPTIONS, headers Content-Type, Authorization, X-Service-Key. No wildcards in production.

AuthZ mode lets client apps authenticate users directly with their IdP and hand the resulting token to Sentinel, which issues a short-lived authorization JWT. Several defences ensure the IdP remains the sole authentication authority.

Both the Python and Next.js AuthZ middlewares require you to configure:

• idp_audience — the OAuth client_id this app is registered as. The IdP token's aud must match.
• idp_issuer — optional but strongly recommended; the IdP token's iss must match.

Without aud validation, any token signed by the IdP for any OAuth client would authenticate — including one minted for an attacker's app. Sentinel's server-side /authz/resolve has always enforced audience; the middleware change brings client verification to parity.

The authz JWT carries three binding claims that the middleware enforces on every request:

Server-side dependencies (get_user_for_service_call, get_current_user_flexible) enforce the same svc binding when authz tokens are accepted alongside a service key.

POST /authz/resolve accepts an optional nonce field. When provided, the IdP token's nonce claim must match. Browsers generate a nonce at login-start and echo it here — a leaked IdP token cannot be replayed without the matching nonce.

GET /authz/idp/github/login takes a caller-supplied redirect_uri. Sentinel validates the URI's origin (scheme + host + port) against ServiceApp.allowed_origins — attackers cannot point the GitHub proxy at their own domain to exfiltrate the access token. The allowlist is re-checked on callback.

find_or_create_user keys identity strictly on (provider, provider_user_id) and never auto-links across providers by email. A new IdP login whose email matches a user who already has a SocialAccount under a different provider is rejected with 409 CrossProviderEmailConflict — attackers with a weaker IdP cannot take over an account created under a stronger one. An email match against an admin-pre-provisioned account that has no SocialAccount yet is the intended first sign-in and is linked to that account, so pre-provisioning works without locking the user out.

Authz tokens carry jti and sub. On Sentinel's own endpoints — the get_user_for_service_call and get_current_user_flexible dependencies — they go through the same revocation checks as access tokens on every request:

• jti on the denylist → 401
• sub marked deactivated → 401

So admin-driven deactivation takes effect immediately for any request that reaches Sentinel.

SDK edge (important). The AuthzMiddleware shipped in the SDK and installed via sentinel.protect(app) validates tokens offline — signature, audience, expiry, and the idp_sub/svc bindings — and deliberately does not call back to Sentinel to consult the denylist or deactivation flag (no network round-trip per request). The consequence: at an SDK-protected downstream service, a deactivated user's already-issued authz token stays accepted until it expires naturally.

Authz tokens are not enrolled in a refresh family, so the deactivation flag is their only revocation lever — and it is consulted only on Sentinel's own endpoints. Bound the exposure by keeping AUTHZ_TOKEN_EXPIRE_MINUTES short (default 5). For revocation-sensitive operations at a downstream service, route the decision through Sentinel (e.g. a PermissionClient / RoleClient check) rather than relying on the offline middleware alone. (A future opt-in revocation check in the middleware could close this at the cost of a per-request network call.)

The JS SDK's persistent store keeps the short-lived authz token in localStorage but not the long-lived IdP token — that stays in instance memory only. After a page reload the SDK has no IdP token, so getAuthState() reports needs_reauth (isAuthenticated is false) and the user re-authenticates via the IdP — either with one click, or seamlessly via silentLogin() (prompt=none). This limits the XSS blast radius: an attacker reading localStorage gets a token that expires in minutes, not an IdP token that continues to mint new authz tokens for the next hour. The surviving authz token is not independently usable — the backend binds it to a freshly-signed IdP token (idp_sub must match), which is never persisted.

SentinelAuthz.handleCallback() fails closed if sessionStorage does not contain a nonce from a login this tab initiated. This blocks login-CSRF where an attacker links a victim to /auth/callback#id_token=<attacker_token> to hijack the session.

require_admin re-checks users.is_active and users.is_admin against the database on every request. Flipping an admin's flag takes effect on the next request, not only after the cookie expires.

POST /authz/resolve differentiates two trust levels:

• Discovery (no workspace_id, returns the user's workspace list) — accepts either X-Service-Key or a registered Origin header. No credential issued, low sensitivity.
• Minting (with workspace_id, returns a signed authz JWT) — requires X-Service-Key. Origin-authenticated callers are rejected with 403. Credential issuance is a server-to-server trust step.

Browsers therefore cannot call /authz/resolve to mint tokens. The SentinelAuthz SDK routes minting through a mintEndpoint on the downstream app's backend, which holds the service key. This closes the "XSS-window extension" attack where an attacker with a fleeting XSS could keep re-minting authz tokens for the IdP token's full TTL (~1 hour for Google). Post-fix, an XSS is bounded to replaying the one authz token already in memory (5-min TTL).

All request bodies are validated with Pydantic models. Invalid input is rejected with 422 before reaching business logic. This covers type checking, UUID format validation, enum constraints, and required/optional field enforcement.

MaxBodySizeMiddleware rejects requests exceeding 10 MB (413 Request Entity Too Large). It checks both Content-Length headers and actual streamed bytes to catch chunked uploads. CSV import endpoints enforce a stricter 5 MB limit at the application level.

RBAC action names must match ^[a-z][a-z0-9_.:-]*$, namespaced by service_name.

When DEBUG=false, the service refuses to start if any check fails:

Redis TLS and certificate verification are checked separately and logged as warnings (not blocking).

In development (DEBUG=true), all checks are logged as warnings instead.

When ALLOWED_HOSTS resolves to anything other than *, TrustedHostMiddleware validates the Host header on every request. This prevents Host header injection attacks used in cache poisoning.

If ALLOWED_HOSTS is empty, hostnames are derived from BASE_URL and ADMIN_URL.

All SDK clients (Python and JavaScript) log a warning when initialized with a plain http:// URL not pointing to localhost. This catches accidental production deployments without HTTPS.

• SESSION_SECRET_KEY set to a cryptographically random value
• COOKIE_SECURE=true and service is behind TLS
• DEBUG=false
• BEHIND_PROXY=true if behind a reverse proxy
• ALLOWED_HOSTS set to actual domain(s)
• CORS_ORIGINS lists only your frontend origin(s)
• RS256 key pair generated, private key chmod 600
• At least one service app registered via admin panel
• PostgreSQL uses SSL (?ssl=require in DATABASE_URL)
• Redis uses TLS (rediss://), has a strong password, not publicly exposed
• REDIS_TLS_VERIFY=required with CA cert configured
• ADMIN_EMAILS set for auto-promotion
• TLS certs generated for Postgres and Redis (keys/tls/)
• Reverse proxy handles TLS termination and sets X-Forwarded-For
• Startup validation passes with DEBUG=false