forge-identity

use forge_identity;

pub mod agent_identity;

pub mod error;

pub mod glyph;

pub mod lineage;

pub mod local_dev;

pub mod persistence;

pub mod prelude;

pub use crate::agent_identity::ForgeAgentIdentity;

pub use crate::error::{ForgeIdentityError, ForgeIdentityResult};

pub use crate::lineage::{
        create_hmr_identity, create_mhr_identity, derive_agent_identity, verify_lineage_chain,
        DEFAULT_MAX_LINEAGE_DEPTH,
    };

#[allow(deprecated)]
pub use crate::persistence::{load_identity, save_identity};

pub struct ForgeAgentIdentity {

}

pub fn new(
        did: String,
        kind: String,
        keypair: OasKeyPair,
        document: OasDocument,
        lineage_depth: u32,
    ) -> ForgeIdentityResult<Self>;

pub fn did(&self) -> &str;

pub fn kind(&self) -> &str;

pub fn document(&self) -> &OasDocument;

pub fn lineage_depth(&self) -> u32;

pub fn sign(&self, message: &[u8]) -> Vec<u8>;

pub fn verify(&self, message: &[u8], signature: &[u8]) -> ForgeIdentityResult<()>;

pub fn verifying_key_bytes(&self) -> [u8; 32];

#[derive(Debug, Error)]
pub enum ForgeIdentityError {
    /// HKDF key derivation failed for the specified derivation path.
    ///
    /// This indicates a failure in the cryptographic key derivation process
    /// when creating a child agent identity from a parent.
    ///
    /// See ANVIL Spec §11.1 — OAS Identity Binding.
    #[error("identity derivation failed for path '{path}' from parent {parent_did}: {reason}")]
    DerivationFailed {
        /// The parent's DID from which derivation was attempted.
        parent_did: String,
        /// The HKDF derivation path that was used.
        path: String,
        /// A description of why the derivation failed.
        reason: String,
    },

    /// Lineage chain verification failed for the specified identity.
    ///
    /// The cryptographic chain from the agent to its human root could not
    /// be verified. This may indicate a tampered identity, a missing parent
    /// document, or an invalid proof signature.
    ///
    /// See ANVIL Spec §11.2 — Lineage Propagation.
    #[error("lineage verification failed for '{did}': {reason}")]
    LineageVerificationFailed {
        /// The DID of the identity whose lineage failed verification.
        did: String,
        /// A description of why verification failed.
        reason: String,
    },

    /// Lineage chain exceeds the maximum allowed generation depth.
    ///
    /// ANVIL Spec §11.2 defines a maximum lineage depth to prevent
    /// unbounded delegation chains. The default maximum is 16.
    #[error("lineage chain depth {depth} exceeds ANVIL maximum {max_depth} (ANVIL Spec §11.2)")]
    ChainTooDeep {
        /// The actual depth of the lineage chain.
        depth: u32,
        /// The configured maximum depth.
        max_depth: u32,
    },

    /// The identity is malformed or fails structural validation.
    ///
    /// This covers cases like missing DID fields, invalid document structure,
    /// or inconsistent lineage sections.
    #[error("invalid identity: {reason}")]
    InvalidIdentity {
        /// A description of the structural problem.
        reason: String,
    },

    /// Saving or loading an identity to/from persistent storage failed.
    ///
    /// This may indicate I/O errors, permission problems, or corrupted
    /// identity files on disk.
    #[error("identity persistence failed: {reason}")]
    PersistenceFailed {
        /// A description of the persistence failure.
        reason: String,
    },

    /// An error propagated from the underlying OAS SDK.
    ///
    /// This wraps [`oas_sdk::OasError`] for seamless `?` propagation
    /// from OAS SDK calls within forge-identity functions.
    #[error("OAS SDK error: {0}")]
    Oas(#[from] oas_sdk::OasError),
}

pub type ForgeIdentityResult<T> = Result<T, ForgeIdentityError>;

#[derive(Debug, Error)]
pub enum GlyphError {
    /// The provided DID string is malformed or unparseable.
    #[error("invalid DID '{did}': {reason}")]
    InvalidDid {
        /// The DID string that failed validation.
        did: String,
        /// Why the DID is invalid.
        reason: String,
    },

    /// The entity kind string does not map to a known glyph kind.
    #[error("invalid glyph entity kind '{kind}': expected one of hmr, mhr, enr, agent, org")]
    InvalidKind {
        /// The kind string that was not recognized.
        kind: String,
    },

    /// Payload encoding failed.
    #[error("glyph payload encoding failed for DID '{did}': {reason}")]
    PayloadEncodingFailed {
        /// The DID being encoded.
        did: String,
        /// Why encoding failed.
        reason: String,
    },

    /// Rendering the glyph to the requested output format failed.
    #[error("glyph render failed: {reason}")]
    RenderFailed {
        /// Why rendering failed.
        reason: String,
    },
}

pub type GlyphResult<T> = Result<T, GlyphError>;

pub mod error;

pub mod palette;

pub mod payload;

pub mod render;

pub use error::{GlyphError, GlyphResult};

pub use palette::{GlyphColor, GlyphPalette};

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GlyphDescriptor {
/// The agent's DID string (e.g. `did:oas:l1fe:agent:data-analyst`).

pub did: String,
/// The entity kind that determines the kind-region visual motif.

pub kind: GlyphEntityKind,
/// Optional human-readable label rendered below the glyph.

pub label: Option<String>
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum GlyphEntityKind {
    /// Human Root identity.
    Hmr,
    /// Multi-Human Root identity.
    Mhr,
    /// Entity Root identity (organizations, services, etc.).
    Enr,
    /// Agent identity.
    Agent,
    /// Organization identity.
    Org,
}

pub fn parse_kind(s: &str) -> Option<Self>;

pub fn as_str(&self) -> &'static str;

pub fn as_u8(&self) -> u8;

pub fn from_u8(v: u8) -> Option<Self>;

#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum GlyphRenderTarget {
    /// SVG output for web rendering.
    Web,
    /// ANSI-colored terminal output.
    Terminal,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GlyphRenderOptions {
/// The render target (Web or Terminal).

pub target: GlyphRenderTarget,
/// Desired width in pixels (Web) or columns (Terminal). Defaults to 512/12.

pub width: Option<u32>,
/// Desired height in pixels (Web) or rows (Terminal). Defaults to 512/6.

pub height: Option<u32>,
/// Optional background color override. If `None`, the palette-derived

/// background is used.

pub color_override: Option<palette::GlyphColor>
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum GlyphRenderFormat {
    /// Self-contained SVG XML string.
    Svg,
    /// PNG image bytes.
    Png,
    /// ASCII art (plain text).
    AsciiArt,
    /// Braille dot pattern.
    Braille,
    /// ANSI half-block characters.
    HalfBlock,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GlyphRenderResult {
/// The output format.

pub format: GlyphRenderFormat,
/// The rendered data bytes.

pub data: Vec<u8>,
/// Width of the rendered output (pixels for SVG/PNG, columns for terminal).

pub width: u32,
/// Height of the rendered output (pixels for SVG/PNG, rows for terminal).

pub height: u32
}

pub fn svg_data(&self) -> Option<String>;

#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct GlyphColor {
/// Red channel (0-255).

pub r: u8,
/// Green channel (0-255).

pub g: u8,
/// Blue channel (0-255).

pub b: u8
}

pub fn rgb(r: u8, g: u8, b: u8) -> Self;

pub fn to_hex(&self) -> String;

pub fn lerp(a: &GlyphColor, b: &GlyphColor, t: f64) -> Self;

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GlyphPalette {
/// Primary identity color.

pub primary: GlyphColor,
/// Secondary identity color (hue-offset from primary).

pub secondary: GlyphColor,
/// Accent color for kind region and highlights.

pub accent: GlyphColor,
/// Background color (dark, desaturated primary).

pub background: GlyphColor
}

pub fn derive_palette(payload: &[u8], kind: GlyphEntityKind) -> GlyphPalette;

pub fn derive_palette_from_did(did: &str, kind: GlyphEntityKind) -> GlyphPalette;

pub const GLYPH_VERSION: u8;

pub const PAYLOAD_SIZE: usize;

pub fn encode_did_payload(did: &str) -> GlyphResult<Vec<u8>>;

pub fn verify_payload_checksum(payload: &[u8]) -> bool;

pub fn extract_version(payload: &[u8]) -> Option<u8>;

pub fn extract_kind(payload: &[u8]) -> Option<GlyphEntityKind>;

pub fn render_glyph(
    descriptor: &GlyphDescriptor,
    options: &GlyphRenderOptions,
) -> GlyphResult<GlyphRenderResult>;

pub mod agent_identity;

pub mod error;

pub mod glyph;

pub mod lineage;

pub mod local_dev;

pub mod persistence;

pub mod prelude;

pub use crate::agent_identity::ForgeAgentIdentity;

pub use crate::error::{ForgeIdentityError, ForgeIdentityResult};

pub use crate::lineage::{
        create_hmr_identity, create_mhr_identity, derive_agent_identity, verify_lineage_chain,
        DEFAULT_MAX_LINEAGE_DEPTH,
    };

#[allow(deprecated)]
pub use crate::persistence::{load_identity, save_identity};

pub const DEFAULT_MAX_LINEAGE_DEPTH: u32;

pub fn create_hmr_identity(
    namespace: &str,
    identifier: &str,
) -> ForgeIdentityResult<ForgeAgentIdentity>;

pub fn create_hmr_with_seed(
    namespace: &str,
    identifier: &str,
    seed_bytes: &[u8; 32],
) -> ForgeIdentityResult<ForgeAgentIdentity>;

pub fn create_mhr_with_seed(
    namespace: &str,
    identifier: &str,
    seed_bytes: &[u8; 32],
) -> ForgeIdentityResult<ForgeAgentIdentity>;

pub fn create_mhr_identity(
    namespace: &str,
    identifier: &str,
) -> ForgeIdentityResult<ForgeAgentIdentity>;

pub fn derive_agent_identity(
    parent: &ForgeAgentIdentity,
    name: &str,
    namespace: &str,
) -> ForgeIdentityResult<ForgeAgentIdentity>;

pub fn verify_lineage_chain(
    identity: &ForgeAgentIdentity,
    provider: &dyn DocumentProvider,
    config: &VerifyConfig,
) -> ForgeIdentityResult<VerifyResult>;

pub const FORGE_DEV_METHOD: &str;

pub fn forge_dev_did(machine_id: &str, kind: &str, identifier: &str) -> String;

#[cfg(not(target_arch = "wasm32"))]
pub fn derive_machine_id(profile_name: &str) -> String;

#[cfg(target_arch = "wasm32")]
pub fn derive_machine_id(profile_name: &str) -> String;

pub fn derive_machine_id_from_parts(hostname: &str, username: &str, profile_name: &str) -> String;

pub fn validate_forge_dev_did(did: &str) -> ForgeIdentityResult<()>;

pub mod did;

pub mod persistence;

pub struct LocalDevProfile {

}

pub struct ForgeDevIdentity {

}

pub fn did(&self) -> &str;

pub fn kind(&self) -> &str;

pub fn lineage_depth(&self) -> u32;

pub fn inner(&self) -> &ForgeAgentIdentity;

pub fn into_inner(self) -> ForgeAgentIdentity;

pub fn org_id(&self) -> &str;

pub fn created_at(&self) -> &str;

pub fn schema_version(&self) -> u32;

pub fn sign(&self, message: &[u8]) -> Vec<u8>;

pub fn verifying_key_bytes(&self) -> [u8; 32];

#[derive(Debug, Clone)]
pub struct LocalOrg {

}

pub fn new(name: impl Into<String>) -> Self;

pub fn id(&self) -> &str;

pub fn name(&self) -> &str;

#[cfg(not(target_arch = "wasm32"))]
pub fn load_or_create_default() -> ForgeIdentityResult<Self>;

#[cfg(not(target_arch = "wasm32"))]
pub fn load_or_create(profile_name: &str) -> ForgeIdentityResult<Self>;

pub fn root(&self) -> &ForgeDevIdentity;

pub fn org(&self) -> &LocalOrg;

pub fn machine_id(&self) -> &str;

pub fn profile_name(&self) -> &str;

pub fn storage_path(&self) -> &std::path::Path;

pub fn agent_count(&self) -> usize;

#[cfg(not(target_arch = "wasm32"))]
pub fn agent_identity(&mut self, agent_name: &str) -> ForgeIdentityResult<&ForgeDevIdentity>;

#[cfg(not(target_arch = "wasm32"))]
pub fn save(&self) -> ForgeIdentityResult<()>;

pub const PROFILE_SCHEMA_VERSION: u32;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersistedProfile {
/// Schema version for forward compatibility.

pub schema_version: u32,
/// ISO 8601 timestamp of when the profile was first created.

pub created_at: String,
/// The profile name (e.g., `"default"`, `"alice"`).

pub profile_name: String,
/// The 16-character hex machine identifier.

pub machine_id: String,
/// The root identity data.

pub root: PersistedDevIdentity,
/// The local organization context.

pub org: PersistedOrg,
/// Cached agent identities, keyed by agent name.

pub agents: BTreeMap<String, PersistedDevIdentity>
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersistedDevIdentity {
/// The `did:forge-dev:...` identifier string.

pub did: String,
/// The entity kind (e.g., `"mhr"`, `"agent"`).

pub kind: String,
/// The 32-byte Ed25519 signing key, hex-encoded.

pub signing_key_hex: String,
/// The full OAS Identity Document serialized as a JSON string.

pub document_json: String,
/// The number of derivation steps from root.

pub lineage_depth: u32,
/// The org ID this identity belongs to.

pub org_id: String,
/// ISO 8601 timestamp of when this identity was created.

pub created_at: String
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersistedOrg {
/// The org identifier (e.g., `"forge-dev-org:local"`).

pub id: String,
/// The org display name.

pub name: String
}

#[cfg(not(target_arch = "wasm32"))]
pub fn default_profile_path() -> ForgeIdentityResult<PathBuf>;

#[cfg(not(target_arch = "wasm32"))]
pub fn named_profile_path(profile_name: &str) -> ForgeIdentityResult<PathBuf>;

#[cfg(not(target_arch = "wasm32"))]
pub fn save_profile(profile: &PersistedProfile, path: &Path) -> ForgeIdentityResult<()>;

#[cfg(not(target_arch = "wasm32"))]
pub fn load_profile(path: &Path) -> ForgeIdentityResult<PersistedProfile>;

#[deprecated(
    since = "0.2.0",
    note = "Persists signing key in plaintext. Use an encrypted persistence backend \
            (e.g., AES-256-GCM + Argon2id) for production workloads. \
            See L1F-570 for the encrypted persistence follow-up."
)]
pub fn save_identity(identity: &ForgeAgentIdentity, path: &Path) -> ForgeIdentityResult<()>;

pub fn load_identity(path: &Path) -> ForgeIdentityResult<ForgeAgentIdentity>;