shell_tunnel/security/
mod.rs

1//! Security module for shell-tunnel.
2//!
3//! **Two of the three things here are defences this server applies; the third is
4//! a primitive it offers and does not use.** They were listed together as
5//! "provided for the API layer", which reads as three active defences and is
6//! not what happens.
7//!
8//! ## Applied by the server, on every request
9//!
10//! - **API key authentication** — bearer tokens, scoped by capability
11//!   ([`auth`], [`capability`]).
12//! - **Rate limiting** — per-address sliding window ([`rate_limit`]).
13//!
14//! ## Offered, and not applied
15//!
16//! - **Command validation** ([`validation`]) — [`CommandValidator`],
17//!   [`looks_like_injection`] and the rest are **not called from any execute
18//!   path**. A command sent to `/execute` reaches the shell without passing
19//!   through them, and nothing here is a barrier between a caller and the
20//!   machine; the barriers are the two above, plus [`crate::fs::FsRoot`] on the
21//!   filesystem routes.
22//!
23//!   Whether to wire it is an open product question rather than an oversight: a
24//!   substring blocklist on by default is a trade a run-anything tool has to
25//!   choose deliberately. Until it is chosen, this stays a primitive a consumer
26//!   may apply to its own input before calling — which is a real use, and the
27//!   reason it is still exported.
28//!
29//! ## Example
30//!
31//! ```rust
32//! use shell_tunnel::security::{ApiKeyStore, RateLimiter, CommandValidator};
33//!
34//! // Applied by the server: authentication …
35//! let auth = ApiKeyStore::default();
36//! auth.add_key("my-secret-key");
37//!
38//! // … and rate limiting (100 req/min).
39//! let limiter = RateLimiter::default();
40//!
41//! // Offered, not applied: a consumer may run this over its own input before
42//! // calling the API. The server does not.
43//! let validator = CommandValidator::default();
44//! assert!(validator.validate_command("echo hello").is_ok());
45//! ```
46
47pub mod auth;
48pub mod capability;
49pub mod rate_limit;
50pub mod validation;
51
52// Re-export commonly used types
53pub use auth::{auth_middleware, generate_api_key, ApiKeyStore, AuthConfig, TokenRecord};
54pub use capability::{preset, CapabilitySet, KNOWN_CAPABILITIES, WILDCARD};
55pub use rate_limit::{
56    rate_limit_middleware, RateLimitCharge, RateLimitConfig, RateLimitDecision, RateLimitStats,
57    RateLimiter,
58};
59pub use validation::{
60    looks_like_injection, sanitize_for_display, CommandValidator, ValidationConfig, ValidationError,
61};
shell_tunnel/security/mod.rs

shell_tunnel/security/
mod.rs
