Concept

Envelopes

An envelope is the unit of communication in HexaEight. The currently supported variant — Sessioned (Variant B) — carries no sender identity on the wire. The recipient identifies the sender from a cryptographically verified field inside the encrypted payload.

Variant B — Sessioned (supported)

hsha:{sha256(sessionId)}|{ciphertext}

Field	Meaning
`hsha:`	Literal 5-byte prefix. Identifies a Sessioned envelope.
`sha256(sessionId)`	SHA-256 hash of the session identifier, lowercase hex (64 chars). Only the participants can map this hash back to their cached ASK.
`ciphertext`	MQ-V4 ciphertext with embedded HMAC-SHA256 integrity tag, Base64URL encoded.

How the recipient learns the sender

The wire envelope carries no sender identity. But the inner JSON that lives inside the ciphertext does — the underlying cipher writes the sender's cryptographically verified Name into a SENDER field as part of encryption. DecryptEnvelopeAsync exposes this as DecryptedEnvelope.Sender.

var msg = await client.DecryptEnvelopeAsync(envelope);
Console.WriteLine(msg.Sender);   // "alice.example.com" — cryptographically verified
Console.WriteLine(msg.Body);     // plaintext
Console.WriteLine(msg.FromSession); // true

This is the trustworthy field. An attacker cannot forge it without breaking the V4 trapdoor and the HMAC simultaneously.

Bootstrapping a session

Two parties (Alice and Bob) need three things in agreement before they can talk:

Each other's Name — the HEXAEIGHT_RESOURCENAME string. Exchange this via your application's normal contact/registry channel.
A sessionId — any unique string, typically a UUID. One party generates it; the other receives it (out of band — over the same channel they used for names, or via an explicit handshake message).
Their half of the ASK pair — Alice calls FetchAskAsync("bob", kgt); Bob calls FetchAskAsync("alice", kgt). The platform issues each side their complementary half.

Each side then pins its ASK to the session and exchanges Sessioned envelopes — the wire never reveals who is talking to whom.

Inspection without decryption

To check whether an incoming string is a HexaEight envelope (and which variant) without paying the decrypt cost:

var inspected = Client.InspectEnvelope(envelope);

if (inspected.Kind == EnvelopeKind.Sessioned)
{
    Console.WriteLine($"Sessioned, hash {inspected.SessionHash}");
}

For Sessioned envelopes, inspection reveals only the session hash — not the sender. The hash by itself is meaningless without the session secret.

What is NOT on the wire

Sender identity — not on the wire. Cryptographically asserted inside the encrypted payload as Sender.
Recipient identity — not on the wire. The recipient discovers a message is for them by being able to decrypt it.
The ASK key — never transmitted. The platform issues complementary halves to each party.
The session secret — only the SHA-256 hash leaves the device.

Variant A — Standard (preview, not yet recommended)

The wire format {sourceId}|{kgt}|{ciphertext} exists in the API surface but is currently in preview. The sourceId field depends on the sender's login-token format and does not yet round-trip reliably across all identity types. Anonymous-sender mode (where the sender is not identified at all) is coming soon — for now, use Sessioned envelopes between known parties.