webgates_tonic/lib.rs
1#![deny(missing_docs)]
2#![deny(unsafe_code)]
3#![deny(clippy::unwrap_used)]
4#![deny(clippy::expect_used)]
5/*!
6# webgates-tonic
7
8tonic server-side integration for `webgates` bearer-token authentication and authorization.
9
10This crate is the tonic-facing transport adapter for `webgates`. It applies
11bearer-token authentication and authorization to incoming gRPC requests while
12keeping the core auth and policy logic in the framework-agnostic `webgates`
13crate.
14
15It is **server-side only** and intentionally does not provide cookie transport,
16browser-redirect OAuth2 flows, or tonic client utilities.
17
18## When to use this crate
19
20Use `webgates-tonic` when you want:
21
22- tonic middleware for bearer-token authentication
23- `webgates` authorization policy enforcement on gRPC services
24- typed auth context in tonic request extensions
25- optional JWT auth context for mixed public/authenticated methods
26- static-token service-to-service authentication
27
28## Key modules
29
30Most tonic applications can learn this crate in three steps:
31
321. start with [`gate`] to understand how bearer auth is enforced in middleware
332. move to [`context`] to see what handler-visible auth state becomes available
343. read [`errors`] if you need to understand or customize auth failure behavior
35
36## Examples
37
38```rust,no_run
39use std::sync::Arc;
40use webgates::accounts::Account;
41use webgates::authz::access_policy::AccessPolicy;
42use webgates::roles::Role;
43use webgates::groups::Group;
44use webgates_codecs::jwt::{JsonWebToken, JwtClaims};
45use webgates_tonic::gate::Gate;
46
47let codec = Arc::new(JsonWebToken::<JwtClaims<Account<Role, Group>>>::default());
48let layer = Gate::bearer("my-svc", codec)
49 .with_policy(AccessPolicy::<Role, Group>::require_role(Role::Admin));
50
51let _ = layer;
52```
53
54## Getting started on docs.rs
55
56A good reading order is:
57
581. [`gate`]
592. [`context`]
603. [`errors`]
614. [`gate::bearer`]
625. [`gate::remote_jwks_bearer`] if you need remote JWKS-backed verification
63*/
64
65/// Gate builders and tower middleware for tonic services.
66pub mod gate;
67
68/// Typed authentication context inserted into tonic request extensions.
69///
70/// See `crate::context` for `JwtAuthContext`, `OptionalJwtAuthContext`, and
71/// `StaticTokenAuthorized`.
72pub mod context;
73
74/// Authentication error types and their mapping to [`tonic::Status`] codes.
75pub mod errors;