security.auth_core

Parsestr | AuthSpec | None into a canonical AuthSpec or None.

EXACT back-compat with the historicalenforce_route_meta_authstring semantics — this preserves the runtime meaning of every existing value:

• None / "" / "none" / "optional" -> None(open, no gate)
• "required" -> AuthSpec()(authn-only, no permissions/policy)
• any other non-empty strings-> AuthSpec(permissions=(s,))(single required permission)
• an existingAuthSpecpasses through unchanged.

AnAuthSpecalways requires authentication, so the open case is the only one that returnsNone; there is no requiredflag to set.

Detect whether the request is from an API client (not a browser).

Heuristic:

• HasAuthorizationheader -> API client
• Acceptprefers JSON over HTML -> API client
• Otherwise -> browser

Build a login redirect URL with anextparameter.

Build the content-negotiated unauthenticated response.

Browser -> 302 redirect to the login URL (withnext); API -> 401. Emitsauth.require.unauthenticatedfor the API/no-login-url branches, matching historical behavior on both paths (the redirect branch does not emit — preserved verbatim).

Return whetherrequired is in held, comparing in constant time.

A plainrequired in heldset membership leaks (via early-exit string compare) how many leading characters of a scope matched. Webhook/cron scope tokens can be secret-bearing, so the issue's success criterion is a constant-time compare — route every scope-name equality through compare_digest() (the same primitive csrf.py/ passwords.py use), never ==. The iteration count still varies with len(held), but each individual scope comparison is constant-time.

Authenticate-or-deny the resolveduser against spec.

This is the single shared gate. It performs, in order:

1. Authentication — ifuseris not authenticated, raise the content-negotiated response (302 -> login for browsers, 401 for APIs).
2. Permission check — whenspec.permissionsis non-empty, the user must implement the permissions protocol (else 403) and satisfy the set: mode="all"requires every permission (subset); mode="any"requires a non-empty intersection.
3. Policy — whenspec.policyis set, resolve it via policy_resolver and call policy(user, request); deny (403) only on a falsy result from the RESOLVED callable (a real denial).
4. Scope check (machine auth) — whenspec.scopesis non-empty, the resolved client must implement the scopes protocol (ClientWithScopes, else 403) and satisfy the scope set underspec.mode. This is the machine-token axis, independent of permissions: a token-resolved client with the scope but no permissions passes, while a human user with permissions but not the scope fails. Scope-equality usescompare_digest() (constant-time). Scope enforcement is implicitly off — a spec with no scopes runs no scope step, so existing verify_tokenusers are never newly denied (no separate enable flag). Denial emits authz.scope.denied with details={"missing": sorted([...])}.

An unresolved policy NAME (nopolicy_resolverwired, or the resolver returnsNone) is a MISCONFIGURATION, not an auth denial: it raises LookupError-> a 500 at request time, consistent with the page wrapper's _resolve_policy (app/registry.py). It is NOT a 403 and emits NO authz.policy.deniedevent. This 500 is only a runtime backstop — the real guard is theauth_specstartup contract check, which ERRORs on any referencedAuthSpec.policythat is not registered.

Audit events use the ONE canonical payload (seeAGENTS.md); the permission/policy warnings are logged viachirp.security.