(** Cross-signing and device verification.

    This module implements Matrix cross-signing for identity verification:
    - Cross-signing key management (master, self-signing, user-signing keys)
    - Device verification (local trust, cross-signing trust)
    - User identity verification
    - SAS (Short Authentication String) verification protocol

    @see <https://spec.matrix.org/v1.11/client-server-api/#cross-signing> Cross-Signing *)

(** {1 Trust States} *)

(** Local trust state for a device. *)
type local_trust =
  | Verified
  | BlackListed
  | Ignored
  | Unset

val local_trust_to_int : local_trust -> int
(** Convert local trust to int for storage. *)

val local_trust_of_int : int -> local_trust
(** Parse local trust from int. *)

(** Own user identity verification state. *)
type own_identity_state =
  | Never_verified
  | Verification_violation
  | Identity_verified

(** {1 Cross-Signing Key Types} *)

(** Cross-signing key usage. *)
type key_usage =
  | Master
  | Self_signing
  | User_signing

val key_usage_to_string : key_usage -> string
(** Convert key usage to string. *)

val key_usage_of_string : string -> key_usage option
(** Parse key usage from string. *)

(** Public cross-signing key. *)
type cross_signing_pubkey = {
  user_id : Matrix_proto.Id.User_id.t;
  usage : key_usage list;
  keys : (string * string) list;
  signatures : (string * (string * string) list) list;
}

val get_ed25519_key : cross_signing_pubkey -> (string * string) option
(** Extract the first Ed25519 key from a cross-signing key. *)

(** {1 Private Cross-Signing Keys} *)

(** Private key for signing operations. *)
type private_key = {
  public_key : string;
  secret_key : string;
}

(** Private cross-signing identity (holds the private keys). *)
type private_cross_signing_identity = {
  user_id : Matrix_proto.Id.User_id.t;
  mutable master_key : private_key option;
  mutable self_signing_key : private_key option;
  mutable user_signing_key : private_key option;
  mutable shared : bool;
}

val create_private_identity : user_id:Matrix_proto.Id.User_id.t -> private_cross_signing_identity
(** Create a new private cross-signing identity. *)

val generate_ed25519_key : unit -> private_key
(** Generate a new Ed25519 key pair. *)

val generate_cross_signing_keys : private_cross_signing_identity -> unit
(** Generate all cross-signing keys for a user. *)

val sign_with_key : private_key -> string -> (string, string) result
(** Sign data with a private key. *)

(** {1 Cross-Signing Public Keys} *)

(** Master public key. *)
type master_pubkey = {
  key : cross_signing_pubkey;
}

(** Self-signing public key. *)
type self_signing_pubkey = {
  key : cross_signing_pubkey;
}

(** User-signing public key. *)
type user_signing_pubkey = {
  key : cross_signing_pubkey;
}

val pubkey_from_private :
  user_id:Matrix_proto.Id.User_id.t ->
  usage:key_usage ->
  private_key ->
  cross_signing_pubkey
(** Create a public cross-signing key from private key. *)

(** {1 Signature Verification} *)

val verify_signature :
  public_key_b64:string ->
  signature_b64:string ->
  data:string ->
  bool
(** Verify an Ed25519 signature. *)

val canonicalize_json : Jsont.json -> string
(** Canonicalize JSON for signing. *)

val verify_cross_signing_signature :
  signer_key:cross_signing_pubkey ->
  signed_key:cross_signing_pubkey ->
  bool
(** Verify that a cross-signing key is signed by another key. *)

(** {1 Device Verification} *)

(** Device with verification state. *)
type verified_device = {
  user_id : Matrix_proto.Id.User_id.t;
  device_id : Matrix_proto.Id.Device_id.t;
  keys : (string * string) list;
  algorithms : string list;
  display_name : string option;
  mutable local_trust : local_trust;
  mutable cross_signing_trusted : bool;
}

val create_verified_device :
  user_id:Matrix_proto.Id.User_id.t ->
  device_id:Matrix_proto.Id.Device_id.t ->
  keys:(string * string) list ->
  algorithms:string list ->
  ?display_name:string ->
  unit ->
  verified_device
(** Create a verified device from device keys. *)

val is_device_verified : verified_device -> bool
(** Check if a device is verified (locally or via cross-signing). *)

val set_device_local_trust : verified_device -> local_trust -> unit
(** Set local trust state for a device. *)

val verify_device_with_self_signing :
  self_signing_key:self_signing_pubkey ->
  device:verified_device ->
  bool
(** Check if device is signed by a self-signing key. *)

(** {1 User Identity} *)

(** Own user identity. *)
type own_user_identity = {
  user_id : Matrix_proto.Id.User_id.t;
  master_key : master_pubkey;
  self_signing_key : self_signing_pubkey;
  user_signing_key : user_signing_pubkey;
  mutable state : own_identity_state;
}

(** Other user identity. *)
type other_user_identity = {
  user_id : Matrix_proto.Id.User_id.t;
  master_key : master_pubkey;
  self_signing_key : self_signing_pubkey;
  mutable pinned_master_key : master_pubkey option;
  mutable was_previously_verified : bool;
}

(** User identity (own or other). *)
type user_identity =
  | Own of own_user_identity
  | Other of other_user_identity

val identity_user_id : user_identity -> Matrix_proto.Id.User_id.t
(** Get user ID from identity. *)

val is_own_identity_verified : own_user_identity -> bool
(** Check if own identity is verified. *)

val is_other_identity_verified :
  our_user_signing_key:user_signing_pubkey ->
  other_user_identity ->
  bool
(** Check if other user identity is verified by us. *)

val has_identity_changed : other_user_identity -> bool
(** Check if a user's identity has changed since we pinned it. *)

val pin_master_key : other_user_identity -> unit
(** Pin the current master key for future change detection. *)

(** {1 SAS Verification Protocol} *)

(** SAS verification state. *)
type sas_state =
  | Sas_created
  | Sas_started
  | Sas_accepted
  | Sas_keys_exchanged
  | Sas_confirmed
  | Sas_mac_received
  | Sas_done
  | Sas_cancelled of string

(** Short authentication string output. *)
type sas_output =
  | Decimal of int * int * int
  | Emoji of (int * string) list

(** SAS verification methods. *)
type sas_method =
  | Decimal_method
  | Emoji_method

(** SAS verification session. *)
type sas_session = {
  flow_id : string;
  mutable state : sas_state;
  our_user_id : Matrix_proto.Id.User_id.t;
  our_device_id : Matrix_proto.Id.Device_id.t;
  their_user_id : Matrix_proto.Id.User_id.t;
  their_device_id : Matrix_proto.Id.Device_id.t;
  mutable their_public_key : string option;
  mutable our_public_key : string option;
  mutable sas_bytes : string option;
  mutable methods : sas_method list;
}

val generate_flow_id : unit -> string
(** Generate a random flow ID. *)

val create_sas_session :
  our_user_id:Matrix_proto.Id.User_id.t ->
  our_device_id:Matrix_proto.Id.Device_id.t ->
  their_user_id:Matrix_proto.Id.User_id.t ->
  their_device_id:Matrix_proto.Id.Device_id.t ->
  sas_session
(** Create a new SAS verification session. *)

val sas_emoji_table : (int * string) array
(** Standard SAS emoji table. *)

val derive_sas_output : method_type:sas_method -> sas_bytes:string -> sas_output
(** Derive SAS output from shared bytes. *)

val get_sas_output : sas_session -> sas_method -> sas_output option
(** Get SAS output for display. *)

val confirm_sas : sas_session -> unit
(** Confirm SAS match. *)

val cancel_sas : sas_session -> string -> unit
(** Cancel SAS verification. *)

val is_sas_done : sas_session -> bool
(** Check if SAS is complete. *)

(** {1 QR Code Verification} *)

(** QR verification mode. *)
type qr_mode =
  | Self_verifying_master_key_trusts_device
  | Self_verifying_device_trusts_master_key
  | Verifying_another_user

(** QR verification state. *)
type qr_state =
  | Qr_started
  | Qr_scanned
  | Qr_confirmed
  | Qr_reciprocated
  | Qr_done
  | Qr_cancelled of string

(** QR verification data. *)
type qr_verification = {
  flow_id : string;
  mutable state : qr_state;
  mode : qr_mode;
  our_user_id : Matrix_proto.Id.User_id.t;
  their_user_id : Matrix_proto.Id.User_id.t;
  our_master_key : string;
  their_master_key : string option;
  mutable secret : string option;
}

val create_self_qr_verification :
  our_user_id:Matrix_proto.Id.User_id.t ->
  our_master_key:string ->
  mode:qr_mode ->
  qr_verification
(** Create QR verification for self-verification. *)

val create_user_qr_verification :
  our_user_id:Matrix_proto.Id.User_id.t ->
  their_user_id:Matrix_proto.Id.User_id.t ->
  our_master_key:string ->
  their_master_key:string ->
  qr_verification
(** Create QR verification for verifying another user. *)

(** {1 Verification Request} *)

(** Verification request. *)
type verification_request = {
  flow_id : string;
  from_user_id : Matrix_proto.Id.User_id.t;
  to_user_id : Matrix_proto.Id.User_id.t;
  from_device_id : Matrix_proto.Id.Device_id.t option;
  methods : string list;
  timestamp : int64;
  mutable accepted : bool;
  mutable cancelled : bool;
}

val create_verification_request :
  from_user_id:Matrix_proto.Id.User_id.t ->
  to_user_id:Matrix_proto.Id.User_id.t ->
  ?from_device_id:Matrix_proto.Id.Device_id.t ->
  unit ->
  verification_request
(** Create a verification request. *)

val accept_verification_request : verification_request -> unit
(** Accept a verification request. *)

val cancel_verification_request : verification_request -> unit
(** Cancel a verification request. *)

(** {1 Cross-Signing Upload} *)

(** Data needed to upload cross-signing keys. *)
type cross_signing_upload = {
  master_key : cross_signing_pubkey;
  self_signing_key : cross_signing_pubkey;
  user_signing_key : cross_signing_pubkey;
}

val build_cross_signing_upload : private_cross_signing_identity -> cross_signing_upload option
(** Build upload data from private identity. *)