com.l1fe.forge:forge-identity

import com.l1fe.forge.identity.*

public interface CryptoBridge

public fun generateKeypair(): Pair<String, String>

/**
* Derive a child keypair from a parent using HKDF-SHA256.
*
* @param parentPrivateKeyHex The parent's private key in hex.
* @param derivationPath The derivation path string.
* @return A pair of (childPublicKeyHex, childPrivateKeyHex).
*/
public fun deriveChildKeypair(
parentPrivateKeyHex: String,
derivationPath: String,
): Pair<String, String>

/**
* Sign a message with an Ed25519 private key.
*
* @param messageBytes The message bytes to sign.
* @param privateKeyHex The private key in hex.
* @return The signature bytes in hex.
*/
public fun sign(messageBytes: ByteArray, privateKeyHex: String): String

/**
* Verify an Ed25519 signature.
*

public fun deriveChildKeypair(
parentPrivateKeyHex: String,
derivationPath: String,
): Pair<String, String>

/**
* Sign a message with an Ed25519 private key.
*
* @param messageBytes The message bytes to sign.
* @param privateKeyHex The private key in hex.
* @return The signature bytes in hex.
*/
public fun sign(messageBytes: ByteArray, privateKeyHex: String): String

/**
* Verify an Ed25519 signature.
*
* @param messageBytes The original message bytes.
* @param signatureHex The signature in hex.
* @param publicKeyHex The public key in hex.
* @return `true` if the signature is valid.
*/
public fun verify(messageBytes: ByteArray, signatureHex: String, publicKeyHex: String): Boolean
}

/**

public fun sign(messageBytes: ByteArray, privateKeyHex: String): String

/**
* Verify an Ed25519 signature.
*
* @param messageBytes The original message bytes.
* @param signatureHex The signature in hex.
* @param publicKeyHex The public key in hex.
* @return `true` if the signature is valid.
*/
public fun verify(messageBytes: ByteArray, signatureHex: String, publicKeyHex: String): Boolean
}

/**
* A verification method entry in the OAS document.
*
* @property id The verification method ID.
* @property type The verification method type (e.g., "Ed25519VerificationKey2020").
* @property controller The DID of the controller.
* @property publicKeyHex The public key in hex encoding.
*/
@Serializable
public data class VerificationMethod(
val id: String,
val type: String;

public fun verify(messageBytes: ByteArray, signatureHex: String, publicKeyHex: String): Boolean
}

/**
* A verification method entry in the OAS document.
*
* @property id The verification method ID.
* @property type The verification method type (e.g., "Ed25519VerificationKey2020").
* @property controller The DID of the controller.
* @property publicKeyHex The public key in hex encoding.
*/
@Serializable
public data class VerificationMethod(
val id: String,
val type: String;

public data class VerificationMethod(
val id: String,
val type: String;

public data class LineageProof(
@SerialName("parent_did")
val parentDid: String,
@SerialName("child_did")
val childDid: String,
@SerialName("derivation_path")
val derivationPath: String,
val signature: String,
val timestamp: Timestamp,
)

/**
* The lineage section of an OAS document.
*
* @property proofs The ordered list of lineage proofs from root to this agent.
* @property depth The depth of this agent in the lineage chain.
*/
@Serializable
public data class LineageSection(
val proofs: List<LineageProof>,
val depth: Int,
)

/**
* A simplified OAS document for the agent.
*

public data class LineageSection(
val proofs: List<LineageProof>,
val depth: Int,
)

/**
* A simplified OAS document for the agent.
*
* @property id The agent's DID.
* @property verificationMethods The agent's verification methods.
* @property lineage The lineage section.
* @property created When the document was created.
*/
@Serializable
public data class OasDocument(
val id: String,
@SerialName("verification_methods")
val verificationMethods: List<VerificationMethod>,
val lineage: LineageSection,
val created: Timestamp,
)

/**
* An agent's complete cryptographic identity.
*
* Contains the OAS DID, keypair (managed via [CryptoBridge]), OAS document,

public data class OasDocument(
val id: String,
@SerialName("verification_methods")
val verificationMethods: List<VerificationMethod>,
val lineage: LineageSection,
val created: Timestamp,
)

/**
* An agent's complete cryptographic identity.
*
* Contains the OAS DID, keypair (managed via [CryptoBridge]), OAS document,
* and lineage chain. The private key is NEVER exposed in toString() or
* any serialized form.
*
* ANVIL Spec Section 11.1
*
* @property did The agent's OAS DID.
* @property publicKeyHex The agent's Ed25519 public key in hex.
* @property document The agent's OAS document.
* @property lineageDepth The depth of this agent in the lineage chain.
*/
public class ForgeAgentIdentity private constructor(
public val did: AgentDid,
public val publicKeyHex: String,
private val privateKeyHex: String,

public class ForgeAgentIdentity private constructor(
public val did: AgentDid,
public val publicKeyHex: String,
private val privateKeyHex: String,
public val document: OasDocument,
public val lineageDepth: Int,
)

public val did: AgentDid,
public val publicKeyHex: String,
private val privateKeyHex: String,
public val document: OasDocument,
public val lineageDepth: Int,
)

public val publicKeyHex: String,
private val privateKeyHex: String,
public val document: OasDocument,
public val lineageDepth: Int,
)

public val document: OasDocument,
public val lineageDepth: Int,
)

public val lineageDepth: Int,
)

public fun sign(message: ByteArray): String

public fun verify(message: ByteArray, signatureHex: String): Boolean

public enum class GlyphEntityKind

public fun asStr(): String;

public fun asU8(): Int;

public fun parseKind(s: String): GlyphEntityKind?;

public fun fromU8(v: Int): GlyphEntityKind?;

public data class GlyphColor(val r: Int, val g: Int, val b: Int)

public fun toHex(): String =

public fun rgb(r: Int, g: Int, b: Int): GlyphColor;

public fun lerp(a: GlyphColor, b: GlyphColor, t: Double): GlyphColor

public data class GlyphPalette(
val primary: GlyphColor,
val secondary: GlyphColor,
val accent: GlyphColor,
val background: GlyphColor,
)

/**
* The glyph input contract: describes what to render.
*
* @property did The agent's DID string.
* @property kind The entity kind that determines the kind-region visual motif.
* @property label Optional human-readable label rendered below the glyph.
*/
@Serializable
public data class GlyphDescriptor(
val did: String,
val kind: GlyphEntityKind,
val label: String?;

public data class GlyphDescriptor(
val did: String,
val kind: GlyphEntityKind,
val label: String?;

public fun derivePaletteFromDid(did: String, kind: GlyphEntityKind): GlyphPalette

public fun renderGlyph(descriptor: GlyphDescriptor): String

public sealed class ForgeIdentityError(
message: String,
cause: Throwable?;

public class DerivationFailed(
public val parentDid: String,
public val path: String,
public val reason: String,
cause: Throwable?;

public val parentDid: String,
public val path: String,
public val reason: String,
cause: Throwable?;

public val path: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class ChainTooDeep(
public val depth: Int,
public val maxDepth: Int,
) : ForgeIdentityError(
"lineage chain depth $depth exceeds ANVIL maximum $maxDepth (ANVIL Spec SS11.2)"
)

/**
* An identity is malformed or invalid.
*
* @property did The DID that is invalid.
* @property reason The validation failure reason.
*/
public class InvalidIdentity(
public val did: String,
public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.

public val depth: Int,
public val maxDepth: Int,
) : ForgeIdentityError(
"lineage chain depth $depth exceeds ANVIL maximum $maxDepth (ANVIL Spec SS11.2)"
)

/**
* An identity is malformed or invalid.
*
* @property did The DID that is invalid.
* @property reason The validation failure reason.
*/
public class InvalidIdentity(
public val did: String,
public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.
*/

public val maxDepth: Int,
) : ForgeIdentityError(
"lineage chain depth $depth exceeds ANVIL maximum $maxDepth (ANVIL Spec SS11.2)"
)

/**
* An identity is malformed or invalid.
*
* @property did The DID that is invalid.
* @property reason The validation failure reason.
*/
public class InvalidIdentity(
public val did: String,
public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.
*/
public class WasmBridgeError(

public class InvalidIdentity(
public val did: String,
public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.
*/
public class WasmBridgeError(
public val operation: String,
public val reason: String,
cause: Throwable?;

public val did: String,
public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.
*/
public class WasmBridgeError(
public val operation: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
) : ForgeIdentityError("invalid identity '$did': $reason")

/**
* The WASM crypto bridge is not available or failed.
*
* Non-Rust languages use the Rust WASM module for all cryptographic
* operations. This error indicates the bridge is missing or broken.
*
* @property operation The operation that failed.
* @property reason The failure reason.
*/
public class WasmBridgeError(
public val operation: String,
public val reason: String,
cause: Throwable?;

public class WasmBridgeError(
public val operation: String,
public val reason: String,
cause: Throwable?;

public val operation: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class PersistenceError(
public val operation: String,
public val reason: String,
cause: Throwable?;

public val operation: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public const val DEFAULT_MAX_LINEAGE_DEPTH: Int;

public fun setCryptoBridge(bridge: CryptoBridge)

public fun getCryptoBridge(): CryptoBridge =

public fun createHmrIdentity(
namespace: String;

public fun createMhrIdentity(
namespace: String;

public fun deriveAgentIdentity(
parent: ForgeAgentIdentity,
agentName: String,
namespace: String;

public const val FORGE_DEV_METHOD: String;

public data class LocalDevProfile(
val machineId: String,
val hostname: String,
val username: String,
val profileName: String,
)

/**
* Constructs a local dev DID string.
*
* Format: `did:forge-dev:<machine-id>:<kind>:<identifier>`
*
* @param machineId The 16-char hex machine identifier from the profile.
* @param kind One of `"mhr"`, `"hmr"`, `"agent"`, `"org"`.
* @param identifier The entity name or derived fingerprint.
* @return The formatted DID string.
*/
public fun forgeDevDid(machineId: String, kind: String, identifier: String): String =

public fun forgeDevDid(machineId: String, kind: String, identifier: String): String =

public fun deriveMachineIdFromParts(hostname: String, username: String, profileName: String): String

public fun deriveMachineId(profileName: String): String

public fun validateForgeDevDid(did: String)

public data class ProtectedPrivateKey(
val scheme: String,
val payload: String,
@SerialName("key_id")
val keyId: String?;

public interface IdentityKeyProtector

public fun protect(privateKeyHex: String): ProtectedPrivateKey

public fun unprotect(protectedPrivateKey: ProtectedPrivateKey): String
}

/**
* A serializable identity envelope for persistence.
*
* Contains all data needed to reconstruct a [ForgeAgentIdentity] without
* storing raw private key material.
*/
@Serializable
internal data class IdentityEnvelope(
@SerialName("format_version")
val formatVersion: Int;

public fun unprotect(protectedPrivateKey: ProtectedPrivateKey): String
}

/**
* A serializable identity envelope for persistence.
*
* Contains all data needed to reconstruct a [ForgeAgentIdentity] without
* storing raw private key material.
*/
@Serializable
internal data class IdentityEnvelope(
@SerialName("format_version")
val formatVersion: Int;

public fun saveIdentity(identity: ForgeAgentIdentity, file: File)

public fun saveIdentity(
identity: ForgeAgentIdentity,
file: File,
protector: IdentityKeyProtector,
)

public fun loadIdentity(file: File): ForgeAgentIdentity

public fun loadIdentity(
file: File,
protector: IdentityKeyProtector,
): ForgeAgentIdentity