Reference · HexaEight.Bridge · 1.0.0-preview12

.NET Bridge API Reference

Every HexaEight SDK — Node, Python, Browser — wraps this .NET package. The surface documented here is the canonical one; language wrappers expose the same names with idiomatic adjustments (camelCase in JS/TS, snake_case in Python).

Class Client

Single entry point. Constructing it loads your identity and authenticates to the platform.

using HexaEight.Bridge;

var client = new Client();
// Identity is now loaded. All subsequent calls are scoped to this identity.

Identity properties

How identity is loaded

The Bridge looks for credentials in this order, stopping at the first hit:

1. Azure mode: If hexaeightkeys.db exists in the current working directory, the Bridge reads the login token from the SQLite settings.logintoken row.
2. Environment variable: If HEXAEIGHT_MACHINETOKEN is set in the process environment.
3. Env-file: If env-file exists in the current working directory with a HEXAEIGHT_MACHINETOKEN=… line.

The Bridge is read-only with respect to your environment — it never sets or modifies environment variables on your behalf.

Sessioned envelope round-trip

The supported two-party flow. Alice and Bob each fetch their half of the ASK pair, pin it under a shared sessionId, and exchange ciphertext.

// ── Alice (sender) ──────────────────────────────────────────
var alice = new Client();
string bobName   = "bob.example.com";
string sessionId = Guid.NewGuid().ToString();   // share with Bob out-of-band
long   kgt       = CurrentKgt();

string askForBob = await alice.FetchAskAsync(bobName, kgt);
alice.PinAskForSession(sessionId, askForBob);

string envelope = await alice.EncryptEnvelopeAsync(
    recipient: bobName,
    body:      "Hello Bob!",
    sessionId: sessionId);
// send envelope to Bob over any transport

// ── Bob (recipient) ─────────────────────────────────────────
var bob = new Client();
string aliceName = "alice.example.com";

string askForAlice = await bob.FetchAskAsync(aliceName, kgt);  // Bob's half
bob.PinAskForSession(sessionId, askForAlice);

DecryptedEnvelope msg = await bob.DecryptEnvelopeAsync(envelope);

// msg.Sender      == "alice.example.com"  (cryptographically verified, not from wire)
// msg.Body        == "Hello Bob!"
// msg.FromSession == true

kgt is the current 15-minute window — see KGT.

Envelope methods

EncryptEnvelopeAsync

Task<string> EncryptEnvelopeAsync(
    string recipient,
    string body,
    long?   kgt       = null,
    string? pinAsk    = null,
    string? sessionId = null)

Encrypts a string body into a single envelope string.

Returns: envelope string (Variant B when sessionId is set), or empty string on failure.

DecryptEnvelopeAsync

Task<DecryptedEnvelope> DecryptEnvelopeAsync(
    string envelope,
    string? pinAsk = null)

Auto-detects the envelope variant by the hsha: prefix.

InspectEnvelope (static)

static InspectedEnvelope InspectEnvelope(string envelope)

Parses the wire format only — no decryption, no platform call. Use it for cheap deny-list filtering before paying the decryption cost.

ASK cache

FetchAskAsync

Task<string> FetchAskAsync(string recipient, long? kgt = null)

Returns the cached ASK if present, otherwise fetches from the platform and caches as non-pinned. kgt defaults to the current 15-min window.

PinAsk / PinAskForSession

void PinAsk(string recipient, long kgt, string ask)
void PinAskForSession(string sessionId, string ask)

Marks an ASK entry as pinned so it survives auto-eviction. PinAskForSession stores it under sha256(sessionId) so subsequent EncryptEnvelopeAsync/DecryptEnvelopeAsync calls with the same sessionId reuse it.

UnpinAsk / UnpinAskForSession

void UnpinAsk(string recipient, long kgt)
void UnpinAskForSession(string sessionId)

Removes a cache entry.

HasCachedAsk / HasCachedSession

bool HasCachedAsk(string recipient, long kgt)
bool HasCachedSession(string sessionId)

Test cache presence without triggering a fetch.

ClearAskCache

void ClearAskCache()

Wipes the entire ASK cache, both recipient-keyed and session-keyed entries.

Persistence

SaveAskCacheToDiskAsync / LoadAskCacheFromDiskAsync

Task SaveAskCacheToDiskAsync(string filePath)
Task LoadAskCacheFromDiskAsync(string filePath)

Serialize/deserialize the cache as JSON. The file contains ASK material in plaintext — protect it with OS-level permissions (chmod 600, restricted ACL on Windows). Load merges entries into the in-memory cache without overwriting; call ClearAskCache() first if you want a clean load.

EnableAutoPersistAsync / DisableAutoPersist

Task EnableAutoPersistAsync(string filePath, bool loadIfExists = true)
void DisableAutoPersist()

Every cache mutation triggers a 2-second-debounced async write to filePath. If loadIfExists is true and the file exists, it's loaded synchronously first. DisableAutoPersist performs a final synchronous flush.

Records and enums

Encrypted JWT (handshake / identity assertion)

Used for the JWT handshake — first message that proves the sender's identity, shares a session identifier, and optionally carries a body. After the handshake, switch to Sessioned envelopes for steady-state messaging.

AddPayloadItem

bool AddPayloadItem(string key, object value)

Attach a custom claim to the next JWT. The custom claim becomes part of the encrypted payload alongside the standard claims (iss, aud, iat, nbf, exp, signingkeyhash). Use for message bodies, session identifiers, or any other tamper-protected metadata.

ClearAllPayloadItems

bool ClearAllPayloadItems()

Remove every claim (standard + custom) from the pending payload.

ViewPayloadString

string ViewPayloadString()

Return the pending payload as JSON for inspection. Diagnostic only.

CreateEncryptedJwtTokenUsingSharedKeyAsync

Task<string> CreateEncryptedJwtTokenUsingSharedKeyAsync(
    string audience, int expiryMinutes, long kgt, string sharedKey)

Produce a HexaEight-encrypted JWT. The JWT's plaintext header includes issuer (sender's Name) and kgt — the receiver can read both with zero crypto and use them to look up the right ASK. The payload is DDE-encrypted under sharedKey. Signature is HS256 over a random key that is itself DDE-encrypted in the kid header field.

ValidateTokenUsingSharedKeyAsync

Task<string> ValidateTokenUsingSharedKeyAsync(string token, string sharedKey)

Verify the HS256 signature and decrypt the payload. Returns the claims JSON on success, or a string starting with "-" on failure. The iss claim in the returned JSON is the cryptographically guaranteed sender identity — always trust this rather than the plaintext header.

License sizing (preview12+)

CpuCoreInfoAsync

Task<CpuCoreInfo> CpuCoreInfoAsync()

Pure local hardware probe. Returns the host's CPU and core count so callers can size their HexaEight license before activating an identity. Does NOT touch the license file or make any platform call.

Mirrors the --cpucores flag of the canonical HexaEight-Machine-Tokens-Utility.

Returns: CpuCoreInfo(int CpuCount, int CoreCount). Both fields are 0 if the underlying Hardware.Info probe throws — e.g. System.Management unavailable on Windows under a hosted CLR like node-api-dotnet (see #479). On native .NET (any platform) and on Linux/Mac under hosted CLR, the values are populated correctly.

Lower-level methods

For protocol-level integration. Most apps should use the envelope methods above.

Error handling

• InvalidOperationException — ASK fetch failed, decryption returned empty, or sessioned envelope has no cached ASK for the session.
• FormatException — malformed envelope.
• FileNotFoundException — LoadAskCacheFromDiskAsync called on a missing file.
• ArgumentNullException — null/empty path passed to a persistence method.

Threading and async

Every async method is implemented as Task.Run over the underlying synchronous HexaEight library. This sidesteps the JSSynchronizationContext deadlock when called from Node.js via node-api-dotnet. You can safely await from any sync context.

Performance characteristics

Above 250 MB plaintext, host process memory pressure dominates; streaming support is planned.

See also

• Quickstart
• Two-party example
• Multi-party example
• Sessioned messages guide
• Wire format spec
• Flat-text mirror of this reference (for AI agents)