towershield_core/lib.rs
1//! Portable path-denylist rule model shared by the Tower middleware and
2//! offline exporters.
3//!
4//! This crate owns the declarative rule vocabulary and the compile/evaluate
5//! lifecycle. It has no HTTP runtime dependency: adapters supply a path
6//! string (or [`InspectionPath`]) and receive a [`ShieldDecision`]. Use
7//! [`towershield`](https://docs.rs/towershield) for the Tower layer, and
8//! `towershield-cloudflare` for offline edge export of the same rules.
9//!
10//! # Domain map
11//!
12//! | Concept | Types |
13//! |---|---|
14//! | Rule identity / grouping | [`RuleId`], [`RuleGroup`], [`RuleDisposition`] |
15//! | Declarative rule | [`Rule`], [`PathMatcher`], [`CaseSensitivity`] |
16//! | Authoring collection | [`RuleSet`], [`RuleSchemaVersion`] |
17//! | Hot-path evaluation | [`CompiledRuleSet`], [`InspectionPath`], [`ShieldDecision`], [`ShieldMatch`] |
18//! | Built-in denylist | [`DEFAULT_RULES`], [`defaults::default_rules`] |
19//! | Compile failure | [`ruleset::CompileError`] |
20//!
21//! # Lifecycle
22//!
23//! Build a [`RuleSet`] (or clone [`DEFAULT_RULES`]), call [`RuleSet::compile`]
24//! once at startup (or config reload), then call [`CompiledRuleSet::evaluate`]
25//! per request. Allow rules win over deny rules; no match means allow
26//! (fail-open for unmatched application traffic). Disabled rules are dropped
27//! at compile and never evaluated.
28//!
29//! # Encoding policy
30//!
31//! Path matching uses a *derived* inspection form — never a mutated request.
32//! See [`InspectionPath`] for single-pass percent-decode rules, what is
33//! excluded (query string, `..` collapse), and intentional `%2F` behaviour.
34//! Match metadata in [`ShieldMatch`] is for server-side metrics only; do not
35//! embed it in client-facing responses.
36//!
37//! # Features
38//!
39//! | Feature | Effect |
40//! |---|---|
41//! | `serde` (default) | Serialize/deserialize [`Rule`], [`RuleSet`], and matchers |
42//! | `regex` (default) | Enable regex matchers and the broader built-in rule tier |
43//! | `rayon` | Parallel compile of large regex-heavy rule sets (implies `regex`) |
44#![forbid(unsafe_code)]
45#![deny(missing_docs)]
46#![deny(clippy::all)]
47
48pub mod defaults;
49pub mod inspection;
50pub mod matcher;
51pub mod rule;
52pub mod ruleset;
53
54pub use defaults::DEFAULT_RULES;
55pub use inspection::InspectionPath;
56pub use matcher::{CaseSensitivity, MatchKind, PathMatcher};
57pub use rule::{Rule, RuleDisposition, RuleGroup, RuleId};
58pub use ruleset::{CompiledRuleSet, RuleSchemaVersion, RuleSet};
59
60/// Outcome of evaluating an inspection path against a [`CompiledRuleSet`].
61///
62/// Adapters map `Allow` to “forward unchanged” and `Block` to a generic
63/// rejection response that must not reveal which rule matched to clients.
64#[derive(Debug, Clone, PartialEq, Eq)]
65pub enum ShieldDecision {
66 /// No deny rule matched (or an allow rule matched first); continue.
67 Allow,
68 /// A deny rule matched; reject without calling protected handlers.
69 Block(ShieldMatch),
70}
71
72/// Identity of the deny rule that produced a [`ShieldDecision::Block`].
73///
74/// Safe for metrics and observability callbacks. Do not put this payload
75/// into client-facing HTTP bodies or headers.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct ShieldMatch {
78 /// Stable rule identifier (e.g. `"secrets.dotenv"`).
79 pub rule_id: RuleId,
80 /// Logical category used for filtering, metrics, and export grouping.
81 pub group: RuleGroup,
82 /// Discriminant of the matcher that hit (without the pattern string).
83 pub match_kind: MatchKind,
84 /// Whether the matched rule shipped with the crate's built-in set.
85 pub is_builtin: bool,
86}