Module principal_gate 

Route-layer authentication for the gateway’s configuration and onboarding surfaces.

Structural enforcement: the middleware is attached via route_layer on the route group, so a handler added to the group cannot forget the check (the per-handler require_auth convention this replaces was enforced only by reviewer vigilance).

The layer also consumes the shared principal model (RFC 7141): a paired native bearer resolves to the shared operator exactly as before, while a bearer presented with the X-ZeroClaw-Auth-Provider header naming an oidc.<alias> provider is verified by that provider and resolved to a scoped principal whose Config grants gate the request. Provider selection is explicit, mirroring the RPC handshake’s auth_provider field: the named provider’s denial is authoritative, and there is no fallback between providers.

Grants are enforced in two places. The route layer applies a coarse floor per HTTP method (a read needs Read; anything else needs some mutating verb) so a read-only principal never reaches a mutating handler. Each mutating handler then authorizes its complete write set before its first side effect: every config path it will persist, classified by effect (Create for a path it brings into being, Delete for one it removes, Update otherwise) and matched against the principal’s config path selectors, with the persist boundary refusing anything the handler did not authorize (ConfigWriteAuthorization). That handler check runs under the config write lock against the grants the principal holds then, not the ones stamped at admission, so a revocation, expiry or unpairing that lands while the request body arrives or the lock is awaited binds the write.

Policy itself moves only at that persist boundary: the handler that writes a configuration publishes the policy compiled from it as the next accepted revision, and requests are verified and resolved against the accepted snapshot as it stands. Nothing on the request path compiles policy, so a request that read the configuration before a concurrent persist can never reinstall the older policy over the newer one.

Structs

ConfigWriteAuthorization

Proof that a mutation’s complete write set was authorized before its first side effect. The persist boundary requires one and re-checks that nothing outside the authorized set is about to be written, then publishes the policy of what it wrote through the admitting authority.

ConfigWriteSet

One config mutation’s complete write set: every dotted path the mutation persists, each with the verb its effect requires.

GatewayInboundAuth

The gateway’s inbound-auth authority: the provider registry and principal resolver the RPC layer uses.

RequestAuth

What the route layer hands every admitted request, for the handlers that mutate configuration: the principal the request was authenticated as (None in the open posture, where the transport is trusted exactly as before this layer existed) and the authority whose accepted policy admitted it, so the persist boundary can publish the policy of the configuration it writes.

WriteDenied

A refused config write: the response the handler returns in place of the mutation. A 403 carries which path or grant fell short; a 401 means the credential that admitted the request is no longer live.

Constants

AUTH_PROVIDER_HEADER

Header naming the auth provider to verify the bearer with, mirroring the RPC handshake’s auth_provider field (e.g. oidc.corp). Absent means the native pairing provider, exactly as before this layer.

Functions

authorize_config_write

Authorize one mutation’s complete write set for the request’s principal, before the mutation’s first side effect and under the config write lock. Every path needs both the Config verb its effect requires and a matching config path selector, checked against the principal’s current grants. The open posture and an admin principal are unrestricted, as everywhere else.

authorize_whole_config_write

A rewrite whose write set cannot be enumerated before it runs (a schema migration of the file, a Quickstart apply): a scoped principal needs the wildcard selector and every verb the rewrite may exercise. Nothing narrower can be honoured, so nothing narrower is accepted.

config_route_auth

Route-layer middleware for the config/onboarding route group.

Type Aliases

RequestPrincipal

The extractor a mutating handler declares to receive its RequestAuth. Absent only when the handler is invoked outside the route group (unit tests call handlers directly); nothing is enforced or published then.