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::{AnvilConfig, AnvilSession};
19//!
20//! # async fn doc() -> Result<(), anvil_ssh::AnvilError> {
21//! // GitHub
22//! let config = AnvilConfig::github();
23//! // GitLab
24//! let config = AnvilConfig::gitlab();
25//! // Codeberg
26//! let config = AnvilConfig::codeberg();
27//!
28//! let mut session = AnvilSession::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 cert_authority;
49pub mod config;
50pub mod diagnostic;
51pub mod error;
52pub mod hostkey;
53pub mod keygen;
54pub mod proxy;
55pub mod relay;
56pub mod session;
57pub mod sshsig;
58pub mod time;
59
60// `ssh_config(5)` parser and resolver. Public API is re-exported below;
61// the sub-modules (lexer, parser, include, matcher, resolver) themselves
62// are crate-private.
63pub mod ssh_config;
64
65// ── Flat re-exports (FR-23) ───────────────────────────────────────────────────
66
67pub use config::AnvilConfig;
68pub use error::AnvilError;
69pub use session::AnvilSession;
70pub use ssh_config::{
71 AlgList, DirectiveSource, ResolvedSshConfig, SshConfigPaths, StrictHostKeyChecking,
72};
73
74// ── Deprecated 0.1.x compatibility aliases ────────────────────────────────────
75//
76// Re-export the renamed types under their legacy `Gitway*` names so that
77// crates which depended on `anvil-ssh = "0.1"` (or the `gitway-lib` shim
78// that re-exports `anvil_ssh::*`) continue to compile after the 0.2.0
79// rename. These aliases emit a `#[deprecated]` warning on use; remove
80// them in 1.0 per Gitway PRD §7.4.
81
82#[deprecated(since = "0.2.0", note = "renamed to `AnvilSession`")]
83pub use AnvilSession as GitwaySession;
84
85#[deprecated(since = "0.2.0", note = "renamed to `AnvilConfig`")]
86pub use AnvilConfig as GitwayConfig;
87
88#[deprecated(since = "0.2.0", note = "renamed to `AnvilError`")]
89pub use AnvilError as GitwayError;