webgates 1.0.0

Application-facing composition crate for webgates authentication and authorization.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

#![deny(missing_docs)]
#![deny(unsafe_code)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
/*!
# webgates

User-focused composition crate for building a practical `webgates` application stack.

`webgates` builds on `webgates-core` and adds optional higher-level capabilities
such as authentication workflows, framework-agnostic gate builders, cookie
configuration, JWT support, sessions, secrets, OAuth2, and observability.

Most application developers should start here rather than wiring multiple
workspace crates together manually.

## When to use this crate

Use `webgates` when you want:

- one crate as the main dependency for application code
- the core domain model plus higher-level authentication and authorization tools
- framework-agnostic gate configuration for cookies, bearer tokens, or OAuth2
- optional login/logout orchestration
- optional session-backed authentication and renewal
- optional audit logging and metrics hooks

If you only need the domain model and authorization primitives, use
`webgates-core` directly.

## What this crate adds

Compared with `webgates-core`, this crate adds optional modules for:

- authentication workflows via [`authn`]
- cookie configuration via [`cookie_template`]
- framework-agnostic gate builders via [`gate`]
- audit logging via [`audit`] when the `audit-logging` feature is enabled

Additional sibling crates are re-exported behind features:

- `codecs` enables `webgates-codecs`
- `secrets` enables `webgates-secrets`
- `sessions` enables `webgates-sessions`

Framework adapters remain in sibling crates such as `webgates-axum`.
Persistence backends remain in `webgates-repositories`.

## Quick mental model

A common application flow looks like this:

1. use the re-exported core domain model such as [`accounts::Account`] and
   [`authz::access_policy::AccessPolicy`]
2. define protected access with a [`gate::Gate`]
3. translate the gate into framework behavior using an adapter crate such as
   `webgates-axum`
4. optionally add login/logout, cookies, sessions, secrets, and observability
   through feature flags

## Quick start

The canonical domain types come from the same paths as in `webgates-core`:

```rust
use webgates::accounts::Account;
use webgates::authz::access_policy::AccessPolicy;
use webgates::groups::Group;
use webgates::roles::Role;
```

A minimal codec-only setup looks like this:

```rust
#[cfg(feature = "codecs")]
# {
use std::sync::Arc;
use webgates::accounts::Account;
use webgates::codecs::jwt::{JsonWebToken, JwtClaims};
use webgates::groups::Group;
use webgates::roles::Role;

type AppClaims = JwtClaims<Account<Role, Group>>;
let codec = Arc::new(JsonWebToken::<AppClaims>::default());
let _ = codec;
# }
```

When the `cookies` feature is enabled, you can build a cookie-based gate:

```rust
#[cfg(feature = "cookies")]
# {
use std::sync::Arc;
use webgates::accounts::Account;
use webgates::authz::access_policy::AccessPolicy;
use webgates::codecs::jwt::{JsonWebToken, JwtClaims};
use webgates::gate::Gate;
use webgates::groups::Group;
use webgates::roles::Role;

type AppClaims = JwtClaims<Account<Role, Group>>;
let codec = Arc::new(JsonWebToken::<AppClaims>::default());

let gate = Gate::cookie::<_, Role, Group>("my-app", Arc::clone(&codec))
    .require_login()
    .with_policy(AccessPolicy::<Role, Group>::require_permission("admin:read"));

let _ = gate;
# }
```

## Session-backed deployment model

When you enable session-backed authentication, the canonical deployment model is:

- an **auth authority** that verifies credentials, issues auth and refresh
  tokens, owns session persistence, and performs refresh-token rotation and
  revocation
- one or more **resource services** that validate short-lived access tokens
  locally and enforce authorization policy
- an optional **single-node deployment** that runs both roles together while
  preserving the same token and revocation semantics

In that model, refresh-token and session mutation logic stay on the authority,
while resource services validate access tokens locally without per-request
introspection calls. Revocation consistency across resource nodes is therefore
bounded by the short access-token TTL.

## Feature model

This crate enables no optional features by default.

Main features:

- `authn` — authentication services; depends on `codecs`, `repositories`, and `secrets`
- `codecs` — re-export `webgates-codecs`
- `cookies` — cookie templates and cookie-dependent gate helpers
- `oauth2` — OAuth2 gate support; depends on `codecs`, `cookies`, and `repositories`
- `secrets` — re-export `webgates-secrets`
- `sessions` — framework-agnostic session lifecycle and renewal primitives
- `repositories` — repository contracts used by higher-level workflows
- `audit-logging` — structured audit events
- `prometheus` — Prometheus metrics for audit logging
- `full` — the standard composed stack

## Getting started on docs.rs

If you are reading this crate on docs.rs, this is a good order to follow:

1. Start with the re-exported core model in [`accounts`], [`roles`], [`groups`],
   and [`permissions`].
2. Read [`gate`] to understand the main higher-level abstraction.
3. Read [`cookie_template`] if you use browser cookies.
4. Read [`authn`] if you are implementing login/logout workflows.
5. Explore feature-gated re-exports such as `codecs`, `secrets`, and `sessions`
   based on your application needs.

## Design notes

- `webgates-core` owns the core domain and authorization API.
- `webgates` extends that API with optional higher-level functionality.
- `webgates-axum` owns Axum-specific integration.
- `webgates-repositories` owns persistence backends and repository modules.
*/

pub use webgates_core::validate_permissions;
pub use webgates_core::{
    accounts, authz, credentials, errors_core, groups, permissions, roles, verification_result,
};

#[cfg(feature = "audit-logging")]
pub mod audit;
#[cfg(feature = "authn")]
pub mod authn;
#[cfg(feature = "cookies")]
pub use cookie;
#[cfg(feature = "codecs")]
pub use webgates_codecs as codecs;
#[cfg(feature = "cookies")]
pub mod cookie_template;
#[cfg(any(
    feature = "authn",
    feature = "codecs",
    feature = "cookies",
    feature = "secrets"
))]
pub mod errors;
#[cfg(any(feature = "codecs", feature = "cookies"))]
pub(crate) mod errors_integration;
#[cfg(any(feature = "codecs", feature = "cookies", feature = "oauth2"))]
pub mod gate;
#[cfg(feature = "secrets")]
pub use webgates_secrets as secrets;
#[cfg(feature = "sessions")]
pub use webgates_sessions as sessions;