Crate toolkit_security 

Security primitives shared by every ToolKit gear: who a caller is, what they are allowed to reach, and how a service proves its own identity to another.

A leaf crate by design — it depends on no other ToolKit library, so anything from a bootstrap path to a gear’s domain layer can use it without pulling in the runtime.

The two planes

ToolKit authenticates on two independent planes, and this crate carries the types for both (cpt-cf-adr-two-plane-auth):

• Tenant plane — a user’s request. SecurityContext is the result: the subject, its tenant, and the token’s capability scopes. Produced by a BearerAuthenticator from an Authorization: Bearer JWT.
• Platform plane — one service calling another. PlatformIdentity is the result, produced by an InternalAuthenticator from the constants::INTERNAL_TOKEN_HEADER credential. Never Authorization, so the two planes cannot be confused for one another.

Authorization

AccessScope is what a policy decision compiles down to: a disjunction of ScopeConstraints, each a conjunction of ScopeFilters over properties like owner_tenant_id. toolkit-db turns it into a SQL WHERE clause so row-level authorization is enforced by the query rather than by a check a caller has to remember.

Two shapes carry meaning and are easy to misread: an unconstrained scope permits everything, and a deny-all scope permits nothing. The contains_* accessors report on the constraint list alone, so both answer “no” — see [AccessScope::allows_uuid] for the predicate that accounts for the difference.

Re-exports

pub use access_scope::AccessScope;

pub use access_scope::EmptyScopeConstraint;

pub use access_scope::EqScopeFilter;

pub use access_scope::InGroupScopeFilter;

pub use access_scope::InGroupSubtreeScopeFilter;

pub use access_scope::InScopeFilter;

pub use access_scope::InTenantSubtreeScopeFilter;

pub use access_scope::ScopeConstraint;

pub use access_scope::ScopeFilter;

pub use access_scope::ScopeValue;

pub use access_scope::pep_properties;

pub use authenticator::AuthNError;

pub use authenticator::BearerAuthenticator;

pub use authenticator::DynBearerAuthenticator;

pub use authenticator::DynInternalAuthenticator;

pub use context::SecurityContext;

pub use context::SecurityContextBuildError;

pub use internal_auth::InternalAuthNError;

pub use internal_auth::InternalAuthenticator;

pub use internal_auth::InternalCredential;

pub use internal_auth::PeerAuthenticated;

pub use internal_auth::PlatformAuthEnforced;

pub use internal_auth::PlatformIdentity;

pub use internal_auth::PlatformSecurityContext;

pub use internal_auth_cache::CachingInternalAuthenticator;

pub use internal_auth_cache::DEFAULT_TOKEN_REVIEW_CACHE_TTL;

pub use internal_auth_cache::InvalidCacheTtl;

pub use internal_auth_cache::MAX_TOKEN_REVIEW_CACHE_TTL;

pub use internal_auth_config::BuiltAuthenticator;

pub use internal_auth_config::DEFAULT_INTERNAL_PEER_NAME;

pub use internal_auth_config::InternalAuthConfig;

pub use internal_auth_config::InvalidInternalAuth;

pub use shared_secret::InvalidSharedSecret;

pub use shared_secret::REDACTED_PLACEHOLDER;

pub use shared_secret::SharedSecretInternalAuthenticator;

pub use bin_codec::SECCTX_BIN_VERSION;

pub use bin_codec::SecCtxDecodeError;

pub use bin_codec::SecCtxEncodeError;

pub use bin_codec::decode_bin;

pub use bin_codec::encode_bin;

Modules

access_scope

What a caller is authorized to reach, and how it compiles to a query filter.

authenticator

Traits for validating a credential on either plane, and object-safe wrappers. Transport-agnostic bearer-token authentication abstraction.

bin_codec

Binary wire format for a SecurityContext over gRPC metadata.

constants

Well-known identifiers and header names.

context

The authenticated tenant-plane caller.

internal_auth

Platform-plane identity, credentials, and the authenticator contract. Platform-plane (workload) authentication primitives.

internal_auth_cache

TTL-bounded caching for platform-plane validation. Short-lived positive (and brief negative) caching for platform-plane authentication.

internal_auth_config

Configuration selecting how the platform plane authenticates. Declarative configuration for the platform (internal) authentication plane.

prelude

The types most gears need, re-exported for a single glob import.

shared_secret

A pre-shared-secret InternalAuthenticator, for development and simple deployments. Shared-secret platform-plane authenticator (dev / single-node profiles).