auths_sdk/domains/signing/

service.rs

//! Signing pipeline orchestration.
//!
//! Composed pipeline: validate freeze → sign data → format SSHSIG.
//! Agent communication and passphrase prompting remain in the CLI.
//!
//! DSSE PAE (Pre-Authentication Encoding) is computed for transparency log
//! submissions where the signing key is available (ephemeral signing).

use crate::context::AuthsContext;
use crate::ports::artifact::{ArtifactDigest, ArtifactMetadata, ArtifactSource};
use auths_core::crypto::signer as core_signer;
use auths_core::crypto::ssh::{self, SecureSeed};
use auths_core::signing::{PassphraseProvider, SecureSigner};
use auths_core::storage::keychain::{IdentityDID, KeyAlias, KeyStorage};
use auths_id::attestation::core::resign_attestation;
use auths_id::attestation::create::create_signed_attestation;
use auths_id::storage::git_refs::AttestationMetadata;
use auths_verifier::core::{OidcBinding, ResourceId, SignerType};
use auths_verifier::types::CanonicalDid;
use chrono::{DateTime, Utc};
use sha2::{Digest, Sha256};
use std::collections::HashMap;
use std::path::Path;
use std::sync::Arc;
use zeroize::Zeroizing;

/// Errors from the signing pipeline.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SigningError {
    /// The identity is in a freeze state and signing is not permitted.
    #[error("identity is frozen: {0}")]
    IdentityFrozen(String),
    /// The requested key alias could not be resolved from the keychain.
    #[error("key resolution failed: {0}")]
    KeyResolution(String),
    /// The cryptographic signing operation failed.
    #[error("signing operation failed: {0}")]
    SigningFailed(String),
    /// The supplied passphrase was incorrect.
    #[error("invalid passphrase")]
    InvalidPassphrase,
    /// SSHSIG PEM encoding failed after signing.
    #[error("PEM encoding failed: {0}")]
    PemEncoding(String),
    /// The agent is not available (platform unsupported, not installed, or not reachable).
    #[error("agent unavailable: {0}")]
    AgentUnavailable(String),
    /// The agent accepted the signing request but it failed.
    #[error("agent signing failed")]
    AgentSigningFailed(#[source] crate::ports::agent::AgentSigningError),
    /// All passphrase attempts were exhausted without a successful decryption.
    #[error("passphrase exhausted after {attempts} attempt(s)")]
    PassphraseExhausted {
        /// Number of failed attempts before giving up.
        attempts: usize,
    },
    /// The platform keychain could not be accessed.
    #[error("keychain unavailable: {0}")]
    KeychainUnavailable(String),
    /// The encrypted key material could not be decrypted.
    #[error("key decryption failed: {0}")]
    KeyDecryptionFailed(String),
}

impl auths_core::error::AuthsErrorInfo for SigningError {
    fn error_code(&self) -> &'static str {
        match self {
            Self::IdentityFrozen(_) => "AUTHS-E5901",
            Self::KeyResolution(_) => "AUTHS-E5902",
            Self::SigningFailed(_) => "AUTHS-E5903",
            Self::InvalidPassphrase => "AUTHS-E5904",
            Self::PemEncoding(_) => "AUTHS-E5905",
            Self::AgentUnavailable(_) => "AUTHS-E5906",
            Self::AgentSigningFailed(_) => "AUTHS-E5907",
            Self::PassphraseExhausted { .. } => "AUTHS-E5908",
            Self::KeychainUnavailable(_) => "AUTHS-E5909",
            Self::KeyDecryptionFailed(_) => "AUTHS-E5910",
        }
    }

    fn suggestion(&self) -> Option<&'static str> {
        match self {
            Self::IdentityFrozen(_) => Some("To unfreeze: auths emergency unfreeze"),
            Self::KeyResolution(_) => Some("Run `auths key list` to check available keys"),
            Self::SigningFailed(_) => Some(
                "The signing operation failed; verify your key is accessible with `auths key list`",
            ),
            Self::InvalidPassphrase => Some("Check your passphrase and try again"),
            Self::PemEncoding(_) => {
                Some("Failed to encode the key in PEM format; the key material may be corrupted")
            }
            Self::AgentUnavailable(_) => Some("Start the agent with `auths agent start`"),
            Self::AgentSigningFailed(_) => Some("Check agent logs with `auths agent status`"),
            Self::PassphraseExhausted { .. } => Some(
                "The passphrase you entered is incorrect (tried 3 times). Verify it matches what you set during init, or try: auths key export --key-alias <alias> --format pub",
            ),
            Self::KeychainUnavailable(_) => Some("Run `auths doctor` to diagnose keychain issues"),
            Self::KeyDecryptionFailed(_) => Some("Check your passphrase and try again"),
        }
    }
}

/// Configuration for a signing operation.
///
/// Args:
/// * `namespace`: The SSHSIG namespace (typically "git").
///
/// Usage:
/// ```ignore
/// let config = SigningConfig {
///     namespace: "git".to_string(),
/// };
/// ```
pub struct SigningConfig {
    /// SSHSIG namespace string (e.g. `"git"` for commit signing).
    pub namespace: String,
}

/// Validate that the identity is not frozen.
///
/// Args:
/// * `repo_path`: Path to the auths repository (typically `~/.auths`).
/// * `now`: The reference time used to check if the freeze is active.
///
/// Usage:
/// ```ignore
/// validate_freeze_state(&repo_path, clock.now())?;
/// ```
pub fn validate_freeze_state(
    repo_path: &Path,
    now: chrono::DateTime<chrono::Utc>,
) -> Result<(), SigningError> {
    use auths_id::freeze::load_active_freeze;

    if let Some(state) = load_active_freeze(repo_path, now)
        .map_err(|e| SigningError::IdentityFrozen(e.to_string()))?
    {
        return Err(SigningError::IdentityFrozen(format!(
            "frozen until {}. Remaining: {}. To unfreeze: auths emergency unfreeze",
            state.frozen_until.format("%Y-%m-%d %H:%M UTC"),
            state.expires_description(now),
        )));
    }

    Ok(())
}

/// Construct the SSHSIG signed-data payload for the given data and namespace.
///
/// Args:
/// * `data`: The raw bytes to sign.
/// * `namespace`: The SSHSIG namespace (e.g. "git").
///
/// Usage:
/// ```ignore
/// let payload = construct_signature_payload(b"data", "git")?;
/// ```
pub fn construct_signature_payload(data: &[u8], namespace: &str) -> Result<Vec<u8>, SigningError> {
    ssh::construct_sshsig_signed_data(data, namespace)
        .map_err(|e| SigningError::SigningFailed(e.to_string()))
}

/// Create a complete SSHSIG PEM signature from a seed and data.
///
/// Args:
/// * `seed`: The Ed25519 signing seed.
/// * `data`: The raw bytes to sign.
/// * `namespace`: The SSHSIG namespace.
///
/// Usage:
/// ```ignore
/// let pem = sign_with_seed(&seed, b"data to sign", "git")?;
/// ```
pub fn sign_with_seed(
    seed: &SecureSeed,
    data: &[u8],
    namespace: &str,
    curve: auths_crypto::CurveType,
) -> Result<String, SigningError> {
    ssh::create_sshsig(seed, data, namespace, curve)
        .map_err(|e| SigningError::PemEncoding(e.to_string()))
}

// ---------------------------------------------------------------------------
// Artifact attestation signing
// ---------------------------------------------------------------------------

/// Selects how a signing key is supplied to `sign_artifact`.
///
/// `Alias` resolves the key from the platform keychain at call time.
/// `Direct` injects a raw seed, bypassing the keychain — intended for headless
/// CI/CD runners that have no platform keychain available.
pub enum SigningKeyMaterial {
    /// Resolve by alias from the platform keychain.
    Alias(KeyAlias),
    /// Inject a raw Ed25519 seed directly. The passphrase provider is not called.
    Direct(SecureSeed),
}

/// Parameters for the artifact attestation signing workflow.
///
/// Usage:
/// ```ignore
/// let params = ArtifactSigningParams {
///     artifact: Arc::new(my_artifact),
///     identity_key: Some(SigningKeyMaterial::Alias("my-identity".into())),
///     device_key: SigningKeyMaterial::Direct(my_seed),
///     expires_in: Some(31_536_000),
///     note: None,
///     commit_sha: None,
/// };
/// ```
pub struct ArtifactSigningParams {
    /// The artifact to attest. Provides the canonical digest and metadata.
    pub artifact: Arc<dyn ArtifactSource>,
    /// Identity key source. `None` skips the identity signature.
    pub identity_key: Option<SigningKeyMaterial>,
    /// Device key source. Required to produce a dual-signed attestation.
    pub device_key: SigningKeyMaterial,
    /// Duration in seconds until expiration (per RFC 6749).
    pub expires_in: Option<u64>,
    /// Optional human-readable annotation embedded in the attestation.
    pub note: Option<String>,
    /// Git commit SHA for provenance binding (included in signed canonical data).
    pub commit_sha: Option<String>,
}

/// Result of a successful artifact attestation signing operation.
///
/// Usage:
/// ```ignore
/// let result = sign_artifact(params, &ctx)?;
/// std::fs::write(&output_path, &result.attestation_json)?;
/// println!("Signed {} (sha256:{})", result.rid, result.digest);
/// ```
#[derive(Debug)]
pub struct ArtifactSigningResult {
    /// Canonical JSON of the signed attestation.
    pub attestation_json: String,
    /// Resource identifier assigned to the attestation in the identity store.
    pub rid: ResourceId,
    /// Hex-encoded SHA-256 digest of the attested artifact.
    pub digest: String,
    /// DSSE signature over the PAE of the attestation JSON (for transparency log submission).
    /// Present when the signing function has access to the key (e.g., ephemeral signing).
    pub dsse_signature: Option<Vec<u8>>,
}

/// Errors from the artifact attestation signing workflow.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ArtifactSigningError {
    /// No auths identity was found in the configured identity storage.
    #[error("identity not found in configured identity storage")]
    IdentityNotFound,

    /// The key alias could not be resolved to usable key material.
    #[error("key resolution failed: {0}")]
    KeyResolutionFailed(String),

    /// The encrypted key material could not be decrypted (e.g. wrong passphrase).
    #[error("key decryption failed: {0}")]
    KeyDecryptionFailed(String),

    /// Computing the artifact digest failed.
    #[error("digest computation failed: {0}")]
    DigestFailed(String),

    /// Building or serializing the attestation failed.
    #[error("attestation creation failed: {0}")]
    AttestationFailed(String),

    /// Adding the device signature to a partially-signed attestation failed.
    #[error("attestation re-signing failed: {0}")]
    ResignFailed(String),

    /// The provided commit SHA has an invalid format.
    #[error("invalid commit SHA: {0} (expected 40 or 64 hex characters)")]
    InvalidCommitSha(String),

    /// The signing device's delegated identity has been revoked by the root.
    #[error("device revoked: {0}")]
    DeviceRevoked(String),

    /// The signing key is no longer the current key in the identity's KEL (rotated out).
    #[error("signing key rotated out of the KEL: {0}")]
    KeyRotatedOut(String),
}

impl auths_core::error::AuthsErrorInfo for ArtifactSigningError {
    fn error_code(&self) -> &'static str {
        match self {
            Self::IdentityNotFound => "AUTHS-E5850",
            Self::KeyResolutionFailed(_) => "AUTHS-E5851",
            Self::KeyDecryptionFailed(_) => "AUTHS-E5852",
            Self::DigestFailed(_) => "AUTHS-E5853",
            Self::AttestationFailed(_) => "AUTHS-E5854",
            Self::ResignFailed(_) => "AUTHS-E5855",
            Self::InvalidCommitSha(_) => "AUTHS-E5856",
            Self::DeviceRevoked(_) => "AUTHS-E5857",
            Self::KeyRotatedOut(_) => "AUTHS-E5858",
        }
    }

    fn suggestion(&self) -> Option<&'static str> {
        match self {
            Self::IdentityNotFound => {
                Some("Run `auths init` to create an identity, or `auths key import` to restore one")
            }
            Self::KeyResolutionFailed(_) => {
                Some("Run `auths status` to see available device aliases")
            }
            Self::KeyDecryptionFailed(_) => Some("Check your passphrase and try again"),
            Self::DigestFailed(_) => Some("Verify the file exists and is readable"),
            Self::AttestationFailed(_) => Some("Check identity storage with `auths status`"),
            Self::ResignFailed(_) => {
                Some("Verify your device key is accessible with `auths status`")
            }
            Self::InvalidCommitSha(_) => {
                Some("Provide a full SHA-1 (40 hex chars) or SHA-256 (64 hex chars) commit hash")
            }
            Self::DeviceRevoked(_) => {
                Some("This device has been removed; pair a new device or sign from an active one")
            }
            Self::KeyRotatedOut(_) => {
                Some("This key was rotated out; sign with the identity's current key")
            }
        }
    }
}

/// A `SecureSigner` backed by pre-resolved in-memory seeds.
///
/// Seeds are keyed by alias and carry their curve so sign dispatches correctly
/// for Ed25519 + P-256 identities. The passphrase provider is never called
/// because all key material was resolved before construction.
struct SeedMapSigner {
    seeds: HashMap<String, (SecureSeed, auths_crypto::CurveType)>,
}

impl SecureSigner for SeedMapSigner {
    fn sign_with_alias(
        &self,
        alias: &auths_core::storage::keychain::KeyAlias,
        _passphrase_provider: &dyn PassphraseProvider,
        message: &[u8],
    ) -> Result<Vec<u8>, auths_core::AgentError> {
        let (seed, curve) = self
            .seeds
            .get(alias.as_str())
            .ok_or(auths_core::AgentError::KeyNotFound)?;
        let typed = match curve {
            auths_crypto::CurveType::Ed25519 => auths_crypto::TypedSeed::Ed25519(*seed.as_bytes()),
            auths_crypto::CurveType::P256 => auths_crypto::TypedSeed::P256(*seed.as_bytes()),
        };
        auths_crypto::typed_sign(&typed, message)
            .map_err(|e| auths_core::AgentError::CryptoError(e.to_string()))
    }

    fn sign_for_identity(
        &self,
        _identity_did: &IdentityDID,
        _passphrase_provider: &dyn PassphraseProvider,
        _message: &[u8],
    ) -> Result<Vec<u8>, auths_core::AgentError> {
        Err(auths_core::AgentError::KeyNotFound)
    }
}

struct ResolvedKey {
    alias: KeyAlias,
    /// None for hardware backends (SE) — signing goes through the keychain directly.
    seed: Option<SecureSeed>,
    public_key_bytes: Vec<u8>,
    curve: auths_crypto::CurveType,
    /// True if this key is backed by hardware (Secure Enclave, HSM).
    is_hardware: bool,
    /// The identity (KERI AID) the stored key belongs to, when known. Present for a
    /// software key loaded by alias; `None` for direct seeds and hardware backends,
    /// which carry no resolvable registry identity here.
    identity_did: Option<IdentityDID>,
}

fn resolve_optional_key(
    material: Option<&SigningKeyMaterial>,
    synthetic_alias: &'static str,
    keychain: &(dyn KeyStorage + Send + Sync),
    passphrase_provider: &dyn PassphraseProvider,
    passphrase_prompt: &str,
) -> Result<Option<ResolvedKey>, ArtifactSigningError> {
    match material {
        None => Ok(None),
        Some(SigningKeyMaterial::Alias(alias)) => {
            // Hardware backends (Secure Enclave): resolve pubkey only; signing happens
            // later via StorageSigner so private key material never leaves the enclave.
            // MIRROR: keep in sync with workflows/signing.rs (SE branch)
            if keychain.is_hardware_backend() {
                let (pubkey, curve) = auths_core::storage::keychain::extract_public_key_bytes(
                    keychain,
                    alias,
                    passphrase_provider,
                )
                .map_err(|e| ArtifactSigningError::KeyResolutionFailed(e.to_string()))?;
                return Ok(Some(ResolvedKey {
                    alias: alias.clone(),
                    seed: None,
                    public_key_bytes: pubkey,
                    curve,
                    is_hardware: true,
                    identity_did: None,
                }));
            }

            let (device_did, _role, encrypted) = keychain
                .load_key(alias)
                .map_err(|e| ArtifactSigningError::KeyResolutionFailed(e.to_string()))?;
            let passphrase = passphrase_provider
                .get_passphrase(passphrase_prompt)
                .map_err(|e| ArtifactSigningError::KeyDecryptionFailed(e.to_string()))?;
            // Defense-in-depth: SE keys must never reach the software decrypt path.
            debug_assert!(
                !keychain.is_hardware_backend(),
                "SE keys must never reach decrypt_keypair"
            );
            let pkcs8 = core_signer::decrypt_keypair(&encrypted, &passphrase)
                .map_err(|e| ArtifactSigningError::KeyDecryptionFailed(e.to_string()))?;
            let (seed, pubkey, curve) = core_signer::load_seed_and_pubkey(&pkcs8)
                .map_err(|e| ArtifactSigningError::KeyDecryptionFailed(e.to_string()))?;
            Ok(Some(ResolvedKey {
                alias: alias.clone(),
                seed: Some(seed),
                public_key_bytes: pubkey.to_vec(),
                curve,
                is_hardware: false,
                identity_did: Some(device_did),
            }))
        }
        Some(SigningKeyMaterial::Direct(seed)) => {
            let typed = auths_crypto::TypedSeed::Ed25519(*seed.as_bytes());
            let pubkey = auths_crypto::typed_public_key(&typed)
                .map_err(|e| ArtifactSigningError::KeyDecryptionFailed(e.to_string()))?;
            Ok(Some(ResolvedKey {
                alias: KeyAlias::new_unchecked(synthetic_alias),
                seed: Some(SecureSeed::new(*seed.as_bytes())),
                public_key_bytes: pubkey,
                curve: auths_crypto::CurveType::Ed25519,
                is_hardware: false,
                identity_did: None,
            }))
        }
    }
}

fn resolve_required_key(
    material: &SigningKeyMaterial,
    synthetic_alias: &'static str,
    keychain: &(dyn KeyStorage + Send + Sync),
    passphrase_provider: &dyn PassphraseProvider,
    passphrase_prompt: &str,
) -> Result<ResolvedKey, ArtifactSigningError> {
    resolve_optional_key(
        Some(material),
        synthetic_alias,
        keychain,
        passphrase_provider,
        passphrase_prompt,
    )
    .map(|opt| {
        opt.ok_or(ArtifactSigningError::KeyDecryptionFailed(
            "expected key material but got None".into(),
        ))
    })?
}

/// Resolve the root identity's own signing key — the issuer of an artifact attestation when
/// no explicit `--key` is given. Picks the first non-rotation (`--next-`) alias stored under
/// the root's AID and loads it. A delegated device's key is deliberately NOT used here: the
/// device signs the device slot, the root signs the issuer slot.
///
/// Args:
/// * `controller_did`: the root identity whose signing key issues the attestation.
/// * `keychain`: key storage holding the root's key under its AID.
/// * `passphrase_provider`: passphrase source for decrypting the key.
///
/// Usage:
/// ```ignore
/// let issuer = resolve_root_issuer_key(&managed.controller_did, keychain, provider)?;
/// ```
fn resolve_root_issuer_key(
    controller_did: &IdentityDID,
    keychain: &(dyn KeyStorage + Send + Sync),
    passphrase_provider: &dyn PassphraseProvider,
) -> Result<ResolvedKey, ArtifactSigningError> {
    let alias = keychain
        .list_aliases_for_identity(controller_did)
        .map_err(|e| ArtifactSigningError::KeyResolutionFailed(e.to_string()))?
        .into_iter()
        .find(|a| !a.as_str().contains("--next-"))
        .ok_or_else(|| {
            ArtifactSigningError::KeyResolutionFailed(format!(
                "no signing key found for root identity {}",
                controller_did.as_str()
            ))
        })?;
    resolve_required_key(
        &SigningKeyMaterial::Alias(alias),
        "__artifact_issuer__",
        keychain,
        passphrase_provider,
        "Enter passphrase for identity key:",
    )
}

/// Refuses to sign with a device whose delegated identity has been revoked by the
/// root, or whose key has been rotated out of its identity's KEL.
///
/// The check is registry-backed: it reads the root KEL for a revocation marker on the
/// device, and the device KEL for its current key. It applies only to keys resolved by
/// alias (which carry a stored KERI AID); direct seeds and hardware keys carry no AID
/// here and are not checked.
///
/// Args:
/// * `ctx`: The signing context, providing the registry.
/// * `controller_did`: The root identity that may have revoked the device.
/// * `device_did`: The signing key's stored KERI identity (AID).
/// * `device_pk_bytes`: The raw public key bytes being signed with.
///
/// Usage:
/// ```ignore
/// enforce_signer_authority(ctx, &managed.controller_did, device_did, &pubkey)?;
/// ```
fn enforce_signer_authority(
    ctx: &AuthsContext,
    controller_did: &IdentityDID,
    device_did: &IdentityDID,
    device_pk_bytes: &[u8],
) -> Result<(), ArtifactSigningError> {
    use std::ops::ControlFlow;

    let device_prefix = auths_id::keri::parse_did_keri(device_did.as_str())
        .map_err(|e| ArtifactSigningError::KeyResolutionFailed(e.to_string()))?;
    let root_prefix = auths_id::keri::parse_did_keri(controller_did.as_str())
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    // Revoked? The root anchors a Seal::Digest of the device prefix on its own KEL.
    // Fail closed: if the root KEL cannot be read, we cannot prove the device is live.
    let mut revoked = false;
    ctx.registry
        .visit_events(&root_prefix, 0, &mut |event| {
            let hit = event.anchors().iter().any(|seal| {
                matches!(seal, auths_id::keri::Seal::Digest { d } if d.as_str() == device_prefix.as_str())
            });
            if hit {
                revoked = true;
                ControlFlow::Break(())
            } else {
                ControlFlow::Continue(())
            }
        })
        .map_err(|e| {
            ArtifactSigningError::KeyResolutionFailed(format!(
                "cannot read root KEL to check revocation: {e}"
            ))
        })?;
    if revoked {
        return Err(ArtifactSigningError::DeviceRevoked(
            device_did.as_str().to_string(),
        ));
    }

    // Rotated out? The signing key must be the current key in the device's KEL.
    // Fail closed: if the KEL state cannot be read, we cannot prove the key is current.
    let state = ctx.registry.get_key_state(&device_prefix).map_err(|e| {
        ArtifactSigningError::KeyResolutionFailed(format!(
            "cannot read KEL state for {} to verify the signing key is current: {e}",
            device_did.as_str()
        ))
    })?;
    let is_current = state.current_keys.iter().any(|k| match k.parse() {
        // Public keys, decoded from CESR (curve-tag-aware) to raw bytes; a plain
        // comparison is correct — no secret is involved.
        Ok(pk) => {
            let key_bytes: &[u8] = pk.as_bytes();
            key_bytes == device_pk_bytes
        }
        Err(_) => false,
    });
    if !is_current {
        return Err(ArtifactSigningError::KeyRotatedOut(
            device_did.as_str().to_string(),
        ));
    }
    Ok(())
}

/// Validate and normalize a commit SHA (40-char SHA-1 or 64-char SHA-256).
///
/// Args:
/// * `sha`: The raw commit SHA string to validate.
///
/// Usage:
/// ```ignore
/// let normalized = validate_commit_sha("AbCd1234...")?;
/// ```
pub fn validate_commit_sha(sha: &str) -> Result<String, ArtifactSigningError> {
    let normalized = sha.to_ascii_lowercase();
    let len = normalized.len();
    if (len != 40 && len != 64) || !normalized.bytes().all(|b| b.is_ascii_hexdigit()) {
        return Err(ArtifactSigningError::InvalidCommitSha(sha.to_string()));
    }
    Ok(normalized)
}

/// Full artifact attestation signing pipeline.
///
/// Loads the identity, resolves key material (supporting both keychain aliases
/// and direct in-memory seed injection), computes the artifact digest, and
/// produces a dual-signed attestation JSON.
///
/// Args:
/// * `params`: All inputs required for signing, including key material and artifact source.
/// * `ctx`: Runtime context providing identity storage, key storage, passphrase provider, and clock.
///
/// Usage:
/// ```ignore
/// let params = ArtifactSigningParams {
///     artifact: Arc::new(FileArtifact::new(Path::new("release.tar.gz"))),
///     identity_key: Some(SigningKeyMaterial::Alias("my-key".into())),
///     device_key: SigningKeyMaterial::Direct(seed),
///     expires_in: Some(31_536_000),
///     note: None,
///     commit_sha: None,
/// };
/// let result = sign_artifact(params, &ctx)?;
/// ```
// A straight-line dual-signature pipeline: resolve the issuer (root) + device keys,
// build and sign the attestation, then anchor it on the root KEL. The steps are
// sequential with shared locals; splitting the flow would scatter it across helpers
// without making any one part clearer.
#[allow(clippy::too_many_lines)]
pub fn sign_artifact(
    params: ArtifactSigningParams,
    ctx: &AuthsContext,
) -> Result<ArtifactSigningResult, ArtifactSigningError> {
    let managed = ctx
        .identity_storage
        .load_identity()
        .map_err(|_| ArtifactSigningError::IdentityNotFound)?;

    let keychain = ctx.key_storage.as_ref();
    let passphrase_provider = ctx.passphrase_provider.as_ref();

    // The attestation is issued by the ROOT identity (the dual-signature model: issuer +
    // device). Resolve the issuer's key — an explicit `--key`, otherwise the root's own
    // signing key, NOT the delegated device (device #0 signs only the device slot). A
    // delegated device is not the root's key, so it cannot produce a valid issuer signature
    // or a root-KEL anchor.
    let issuer_did = CanonicalDid::from(managed.controller_did.clone());
    let identity_resolved = match params.identity_key.as_ref() {
        Some(explicit) => resolve_optional_key(
            Some(explicit),
            "__artifact_identity__",
            keychain,
            passphrase_provider,
            "Enter passphrase for identity key:",
        )?,
        None => Some(resolve_root_issuer_key(
            &managed.controller_did,
            keychain,
            passphrase_provider,
        )?),
    };

    let device_resolved = resolve_required_key(
        &params.device_key,
        "__artifact_device__",
        keychain,
        passphrase_provider,
        "Enter passphrase for device key:",
    )?;

    if let Some(ref device_did) = device_resolved.identity_did {
        enforce_signer_authority(
            ctx,
            &managed.controller_did,
            device_did,
            &device_resolved.public_key_bytes,
        )?;
    }

    let mut seeds: HashMap<String, (SecureSeed, auths_crypto::CurveType)> = HashMap::new();
    let identity_alias: Option<KeyAlias> = identity_resolved.map(|r| {
        let alias = r.alias.clone();
        let curve = r.curve;
        if let Some(seed) = r.seed {
            seeds.insert(r.alias.into_inner(), (seed, curve));
        }
        alias
    });
    let device_alias = device_resolved.alias.clone();
    let device_is_hardware = device_resolved.is_hardware;
    let device_curve = device_resolved.curve;
    if let Some(seed) = device_resolved.seed {
        seeds.insert(device_resolved.alias.into_inner(), (seed, device_curve));
    }
    let device_pk_bytes = device_resolved.public_key_bytes;

    // Prefer the device key's stored delegated `did:keri` AID (device #0's own identifier)
    // over a raw `did:key` derived from the pubkey, so the device is reported by ONE
    // canonical `did:keri` everywhere (attestation subject == whoami's device_did). Falls
    // back to `did:key` for keys with no stored KERI identity (ephemeral/raw signers).
    let device_did = device_resolved
        .identity_did
        .clone()
        .map(CanonicalDid::from)
        .unwrap_or_else(|| {
            CanonicalDid::from_public_key_did_key(&device_pk_bytes, device_resolved.curve)
        });

    let artifact_meta = params
        .artifact
        .metadata()
        .map_err(|e| ArtifactSigningError::DigestFailed(e.to_string()))?;

    let rid = ResourceId::new(format!("sha256:{}", artifact_meta.digest.hex));
    let now = ctx.clock.now();
    let meta = AttestationMetadata {
        timestamp: Some(now),
        expires_at: params
            .expires_in
            .map(|s| now + chrono::Duration::seconds(s as i64)),
        note: params.note,
    };

    let payload = serde_json::to_value(&artifact_meta)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    let validated_commit_sha = params
        .commit_sha
        .map(|sha| validate_commit_sha(&sha))
        .transpose()?;

    let attestation_json = create_and_sign_attestation(
        ctx,
        seeds,
        device_is_hardware,
        now,
        &rid,
        // Dual-signature: the root identity is the issuer (its key co-signs) and the
        // delegated device #0 is the subject/device signer. The issuer is the verifiable
        // trust anchor a bundle/pinned-root verifier resolves.
        &issuer_did,
        &device_did,
        &device_pk_bytes,
        device_curve,
        payload,
        &meta,
        identity_alias.as_ref(),
        &device_alias,
        validated_commit_sha,
    )?;

    // Anchor the attestation digest on the root KEL under the issuer's (root's) key. The
    // issuer key controls the root KEL, so the anchoring ixn is a valid root event that
    // stateless (identity-bundle) verification accepts.
    if let Some(ref alias) = identity_alias {
        anchor_artifact_attestation(ctx, &managed.controller_did, alias, &attestation_json, now)?;
    }

    Ok(ArtifactSigningResult {
        attestation_json,
        rid,
        digest: artifact_meta.digest.hex,
        dsse_signature: None,
    })
}

fn anchor_artifact_attestation(
    ctx: &AuthsContext,
    controller_did: &auths_core::storage::keychain::IdentityDID,
    alias: &KeyAlias,
    attestation_json: &str,
    now: DateTime<Utc>,
) -> Result<(), ArtifactSigningError> {
    let prefix = auths_id::keri::parse_did_keri(controller_did.as_str())
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;
    let att: auths_verifier::core::Attestation = serde_json::from_str(attestation_json)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;
    let storage_signer = auths_core::signing::StorageSigner::new(Arc::clone(&ctx.key_storage));
    let mut batch = auths_id::storage::registry::backend::AtomicWriteBatch::new();
    batch.stage_attestation(att.clone());
    auths_id::keri::anchor_and_persist_via_backend(
        ctx.registry.as_ref(),
        &storage_signer,
        alias,
        ctx.passphrase_provider.as_ref(),
        &prefix,
        &att,
        &mut batch,
        &ctx.witness_params(),
        now,
    )
    .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;
    Ok(())
}

/// Create, sign, and serialize an attestation. Handles both hardware and software signers.
#[allow(clippy::too_many_arguments)]
fn create_and_sign_attestation(
    ctx: &AuthsContext,
    seeds: HashMap<String, (SecureSeed, auths_crypto::CurveType)>,
    device_is_hardware: bool,
    now: DateTime<Utc>,
    rid: &ResourceId,
    issuer: &CanonicalDid,
    subject: &CanonicalDid,
    device_pk_bytes: &[u8],
    device_curve: auths_crypto::CurveType,
    payload: serde_json::Value,
    meta: &AttestationMetadata,
    identity_alias: Option<&KeyAlias>,
    device_alias: &KeyAlias,
    commit_sha: Option<String>,
) -> Result<String, ArtifactSigningError> {
    let seed_signer = SeedMapSigner { seeds };
    let storage_signer = auths_core::signing::StorageSigner::new(Arc::clone(&ctx.key_storage));
    let signer: &dyn SecureSigner = if device_is_hardware {
        &storage_signer
    } else {
        &seed_signer
    };
    let noop_provider = auths_core::PrefilledPassphraseProvider::new("");

    let issuer_canonical = issuer.clone();
    let mut attestation = create_signed_attestation(
        now,
        auths_id::attestation::create::AttestationInput {
            rid: rid.as_str(),
            issuer: &issuer_canonical,
            subject,
            device_public_key: device_pk_bytes,
            device_curve,
            payload: Some(payload),
            meta,
            identity_alias,
            device_alias: Some(device_alias),
            delegated_by: None,
            commit_sha,
            signer_type: None,
            oidc_binding: None,
        },
        signer,
        &noop_provider,
    )
    .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    resign_attestation(
        &mut attestation,
        signer,
        &noop_provider,
        identity_alias,
        device_alias,
    )
    .map_err(|e| ArtifactSigningError::ResignFailed(e.to_string()))?;

    serde_json::to_string_pretty(&attestation)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))
}

/// Inputs for [`sign_artifact_ephemeral`] — the artifact bytes plus the
/// provenance the one-time key binds them to. Named fields (the
/// `AttestationInput` pattern) so call sites stay readable as the shape
/// evolves.
pub struct EphemeralSignRequest<'a> {
    /// Raw artifact bytes to sign.
    pub data: &'a [u8],
    /// Optional human-readable name for the artifact.
    pub artifact_name: Option<String>,
    /// Git commit SHA this artifact was built from (required, 40 or 64 hex chars).
    pub commit_sha: String,
    /// Curve the one-time ephemeral key is minted on. A parsed
    /// [`CurveType`](auths_crypto::CurveType) (the boundary validated it), so
    /// the signer never branches on a string. Defaults to P-256 via
    /// `CurveType::default()`.
    pub curve: auths_crypto::CurveType,
    /// Optional TTL in seconds.
    pub expires_in: Option<u64>,
    /// Optional attestation note.
    pub note: Option<String>,
    /// Optional CI environment metadata (serialized into payload, covered by signature).
    pub ci_env: Option<serde_json::Value>,
    /// Verified OIDC workload binding, if the runner presented a token
    /// (signed envelope field, so verify-time policy joins can trust it).
    pub oidc_binding: Option<OidcBinding>,
}

/// Signs artifact bytes with a one-time ephemeral key on the requested curve.
/// No keychain, no identity storage, no passphrase — the key is generated,
/// used, and zeroized within this function call.
///
/// The ephemeral key signs "this artifact was built from this commit." Trust
/// derives transitively: consumers verify the commit is signed by a maintainer,
/// then verify this attestation's ephemeral signature covers the artifact hash
/// and commit SHA.
///
/// Args:
/// * `now` - Current UTC time (injected per clock pattern).
/// * `req` - The artifact bytes plus provenance to bind (see
///   [`EphemeralSignRequest`]).
///
/// Usage:
/// ```ignore
/// let result = sign_artifact_ephemeral(Utc::now(), EphemeralSignRequest {
///     data: b"artifact bytes",
///     artifact_name: Some("release.tar.gz".into()),
///     commit_sha: "abc123def456abc123def456abc123def456abc1".into(),
///     curve: auths_crypto::CurveType::default(),
///     expires_in: None,
///     note: None,
///     ci_env: None,
///     oidc_binding: None,
/// })?;
/// ```
pub fn sign_artifact_ephemeral(
    now: DateTime<Utc>,
    req: EphemeralSignRequest<'_>,
) -> Result<ArtifactSigningResult, ArtifactSigningError> {
    let EphemeralSignRequest {
        data,
        artifact_name,
        commit_sha,
        curve,
        expires_in,
        note,
        ci_env,
        oidc_binding,
    } = req;
    // 1. Generate the ephemeral seed and zeroize on drop
    let mut seed_bytes = Zeroizing::new([0u8; 32]);
    ring::rand::SecureRandom::fill(&ring::rand::SystemRandom::new(), seed_bytes.as_mut())
        .map_err(|_| ArtifactSigningError::AttestationFailed("RNG failure".into()))?;

    // 2. Derive pubkey and DIDs on the requested curve
    let typed_seed = auths_crypto::TypedSeed::from_curve(curve, *seed_bytes);
    let pubkey_vec = auths_crypto::typed_public_key(&typed_seed)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    // The ephemeral key is its own issuer, so the issuer DID here is the
    // `did:key:` of that key, not a `did:keri:` identity.
    let device_did = CanonicalDid::from_public_key_did_key(&pubkey_vec, curve);

    // 3. Build artifact metadata with optional CI environment in payload
    let digest_hex = hex::encode(Sha256::digest(data));
    let artifact_meta = ArtifactMetadata {
        artifact_type: "file".to_string(),
        digest: ArtifactDigest {
            algorithm: "sha256".to_string(),
            hex: digest_hex,
        },
        name: artifact_name,
        size: Some(data.len() as u64),
    };

    let mut payload_value = serde_json::to_value(&artifact_meta)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    if let Some(env) = ci_env
        && let serde_json::Value::Object(ref mut map) = payload_value
    {
        map.insert("ci_environment".to_string(), env);
    }

    let rid = ResourceId::new(format!("sha256:{}", artifact_meta.digest.hex));
    let meta = AttestationMetadata {
        timestamp: Some(now),
        expires_at: expires_in.map(|s| now + chrono::Duration::seconds(s as i64)),
        note,
    };

    // 4. Validate commit SHA
    let validated_sha = validate_commit_sha(&commit_sha)?;

    // 5. Set up ephemeral signer
    let identity_alias = KeyAlias::new_unchecked("__ephemeral_identity__");
    let device_alias = KeyAlias::new_unchecked("__ephemeral_device__");

    let mut seeds: HashMap<String, (SecureSeed, auths_crypto::CurveType)> = HashMap::new();
    seeds.insert(
        identity_alias.as_str().to_string(),
        (SecureSeed::new(*seed_bytes), curve),
    );
    seeds.insert(
        device_alias.as_str().to_string(),
        (SecureSeed::new(*seed_bytes), curve),
    );
    let signer = SeedMapSigner { seeds };
    let noop_provider = auths_core::PrefilledPassphraseProvider::new("");

    // 6. Create signed attestation with Workload signer type
    let attestation = create_signed_attestation(
        now,
        auths_id::attestation::create::AttestationInput {
            rid: rid.as_str(),
            issuer: &device_did,
            subject: &device_did,
            device_public_key: &pubkey_vec,
            device_curve: curve,
            payload: Some(payload_value),
            meta: &meta,
            identity_alias: Some(&identity_alias),
            device_alias: Some(&device_alias),
            delegated_by: None,
            commit_sha: Some(validated_sha),
            signer_type: Some(SignerType::Workload),
            oidc_binding,
        },
        &signer,
        &noop_provider,
    )
    .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    let attestation_json = serde_json::to_string_pretty(&attestation)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    // Compute DSSE signature for transparency log submission (key still in scope)
    let pae = dsse_pae("application/vnd.auths+json", attestation_json.as_bytes());
    let dsse_sig = auths_crypto::typed_sign(&typed_seed, &pae)
        .map_err(|e| ArtifactSigningError::AttestationFailed(format!("DSSE sign: {e}")))?;

    Ok(ArtifactSigningResult {
        attestation_json,
        rid,
        digest: artifact_meta.digest.hex,
        dsse_signature: Some(dsse_sig),
    })
}

/// Signs artifact bytes with a raw Ed25519 seed, bypassing keychain and identity storage.
///
/// This is the raw-key equivalent of [`sign_artifact`]. It does not require an
/// [`AuthsContext`] or any filesystem/keychain access. The same seed is used for
/// both identity and device signing roles.
///
/// Args:
/// * `now` - Current UTC time (injected per clock pattern).
/// * `seed` - Ed25519 32-byte seed.
/// * `identity_did` - Parsed identity DID (must be `did:keri:` — caller validates via `IdentityDID::parse()`).
/// * `data` - Raw artifact bytes to sign.
/// * `expires_in` - Optional TTL in seconds.
/// * `note` - Optional attestation note.
/// * `commit_sha` - Optional git commit SHA for provenance binding (40 or 64 hex chars).
///
/// Usage:
/// ```ignore
/// let did = IdentityDID::parse("did:keri:E...")?;
/// let result = sign_artifact_raw(Utc::now(), &seed, &did, b"payload", None, None, None)?;
/// ```
pub fn sign_artifact_raw(
    now: DateTime<Utc>,
    seed: &SecureSeed,
    identity_did: &IdentityDID,
    data: &[u8],
    expires_in: Option<u64>,
    note: Option<String>,
    commit_sha: Option<String>,
) -> Result<ArtifactSigningResult, ArtifactSigningError> {
    // Default to P-256 per workspace convention. The raw seed is 32 bytes for both curves.
    let curve = auths_crypto::CurveType::default();
    let typed = auths_crypto::TypedSeed::from_curve(curve, *seed.as_bytes());
    let pubkey = auths_crypto::typed_public_key(&typed)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    let device_did = CanonicalDid::from_public_key_did_key(&pubkey, curve);

    let digest_hex = hex::encode(Sha256::digest(data));
    let artifact_meta = ArtifactMetadata {
        artifact_type: "bytes".to_string(),
        digest: ArtifactDigest {
            algorithm: "sha256".to_string(),
            hex: digest_hex,
        },
        name: None,
        size: Some(data.len() as u64),
    };

    let rid = ResourceId::new(format!("sha256:{}", artifact_meta.digest.hex));
    let meta = AttestationMetadata {
        timestamp: Some(now),
        expires_at: expires_in.map(|s| now + chrono::Duration::seconds(s as i64)),
        note,
    };

    let payload = serde_json::to_value(&artifact_meta)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    let identity_alias = KeyAlias::new_unchecked("__raw_identity__");
    let device_alias = KeyAlias::new_unchecked("__raw_device__");

    let mut seeds: HashMap<String, (SecureSeed, auths_crypto::CurveType)> = HashMap::new();
    seeds.insert(
        identity_alias.as_str().to_string(),
        (SecureSeed::new(*seed.as_bytes()), curve),
    );
    seeds.insert(
        device_alias.as_str().to_string(),
        (SecureSeed::new(*seed.as_bytes()), curve),
    );
    let signer = SeedMapSigner { seeds };
    // Seeds are already resolved — passphrase provider will not be called.
    let noop_provider = auths_core::PrefilledPassphraseProvider::new("");

    let validated_commit_sha = commit_sha
        .map(|sha| validate_commit_sha(&sha))
        .transpose()?;

    let issuer_canonical = CanonicalDid::from(identity_did.clone());
    let attestation = create_signed_attestation(
        now,
        auths_id::attestation::create::AttestationInput {
            rid: rid.as_str(),
            issuer: &issuer_canonical,
            subject: &device_did,
            device_public_key: &pubkey,
            device_curve: curve,
            payload: Some(payload),
            meta: &meta,
            identity_alias: Some(&identity_alias),
            device_alias: Some(&device_alias),
            delegated_by: None,
            commit_sha: validated_commit_sha,
            signer_type: None,
            oidc_binding: None,
        },
        &signer,
        &noop_provider,
    )
    .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    let attestation_json = serde_json::to_string_pretty(&attestation)
        .map_err(|e| ArtifactSigningError::AttestationFailed(e.to_string()))?;

    Ok(ArtifactSigningResult {
        attestation_json,
        rid,
        digest: artifact_meta.digest.hex,
        dsse_signature: None,
    })
}

/// Compute the DSSE Pre-Authentication Encoding (PAE).
///
/// Format per the DSSE spec:
/// `"DSSEv1" SP len(payloadType) SP payloadType SP len(payload) SP payload`
pub fn dsse_pae(payload_type: &str, payload: &[u8]) -> Vec<u8> {
    let header = format!(
        "DSSEv1 {} {} {} ",
        payload_type.len(),
        payload_type,
        payload.len()
    );
    let mut result = Vec::with_capacity(header.len() + payload.len());
    result.extend_from_slice(header.as_bytes());
    result.extend_from_slice(payload);
    result
}