mockforge_platform_signing/
lib.rs

1//! HSM-backed platform signing-root for `MockForge`.
2//!
3//! Implements RFC §8.2 (kill-switch signing) and §9 (rotation procedure) of
4//! the cloud trust & permissions RFC.
5//!
6//! # Layout
7//!
8//! - [`signer`] — [`PlatformSigner`] trait + an in-memory [`MockSigner`]
9//!   for tests.
10//! - [`aws_kms`] (feature: `aws-kms`) — production [`AwsKmsSigner`] that
11//!   round-trips signatures through AWS KMS so private bytes never leave
12//!   the service boundary.
13//! - [`rotation`] — [`RotationStateMachine`] + [`RotationEvent`]; how the
14//!   operator drives a key handover and how the wire-format manifest is
15//!   built.
16//! - [`verifier`] — pure-Rust verifier for `RotationEvent` manifests, used
17//!   by plugin-hosts to decide whether to trust a newly-rotated platform
18//!   key. Does not need the AWS SDK.
19//!
20//! # Quick start (operator-facing)
21//!
22//! ```no_run
23//! # #[cfg(feature = "aws-kms")]
24//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
25//! use mockforge_platform_signing::aws_kms::AwsKmsSigner;
26//! use mockforge_platform_signing::rotation::RotationStateMachine;
27//! use chrono::Duration;
28//!
29//! // Active key — `MOCKFORGE_PLATFORM_SIGNING_KMS_KEY_ID`.
30//! let current = AwsKmsSigner::from_env().await?;
31//! // New key — generated out-of-band via the runbook.
32//! let next = AwsKmsSigner::from_key_id("arn:aws:kms:us-east-1:...:key/new").await?;
33//!
34//! let mut sm = RotationStateMachine::new(current);
35//! let event = sm.begin_handover(&next, Duration::days(30)).await?;
36//! // `event` is the wire manifest the registry publishes; every host
37//! // verifies it before trusting `next.key_id()`.
38//! # Ok(()) }
39//! ```
40//!
41//! See `docs/plugins/security/platform-signing-rotation-runbook.md`
42//! for the end-to-end runbook (this crate is the machinery; the runbook
43//! is the process).
44
45#![warn(missing_docs)]
46
47pub mod rotation;
48pub mod signer;
49pub mod verifier;
50
51#[cfg(feature = "aws-kms")]
52pub mod aws_kms;
53
54pub use rotation::{
55    RotationError, RotationEvent, RotationEventPayload, RotationPhase, RotationStateMachine,
56};
57pub use signer::{MockSigner, PlatformSigner, SignerError, SigningAlgorithm};
58pub use verifier::{verify_rotation_event, VerifyError};
mockforge_platform_signing/lib.rs

mockforge_platform_signing/
lib.rs
