@saihm/client-pro

@saihm/client-pro

Client-side envelope cryptography for SAIHM non-custodial memory.

This library performs every cryptographic operation that touches your plaintext or your master secret on the client. SAIHM's runtime stores, anchors, shares, and bills over the resulting ciphertext blind — it never holds your keys and cannot read your memory.

• Post-quantum identity & signing — ML-DSA-65 (FIPS 204).
• Post-quantum authenticated sharing — ML-KEM-768 (FIPS 203), KEM-then-AEAD.
• Per-cell confidentiality — a fresh random AES-256-GCM data-encryption key (DEK) per cell, itself AEAD-wrapped under a client-held key-encryption key (KEK).
• Crypto-shred erasure — because each DEK is random and persisted only in wrapped form on the SAIHM side, destroying that wrapped DEK makes the cell undecryptable (GDPR Art. 17, controller-side).
• Clean-room — built only on @noble primitives (@noble/post-quantum, @noble/ciphers, @noble/hashes). No network, no storage, no platform code.

Key loss is unrecoverable by design. If you lose your master secret (and therefore your KEK), your wrapped DEKs cannot be opened — by you or by anyone, including SAIHM. This is the cost of true non-custody. Back up your master secret securely.

Install

npm install @saihm/client-pro

Usage

import {
  deriveIdentity, sealCell, verifyEnvelope, openCell,
  shareCell, unwrapSharedDek, openCellWithDek, verifyIdentityRecord,
} from '@saihm/client-pro';

// 1. Derive a deterministic identity from a >=32-byte master secret you hold.
const me = deriveIdentity(myMasterSecret);
//  me.agentIdHash      -> your public identifier (= sha256(ML-DSA public key))
//  me.identityRecord   -> publish to SAIHM (public keys + self-signature)
//  me.kek / me.mldsaSecretKey / me.mlkemSecretKey -> NEVER leave this process

// 2. Encrypt a cell. `seq` is the server-issued monotonic counter for this cell.
const env = sealCell({
  plaintext: new TextEncoder().encode('remember this'),
  kek: me.kek, mldsaSecretKey: me.mldsaSecretKey, mldsaPubKey: me.mldsaPubKey,
  agentIdHash: me.agentIdHash, cellId: 'note-1', seq: 1n, tier: 'PRO',
});
// `env` is the blind envelope SAIHM stores. SAIHM can verifyEnvelope(env) but cannot open it.

// 3. Read it back (client-side).
const plaintext = openCell(env, me.kek);

// 4. Share a cell with another agent, authenticated and end-to-end.
//    Pin the recipient's agentIdHash out-of-band; the library rejects directory key-substitution.
verifyIdentityRecord(recipientRecord, recipientAgentIdHash); // throws KeySubstitutionError on tamper
const share = shareCell({
  envelope: env, sharerKek: me.kek, sharerMldsaSecretKey: me.mldsaSecretKey,
  sharerAgentIdHash: me.agentIdHash, recipientRecord, recipientPinnedAgentIdHash: recipientAgentIdHash,
});
// recipient side (the grantee holds its own identity `recipient`; the sharer's ML-DSA public key
// is pinned out-of-band as `sharerPinnedMldsaPubKey` — sharer authentication is mandatory):
const dek = unwrapSharedDek({
  share,
  recipientMlkemSecretKey: recipient.mlkemSecretKey,
  recipientAgentIdHash: recipient.agentIdHash,
  sharerPinnedMldsaPubKey,
});
const shared = openCellWithDek(env, dek);

Security model

Property	Guarantee
Confidentiality vs SAIHM	SAIHM holds ciphertext + wrapped DEKs + public keys only; no key able to decrypt.
Integrity / authenticity	Every envelope is ML-DSA-65-signed over its full contents, including the sequence number.
Anti-replay / rollback	The signed, server-issued monotonic seq is rejected server-side if not strictly increasing.
Tenant isolation	State is namespaced by the public agentIdHash; a different secret yields a different KEK and namespace.
Authenticated sharing	Recipient public keys are pinned out-of-band and checked before any secret is bound to them.
Erasure	Destroying the SAIHM-side wrapped DEK crypto-shreds the cell.

AES-256-GCM wrap operations use random 96-bit nonces under a reused KEK, well within NIST SP 800-38D guidance for realistic per-identity write volumes. ML-DSA signatures are hedged (randomized); they verify deterministically but are not byte-reproducible.

License

Apache-2.0 © SAIHM