Contract Category Reference

app.check()validates your hypermedia wiring at startup and reports every problem as a(category, severity, message)triple. The category is the stable handle you target in CI policy; the message names the exact route, template, block, selector, registration, config field, middleware, or import string to fix. This page lists every category, its default severity, and what to change.

New here? Start with how to read and diagnose check output and how app.check runs at startup.

The two policy levers

chirp check myapp:app --warnings-as-errorspromotes warnings at the CLI boundary. For app-specific policy, override a category before running checks:

from chirp.contracts.types import Severity

app.override_contract_severity("dead", Severity.WARNING)
app.override_contract_severity("page_handlers", Severity.WARNING)

Routing And Pages

Templates And Blocks

HTMX And Swaps

SSE And Reactive

Forms, Commands, And Safety

chirp check --deploy: production-posture preflight

The env-aware categories above (secret_key, allowed_hosts, security_stack, cookie_secure, hsts, password_extra, passkeys, auth_middleware, auth_spec, access_grant_scalar_loop, settings_spec, sse_auth_gate, sse_context, csp_nonce, chirpui_csp, deploy_debug, deploy_metrics, deploy_health, deploy_sentry) pick their severity from config.env. In development most are silent or WARNING, so a dev app passesapp.check()while still carrying production-blocking misconfigurations.chirp check myapp:app --deployanswers "would this pass in production?" without changing your config: it runs those rules against a throwaway production-posture view of the config and treats warnings as errors (--deploy implies --warnings-as-errors). It is tighten-only — only severities rise, so a genuinely deploy-ready app still passes — and it never mutates the running app. Programmatically this isapp.check(deploy=True). Use it as a CI deploy gate.

security_stack: canonical reference

security_stackis the canonical owner of the mutating route definition and the secure-by-default presence check. Severity is env-aware: missing CSRFMiddleware or SessionMiddlewareis ERROR in production, WARNING in staging, silent in development; missingSecurityHeadersMiddlewareis always WARNING (env-independent). Chirp force-injects no security middleware — the chirp new scaffolds (including --minimal) wire SessionMiddleware→ CSRFMiddleware → SecurityHeadersMiddlewarefor you, so generated apps pass out of the box.csrf_session checks the ordering of that stack; csrf_form checks individual template<form> tags; security_stackis the route-level presence check.

Env-severity matrix. Two distinct severity tracks:

cookie_secure: Secure session cookies

ASecure cookie is only ever sent over HTTPS. A session cookie without Secure — whether it carries the session data (CookieSessionStore) or just the session id (RedisSessionStore) — can be sniffed over a plaintext path and replayed to hijack the session. The check is store-agnostic: both stores emit a Set-Cookie, so it fires on the effective Secureflag, never on the store type.

It is a no-op when noSessionMiddleware is registered — security_stackalready owns the presence check. When aSessionMiddlewareis present, the check reads its effectiveSecure flag (SessionMiddleware.secure, resolved through the same resolve_cookie_securethe runtime uses, so the check and runtime never disagree). The blessed defaultSessionConfig(secure="auto") resolves to Secure in production/staging, so a default-config app passes.

Two severity tracks:

Thesamesite="none" + not-Securecase is env-independent ERROR because browsers silently drop aSameSite=None cookie that is not Secure— the session simply breaks in every environment, including development. That is a correctness footgun, not a hardening preference, so it is reported regardless of env.

Fix: keepSessionConfig(secure="auto")(the default) and serve over HTTPS in production/staging, or setSessionConfig(secure=True)explicitly. For the SameSite=None case, either add Secure or use samesite="lax"/"strict". Severity is env-aware (silent dev / WARNING staging / ERROR prod) for the hardening track and escalates underchirp check --deploy.

hsts: HTTP Strict Transport Security nudge

WARNING (never ERROR) when an app declaresenv="production", has an auth/mutating surface (sameis_mutating_route definition security_stackowns), and leaves strict_transport_security unset both on AppConfigand on any SecurityHeadersMiddleware. Without HSTS a first request over plain HTTP can be downgraded/MITM'd before the redirect to HTTPS.

This is deliberately a WARNING + docs nudge only — Chirp does not auto-emit an HSTS header, andstrict_transport_security=Noneis not overloaded to mean "auto";Nonestays "off". An HSTS header is an irreversible multi-year browser pin: emitting it becauseenvsays production — while the app may actually be reached over plain HTTP behind a misconfigured proxy — is worse than the gap. So the contract surfaces the gap and leaves the irreversible decision to you.

Fix: once you have confirmed the app is only ever reached over HTTPS, set AppConfig(strict_transport_security="max-age=63072000; includeSubDomains")(or add aSecurityHeadersMiddlewareconfigured with it). Either source clears the warning. It is silent in development and staging — only the declared production posture is nudged — and surfaces underchirp check --deploy.

password_extra: argon2 in production

WARNING (never ERROR) when an app has a login/mutating surface (the same is_mutating_route definition security_stack owns) and argon2-cffiis not importable — so password hashing falls back to stdlib scrypt. scrypt is a correct, always-available fallback (no hash is ever rejected andverify_password auto-detects the algorithm from the PHC prefix), but argon2id is the recommended algorithm for new production deployments.

This is a posture advisory, never an ERROR: there is no correctness gap to fail loud on, and existing scrypt hashes upgrade to argon2 on the next successful login viaverify_and_upgrade()once the extra is installed. Severity is env-aware — silent in development (and the scrypt-only base CI environment), WARNING in staging/production — so dev apps and shipped examples stay clean, and it escalates underchirp check --deploy. argon2 availability is read via the same_has_argon2()predicate the runtime uses to pick the hashing algorithm, so the check and the runtime never disagree.

Fix:pip install chirp[auth] (pulls in argon2-cffi). New hashes then use argon2id; existing scrypt hashes re-derive to argon2 the next time each user logs in if you wireverify_and_upgrade()(see Auth Hardening).

passkeys: WebAuthn ceremony posture

Fires only whenAppConfig(passkeys=True). Two distinct tracks:

• webauthnnot installed → ERROR, env-independent. Passkeys have no stdlib fallback (unlikepassword_extra's scrypt path), so without the webauthn package every ceremony raisesConfigurationErrorat runtime in every environment. This is a broken config, not a hardening gap, so it is reported regardless ofenv — like the samesite="none"cookie-drop ERROR in cookie_secure. Availability is read via the same _has_webauthn()find-spec probe the runtime uses, so the check and runtime never disagree.
• CookieSessionStorefor the challenge → WARNING, env-aware (silent dev / WARNING staging+production). The single-use WebAuthn challenge lives in the session between the begin and finish ceremonies, and the cookie store signs the entire session — including the ~86-char base64url challenge — into the client cookie, whereasRedisSessionStore strips __-prefixed keys from durable storage. The challenge is popped on finish, but abandoned begin-flows carry it until session timeout. Advisory only (mirrorspassword_extra); escalates under chirp check --deploy.

What this rule deliberately does not re-check, to stay non-redundant: security_stack already requires SessionMiddleware/CSRFMiddlewareon the mutating finish endpoints;PasskeyConfig.__post_init__validates the rp_id-is-a-registrable-suffix-of-origin invariant at construction; and the HTTPS/secure-context posture is covered bycookie_secure (a Securecookie implies HTTPS).

Fix:pip install chirp[passkeys] (pulls in webauthn, which pins cryptography). For passkey-heavy traffic on the cookie store, switch to RedisSessionStore or set a short SessionConfig(absolute_timeout_seconds=...).

auth_middleware: auth-declaring routes need AuthMiddleware

A route can declare that it needs authentication two ways, and both call get_user() — which raises LookupError→ a 500 at request time when AuthMiddlewareis absent from the stack:

• RouteMeta.auth on a filesystem page (_meta.py): None / "none"/ "optional" are open; "required"requires an authenticated user; any other non-empty string is treated as a single required permission.
• @login_required / @requires on an @app.routehandler. These decorators carry a static_chirp_requires_authmarker on the handler the router stores, so the check can prove the route is auth-gated without executing it.

When any auth-declaring route exists and noAuthMiddlewareis registered, this fires, naming a concrete offending route and the fix (register AuthMiddleware after SessionMiddleware).

Env-severity matrix. Mirrorssecurity_stack— the dev 500 surfaces the gap locally, so a standing dev WARNING would be noise:

Dynamicmeta() pages are a static blind spot. A page whose _meta.py definesmeta()resolves its auth value at runtime, so its requirement is invisible to a static check. Those pages are never false-ERRORed; instead, whenAuthMiddlewareis absent and such pages exist, a single INFO notes that auth wiring could not be statically verified — wireAuthMiddlewareif any dynamic-meta page is gated. This mirrors howroute_contract's section-coverage check handles meta providers.

Fix: registerAuthMiddleware after SessionMiddleware (app.add_middleware(AuthMiddleware(AuthConfig(load_user=...)))). It is silent in development and escalates underchirp check --deploy.

auth_spec: declared permissions/policies that silently fail

RouteMeta.auth treats any non-reserved string (and every AuthSpec.permissions entry) as a required permission, and anAuthSpec.policyas a named policy resolved against the app policy registry. A wrong permission silently403s; an unresolved policy name fails loud (500— a misconfiguration, not an auth denial) — both with no other startup signal. This check has two modes.

Registry-backed (precise). When you declare permissions/policies during setup:

app.register_permission("admin")
app.register_permission("editor")
app.register_policy("is_owner", lambda user, request: ...)

every RouteMeta.authpermission not in the permission registry is an ERROR, and everyAuthSpec.policynot in the policy registry is an ERROR. The registry is the source of truth, so even a plausible-looking"admni"typo is caught.

Permissions and policies are checked asymmetrically. Permission validation is opt-in: it only runs when a permission registry is declared (otherwise the heuristic below applies). Policy validation is always on: a referenced AuthSpec.policyname that is not registered is always an ERROR — even with no policy registered at all — because an unregistered policy name unconditionally 500s at request time, so there is no false-positive risk.

Heuristic-only (no permission registry). With no permission registry declared, permission validation falls back to a high-signal reserved-token-confusion heuristic. A near-miss of a reserved token —"Required", "REQUIRED", " required ", "None", "Optional", or a tight misspelling like "requied"— silently becomes a permission named that exact string and 403s forever instead of gating as intended. Empty-after-strip / whitespace-only auth (" ") is the same bug. It flags exactly:

• a case/whitespace variant of a reserved token ("Required", " required ", "None", "Optional");
• a tight misspelling of"required" (edit distance ≤ 2, e.g. "requied"); and
• empty-after-strip / whitespace-only.

Plausible permission names ("admin", "editor", "billing.read") are not flagged in heuristic mode — without a registry Chirp cannot know which strings are real permissions, and false positives erode trust. Declare a permission registry to validate them precisely.

Machine-token scopes (AuthSpec.scopes). The machine-auth axis — webhook / cron / provisioning endpoints gate on a token-resolved client's scopes independently of human permissions — folds into this sameauth_speccategory (no separate category). Scope validation is opt-in like permissions: declare scopes withapp.register_scope("webhook:write") and every AuthSpec.scopes entry not in the registry becomes an env-aware ERROR. With no scope registry, scopes are free strings and are not heuristically flagged (a scope is an arbitrary machine token, so a plausible-name heuristic has no signal).

Severity is env-aware (silent dev / WARNING staging / ERROR prod), same as auth_middleware, and escalates under chirp check --deploy. Dynamic meta() pages are skipped (their auth value is not statically known).

Fix: declare the permission withapp.register_permission()(or fix the typo), register the policy withapp.register_policy(), declare the scope with app.register_scope(), or use the exact reserved token ("required" / "none"/ "optional").

sse_auth_gate / sse_context: reading the user inside an SSE generator

get_request(), get_user() / current_user(), get_csrf_token(), and g work inside anEventStreamgenerator — the request-scoped context is captured at connect time and re-established for the lifetime of the stream. Two checks guard the two ways this can surprise you.

sse_auth_gate — the user is AnonymousUser without AuthMiddleware. An EventStream generator that calls get_user() / current_user()resolves the connect-time-captured user, but only whenAuthMiddlewareis wired. Without it, the captured user isAnonymousUserfor the entire stream, so an auth-sensitive feed silently serves the anonymous view to everyone — no error, no startup signal. Env-aware, mirroringauth_middleware:

sse_context— the SSE user identity is pinned at connect time. This is a post-fix semantic nudge, never an ERROR — the pattern WORKS. When a generator reads the user inside a long-lived loop (while / async for / for), the identity is fixed for the connection's lifetime: a mid-stream logout or permission revoke is not reflected until the client reconnects. It fires as a WARNINGin staging/production (silent in development) so you can decide whether the feed is auth-sensitive enough to re-check authorization per event (or close the stream on revoke). A short-lived top-level user read (outside any loop) is not nudged — it resolves once and the stream ends.

These rules do not fire on the shippedchat / kanban / dashboard/ lucky_catSSE examples: their generators read global state (the message bus, the task store, the market feed), never the request user.

Data

Debug, Extensions, Accessibility, And Plugins