ksecuremessage-core-model/dev.kreienbuehl.ksecuremessage.model

Package-level declarations

Types

CiphertextMessage

@Serializable

sealed interface CiphertextMessage

Output of ProtocolEngine.encrypt, input of ProtocolEngine.decrypt.

DeviceAddress

@Serializable

data class DeviceAddress(val userId: UserId, val deviceId: DeviceId)

DeviceAuthenticationRegistrationStatus

data class DeviceAuthenticationRegistrationStatus(val authEpoch: Long, val authKeyInstalledAt: Instant)

The server's registration metadata of a device's authoritative device authentication key (docs/device-authentication-rotation.md), as returned by the signed GET /v1/devices/{user}/{device}/registration.

DeviceId

@Serializable

@JvmInline

value class DeviceId(val value: String)

DeviceRegistration

class DeviceRegistration(val address: DeviceAddress, publicKey: ByteArray)

Binds address to the public half of that device's authentication key (docs/server-authentication.md). The server verifies the device's authenticated requests with publicKey. Public data only.

EncryptedEnvelope

@Serializable

data class EncryptedEnvelope(val id: MessageId, val sender: DeviceAddress, val recipient: DeviceAddress, val protocolVersion: Int = 1, val payload: ByteArray)

Transport envelope. The payload stays opaque to the server.

InboundFinalization

enum InboundFinalization : Enum<InboundFinalization>

The terminal outcome of a received logical message (docs/message-discard.md). A pending message becomes exactly one of these, once, by an explicit application call; the outcome never changes afterwards.

LastDeviceRecoveryKeyStatus

sealed interface LastDeviceRecoveryKeyStatus

The server's state of a user's offline last-device recovery key (docs/recovery-key-lifecycle.md), as returned to a registered device of the user by the signed GET /v1/devices/{user}/{device}/last-device-recovery/key.

LogicalMessageId

@JvmInline

value class LogicalMessageId(val uuid: Uuid)

KSecureMessage-owned identifier of one logical application message (docs/message-reliability.md). 128 random bits chosen by the sending device. It travels inside the encrypted payload, never in the envelope, and stays the same when the message is encrypted again for a resend. Only meaningful together with the sender's DeviceAddress: two devices may pick the same value for unrelated messages.

MessageDiscardReason

enum MessageDiscardReason : Enum<MessageDiscardReason>

Why the application discarded a received message (docs/message-discard.md). A closed set of codes, deliberately not free text: it is stored unencrypted as local metadata and never sent to the sender. Use it for permanent decisions only; a temporary failure should leave the message pending.

MessageId

@Serializable

@JvmInline

value class MessageId(val value: String)

ID of one EncryptedEnvelope: one transport attempt. A logical message that is sent again gets a new envelope with a new MessageId but keeps its LogicalMessageId.

OneTimePreKeyId

@Serializable

@JvmInline

value class OneTimePreKeyId(val value: Int)

KSecureMessage-owned identifier of a one-time prekey. Separate ID space from SignedPreKeyId. Used to find and then delete the consumed private key. Range 0..Int.MAX_VALUE, like SignedPreKeyId.

PreKeyBundle

@Serializable

data class PreKeyBundle(val address: DeviceAddress, val identityKey: ByteArray, val signedPreKey: PublicSignedPreKey, val oneTimePreKey: PublicOneTimePreKey? = null)

Public data published by a device for asynchronous session establishment. Byte arrays intentionally avoid exposing Kodium-specific key types in the public KSecureMessage model.

PreKeyMessage

@Serializable

data class PreKeyMessage(val identityKey: ByteArray, val ephemeralKey: ByteArray, val signedPreKeyId: SignedPreKeyId, val oneTimePreKeyId: OneTimePreKeyId?, val message: RatchetMessage, val initiationVersion: SessionInitiationVersion = SessionInitiationVersion.V2) : CiphertextMessage

A ratchet message plus the X3DH data the recipient needs to create its side of the session.

PreKeyPublication

@Serializable

data class PreKeyPublication(val address: DeviceAddress, val identityKey: ByteArray, val signedPreKey: PublicSignedPreKey, val oneTimePreKeys: List<PublicOneTimePreKey>)

Public prekey material a device uploads to the server: its identity key, its current signed prekey and a batch of one-time prekeys.

PublicOneTimePreKey

@Serializable

data class PublicOneTimePreKey(val id: OneTimePreKeyId, val publicKey: ByteArray)

Public half of a one-time prekey. Each one should be handed out at most once.

PublicSignedPreKey

@Serializable

data class PublicSignedPreKey(val id: SignedPreKeyId, val publicKey: ByteArray, val signature: ByteArray)

Public half of a signed prekey. signature is the identity key's detached signature over publicKey; initiators must reject bundles where it does not verify.

RatchetMessage

@Serializable

data class RatchetMessage(val bytes: ByteArray) : CiphertextMessage

A Double Ratchet message on an established session. bytes is opaque: ratchet header plus authenticated ciphertext.

RecoveryKeyResetId

class RecoveryKeyResetId(bytes: ByteArray)

Server-chosen identifier of one pending recovery key reset (docs/recovery-key-reset.md): 16 cryptographically random bytes. Not secret, but never printed by toString. The canonical text form encode is Base64url without padding (22 characters).

RecoveryKeyResetStatus

sealed interface RecoveryKeyResetStatus

The pending delayed reset of a user's offline recovery key (docs/recovery-key-reset.md), as returned to a registered device of the user by the signed GET …/last-device-recovery/key/reset, or to the holder of the current recovery key by the recovery-key-signed status query.

SessionInitiationVersion

@Serializable

enum SessionInitiationVersion : Enum<SessionInitiationVersion>

Session initiation format (docs/session-lifecycle.md, S1 in docs/security-review-remediation.md).

SignedPreKeyId

@Serializable

@JvmInline

value class SignedPreKeyId(val value: Int)

KSecureMessage-owned identifier of a signed prekey. Chosen by the owning device; used to select the matching private key when a PreKeyMessage arrives and, later, for rotation. Range 0..Int.MAX_VALUE: the wire format encodes it as 32 bits with the high bit clear.

UserId

@Serializable

@JvmInline

value class UserId(val value: String)