contracts.rules_auth_meta

Levenshtein distance betweena and b(insert/delete/substitute).

Small DP — auth values are tiny strings, so the O(len(a)*len(b)) table is trivially cheap and runs only on the handful of declared, non-reserved auth values an app actually ships.

True whenvalue(already lowercased+stripped, non-reserved) is a tight near-miss of"required"— a likely typo (e.g. 'requied' -> 'required').

Scoped to"required"ONLY, the one reserved token long and specific enough to attract typos. The short open tokens (none/optional) are deliberately NOT in the edit-distance neighbourhood: their distance-2 ball contains real words (node/note near none), which would be false positives — case/whitespace variants of those (None/Optional) are still caught by the variant branch. Bounded by_TYPO_EDIT_DISTANCE so realistic permission names (admin/editor/moderatorare all distance >= 5 fromrequired) are never flagged.

True when a staticRouteMeta.authdeclares no gate.

Mirrorsnormalize_auth_spec(): Noneand the falsy/empty string case are open, as are the exact reserved open tokens "none" / "optional". A bare "required", any other non-empty string, OR a structuredAuthSpec DECLARES auth (an AuthSpecalways gates).

True when a route's handler carries the static auth-gate marker.

The marker (_AUTH_MARKER) is set by @login_required / @requires on the OUTERMOST wrapper the router stores — NOT the inner handler — so it must be read offroute.handler(and, for mounted pages, route.page_source_handler) directly, before inspect.unwrapwould drop to the inner handler and lose it. We additionally walk the unwrap chain so a marker that landed on an inner layer (e.g. a stacked decorator arrangement) is still detected. This mirrors howrules_nojs_floorresolves the user's real handler viapage_source_handler then inspect.unwrap.

Flag auth-declaring routes whenAuthMiddlewareis absent.

A route "declares auth" when EITHER:

• its staticRouteMeta.auth(from route_metas, keyed by URL path) is non-open — notNone / "none" / "optional"; or
• its handler carries the_chirp_requires_authmarker set by @login_required / @requires (see _handler_declares_auth()).

If ANY auth-declaring route exists and noAuthMiddlewareis registered, emitauth_middlewarenaming a concrete offending route + the fix. WithoutAuthMiddleware, get_user() raises LookupError→ 500 at request time. Severity is env-aware: ERROR in production, WARNING in staging, silent in development (the dev 500 surfaces it locally — matching security_stack; no standing dev WARNING).

Dynamicmeta()pages (meta_provider_paths) are a static blind spot: a page whose_meta.py defines meta()registers a meta provider with staticmeta left None, so its auth value is invisible here. Those paths are excluded from the ERROR/WARNING (no false positive) and, when AuthMiddlewareis absent and such pages exist, get a single INFO noting auth wiring could not be statically verified for them — mirroring how check_section_coverage handles meta_provider_paths.

Return the declared permission name(s) for anauthvalue.

• a bare non-openstr-> that single permission (the legacy shape);
• anAuthSpec -> its permissionstuple (canonical, post-discovery);
• anything open / authn-only ->().

Mirrorsnormalize_auth_spec(): requiredand the open tokens declare no permission, so they are never inspected here.

Return the declared machine-token scope name(s) for anauthvalue.

Only a structuredAuthSpec carries scopes — a bare string auth never produces scopes (it normalizes to a permission). The machine-auth counterpart to_permission_names().

True when a permission name is almost certainly a botched reserved token.

The high-signal heuristic used when NO permission registry is declared:

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

Plausible permission names ("admin", "billing.read") are NOT flagged.

Flag declaredRouteMeta.authpermissions/policies/scopes that fail silently.

A non-reservedauth string (or an AuthSpec.permissionsentry) is a required PERMISSION; anAuthSpec.policyis a NAME resolved against the app policy registry; anAuthSpec.scopesentry is a machine-token SCOPE. All 403 (permission/scope) / 500 (unresolved policy) at request time when wrong, with no other startup signal.

PERMISSIONS, POLICIES, and SCOPES are validated by design:

• Permissions are opt-in. They are only validated against permission_registry when that registry is non-empty (a declared app.register_permission); with no permission registry the high-signal reserved-token-confusion heuristic runs instead ("Required"/ " required " / "requied"/ whitespace-only). Plausible permission names ("admin") are never flagged without a registry — false positives erode trust.
• Policies always resolve. A referencedAuthSpec.policyNAME not in policy_registry is ALWAYS an ERROR (env-aware), INCLUDING when policy_registry is empty. AnAuthSpec(policy="x")with no register_policy("x")is unconditionally a bug — it raises LookupError-> 500 at request time, so there is no false-positive risk.
• Scopes are opt-in (machine-auth axis). They are validated against scope_registry only when that registry is non-empty (a declared app.register_scope); an AuthSpec.scopesentry not in the declared set is an env-aware ERROR. With no scope registry scopes are free strings — there is no typo heuristic (a scope is an arbitrary machine token, so a plausible-name heuristic has no signal). This folds into the EXISTING auth_speccategory — no new category, no severity change.

Env-aware via config.env (ERROR production / WARNING staging / silent development), same asauth_middleware. Dynamic meta()pages (meta_provider_paths) are skipped — their auth value is not in route_metas.

Build the reserved-token-confusionauth_specissue for a permission.