anvil_ssh/lib.rs
1// SPDX-License-Identifier: GPL-3.0-or-later
2// Rust guideline compliant 2026-04-05
3// S3: enforce zero unsafe in all project-owned code at compile time.
4#![forbid(unsafe_code)]
5//! # anvil-ssh
6//!
7//! Pure-Rust SSH library for Git: transport, keys, signing, agent.
8//!
9//! Built on [`russh`](https://docs.rs/russh) v0.59, it replaces the
10//! general-purpose `ssh` binary in the Git transport pipeline, plus the
11//! subset of `ssh-keygen`, `ssh-add`, and `ssh-agent` that day-to-day Git
12//! workflows need. Works against GitHub, GitLab, Codeberg, AUR, sourcehut,
13//! and self-hosted Git instances.
14//!
15//! ## Quick start
16//!
17//! ```no_run
18//! use anvil_ssh::{GitwayConfig, GitwaySession};
19//!
20//! # async fn doc() -> Result<(), anvil_ssh::GitwayError> {
21//! // GitHub
22//! let config = GitwayConfig::github();
23//! // GitLab
24//! let config = GitwayConfig::gitlab();
25//! // Codeberg
26//! let config = GitwayConfig::codeberg();
27//!
28//! let mut session = GitwaySession::connect(&config).await?;
29//! session.authenticate_best(&config).await?;
30//!
31//! let exit_code = session.exec("git-upload-pack 'user/repo.git'").await?;
32//! session.close().await?;
33//! # Ok(())
34//! # }
35//! ```
36//!
37//! ## Design principles
38//!
39//! - **Pinned host keys** — SHA-256 fingerprints for GitHub, GitLab, and
40//! Codeberg are embedded; no TOFU (Trust On First Use) for known hosts.
41//! - **Narrow scope** — only exec channels; no PTY, SFTP, or port forwarding.
42//! - **Post-quantum ready** — uses `aws-lc-rs` for cryptography.
43//! - **Metric / SI / ISO 8601** throughout all timestamps and measurements.
44
45pub mod agent;
46pub mod allowed_signers;
47pub mod auth;
48pub mod config;
49pub mod diagnostic;
50pub mod error;
51pub mod hostkey;
52pub mod keygen;
53pub mod relay;
54pub mod session;
55pub mod sshsig;
56pub mod time;
57
58// ── Flat re-exports (FR-23) ───────────────────────────────────────────────────
59
60pub use config::GitwayConfig;
61pub use error::GitwayError;
62pub use session::GitwaySession;