@rine-network/core 0.4.4 → 0.5.1

package/dist/index.js

@@ -4,15 +4,19 @@ import { join } from "node:path";
 import { Aes256Gcm, CipherSuite, HkdfSha256 } from "@hpke/core";
 import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
 import { ed25519, x25519 } from "@noble/curves/ed25519.js";
-import { hmac } from "@noble/hashes/hmac.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { MlsError, acceptAll, clientStateDecoder, clientStateEncoder, createApplicationMessage, createCommit, createGroup, createGroupInfoWithExternalPubAndRatchetTree, decode, defaultCredentialTypes, encode, generateKeyPackageWithKey, getCiphersuiteImpl, joinGroup, joinGroupExternal, keyPackageDecoder, keyPackageEncoder, makeKeyPackageRef, mlsMessageDecoder, mlsMessageEncoder, privateKeyPackageDecoder, privateKeyPackageEncoder, processMessage, processPrivateMessage, protocolVersions, unsafeTestingAuthenticationService, wireformats, zeroOutUint8Array } from "ts-mls";
 //#region src/errors.ts
 var RineApiError = class extends Error {
-	constructor(status, detail, raw) {
+	constructor(status, detail, raw, code) {
 		super(`${status}: ${detail}`);
 		this.status = status;
 		this.detail = detail;
 		this.raw = raw;
+		this.code = code;
 		this.name = "RineApiError";
 	}
 };
@@ -45,9 +49,7 @@ function resolveConfigDir() {
 			mode: 448
 		});
 		return dir;
-	} catch {
-		continue;
-	}
+	} catch {}
 	return candidates[0];
 }
 /** Resolve API URL from environment or default. */
@@ -98,7 +100,9 @@ function cacheToken(configDir, profile, token) {
 		access_token: token.access_token,
 		expires_at: Date.now() / 1e3 + token.expires_in
 	};
-	saveTokenCache(configDir, cache);
+	try {
+		saveTokenCache(configDir, cache);
+	} catch {}
 }
 /**
 * Resolves credentials for a profile. Priority:
@@ -116,13 +120,29 @@ function getCredentialEntry(configDir, profile = "default") {
 }
 //#endregion
 //#region src/http.ts
-async function parseErrorDetail(res) {
+/**
+* Parse an error response body ONCE, extracting both the human-readable detail
+* and the structured error code. The server sends {"error": "<code>", "detail":
+* "..."} for typed errors (e.g. epoch_conflict); callers use `code` to branch.
+*/
+async function parseError(res) {
 	try {
 		const body = await res.json();
-		if (typeof body.detail === "string") return body.detail;
-		if (Array.isArray(body.detail)) return body.detail.map((e) => e.msg).join("; ");
+		const code = typeof body.error === "string" ? body.error : void 0;
+		if (typeof body.detail === "string") return {
+			detail: body.detail,
+			code
+		};
+		if (Array.isArray(body.detail)) return {
+			detail: body.detail.map((e) => e.msg).join("; "),
+			code
+		};
+		return {
+			detail: res.statusText,
+			code
+		};
 	} catch {}
-	return res.statusText;
+	return { detail: res.statusText };
 }
 var HttpClient = class {
 	baseUrl;
@@ -161,8 +181,8 @@ var HttpClient = class {
 		let res = await doFetch();
 		if (res.status === 401 && this.canRefresh) res = await doFetch(true);
 		if (!res.ok) {
-			const detail = await parseErrorDetail(res);
-			throw new RineApiError(res.status, detail, res);
+			const { detail, code } = await parseError(res);
+			throw new RineApiError(res.status, detail, res, code);
 		}
 		if (res.status === 204) return void 0;
 		return res.json();
@@ -191,8 +211,8 @@ var HttpClient = class {
 		const url = qs ? `${apiUrl}${path}?${qs}` : `${apiUrl}${path}`;
 		const res = await fetch(url, { headers: { Accept: "application/json" } });
 		if (!res.ok) {
-			const detail = await parseErrorDetail(res);
-			throw new RineApiError(res.status, detail, res);
+			const { detail, code } = await parseError(res);
+			throw new RineApiError(res.status, detail, res, code);
 		}
 		return res.json();
 	}
@@ -378,6 +398,85 @@ async function open(recipientPrivateKey, encryptedPayload, aad) {
 	return new Uint8Array(await recipient.open(ct, aad));
 }
 //#endregion
+//#region src/crypto/hybrid.ts
+const VERSION_HYBRID = 3;
+const X25519_ENC_SIZE = 32;
+const MLKEM_CT_SIZE = 1088;
+const AES_KEY_SIZE = 32;
+const HKDF_INFO = new TextEncoder().encode("rine.e2ee.v1.hpke-hybrid");
+const GCM_NONCE = new Uint8Array(12);
+/** Copy into a plain ArrayBuffer-backed Uint8Array (required by Web Crypto). */
+function toPlainBuffer$1(src) {
+	const buf = new Uint8Array(src.length);
+	buf.set(src);
+	return buf;
+}
+/** Generate an ML-KEM-768 key pair for post-quantum key encapsulation. */
+function generatePqKeyPair() {
+	const { publicKey, secretKey } = ml_kem768.keygen();
+	return {
+		publicKey,
+		privateKey: secretKey
+	};
+}
+/** HKDF-SHA256 over (classical || pq) shared secrets with hybrid domain separation. */
+function combineSecrets(x25519Shared, mlkemShared) {
+	const ikm = new Uint8Array(x25519Shared.length + mlkemShared.length);
+	ikm.set(x25519Shared, 0);
+	ikm.set(mlkemShared, x25519Shared.length);
+	const key = hkdf(sha256, ikm, void 0, HKDF_INFO, AES_KEY_SIZE);
+	ikm.fill(0);
+	return key;
+}
+async function aesGcm(mode, key, data, aad) {
+	const cryptoKey = await crypto.subtle.importKey("raw", toPlainBuffer$1(key), "AES-GCM", false, [mode]);
+	const params = {
+		name: "AES-GCM",
+		iv: GCM_NONCE
+	};
+	if (aad) params.additionalData = toPlainBuffer$1(aad);
+	const buf = toPlainBuffer$1(data);
+	const out = mode === "encrypt" ? await crypto.subtle.encrypt(params, cryptoKey, buf) : await crypto.subtle.decrypt(params, cryptoKey, buf);
+	return new Uint8Array(out);
+}
+async function sealHybrid(recipientX25519Pk, recipientMlKemPk, innerEnvelope, aad) {
+	const ephSk = x25519.utils.randomSecretKey();
+	const ephPk = x25519.getPublicKey(ephSk);
+	const x25519Shared = x25519.getSharedSecret(ephSk, recipientX25519Pk);
+	const { cipherText: mlkemCt, sharedSecret: mlkemShared } = ml_kem768.encapsulate(recipientMlKemPk);
+	const key = combineSecrets(x25519Shared, mlkemShared);
+	x25519Shared.fill(0);
+	mlkemShared.fill(0);
+	ephSk.fill(0);
+	const ciphertext = await aesGcm("encrypt", key, innerEnvelope, aad);
+	key.fill(0);
+	const out = new Uint8Array(1 + X25519_ENC_SIZE + MLKEM_CT_SIZE + ciphertext.length);
+	out[0] = 3;
+	out.set(ephPk, 1);
+	out.set(mlkemCt, 1 + X25519_ENC_SIZE);
+	out.set(ciphertext, 1 + X25519_ENC_SIZE + MLKEM_CT_SIZE);
+	return out;
+}
+async function openHybrid(recipientX25519Sk, recipientMlKemSk, encryptedPayload, aad) {
+	const headerSize = 1 + X25519_ENC_SIZE + MLKEM_CT_SIZE;
+	if (encryptedPayload.length < headerSize + 1) throw new Error("encrypted payload too short");
+	const version = encryptedPayload[0];
+	if (version !== 3) throw new Error(`unsupported version: 0x${version?.toString(16).padStart(2, "0")}`);
+	const ephPk = encryptedPayload.slice(1, 1 + X25519_ENC_SIZE);
+	const mlkemCt = encryptedPayload.slice(1 + X25519_ENC_SIZE, headerSize);
+	const ciphertext = encryptedPayload.slice(headerSize);
+	const x25519Shared = x25519.getSharedSecret(recipientX25519Sk, ephPk);
+	const mlkemShared = ml_kem768.decapsulate(mlkemCt, recipientMlKemSk);
+	const key = combineSecrets(x25519Shared, mlkemShared);
+	x25519Shared.fill(0);
+	mlkemShared.fill(0);
+	try {
+		return await aesGcm("decrypt", key, ciphertext, aad);
+	} finally {
+		key.fill(0);
+	}
+}
+//#endregion
 //#region src/crypto/sign.ts
 function signPayload(signingPrivateKey, plaintext) {
 	return ed25519.sign(plaintext, signingPrivateKey);
@@ -417,6 +516,8 @@ function decodeEnvelope(data) {
 }
 //#endregion
 //#region src/crypto/keys.ts
+const MLKEM_PUBLIC_KEY_SIZE = 1184;
+const MLKEM_SECRET_KEY_SIZE = 2400;
 function toBase64Url(bytes) {
 	return Buffer.from(bytes).toString("base64url");
 }
@@ -440,7 +541,8 @@ function generateEncryptionKeyPair() {
 function generateAgentKeys() {
 	return {
 		signing: generateSigningKeyPair(),
-		encryption: generateEncryptionKeyPair()
+		encryption: generateEncryptionKeyPair(),
+		pqEncryption: generatePqKeyPair()
 	};
 }
 function signingPublicKeyToJWK(publicKey) {
@@ -462,6 +564,18 @@ function jwkToPublicKey(jwk) {
 	if (key.length !== 32) throw new Error(`Invalid public key: expected 32 bytes, got ${key.length}`);
 	return key;
 }
+function pqPublicKeyToJWK(publicKey) {
+	return {
+		kty: "MLKEM",
+		alg: "ML-KEM-768",
+		x: toBase64Url(publicKey)
+	};
+}
+function jwkToPqPublicKey(jwk) {
+	const key = fromBase64Url(jwk.x);
+	if (key.length !== MLKEM_PUBLIC_KEY_SIZE) throw new Error(`Invalid PQ public key: expected ${MLKEM_PUBLIC_KEY_SIZE} bytes, got ${key.length}`);
+	return key;
+}
 const KID_RE = /^rine:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
 function agentIdFromKid(kid) {
 	const match = KID_RE.exec(kid);
@@ -485,6 +599,22 @@ function saveAgentKeys(configDir, agentId, keys) {
 	const encPath = join(dir, "encryption.key");
 	fs.writeFileSync(encPath, toBase64Url(keys.encryption.privateKey), "utf-8");
 	fs.chmodSync(encPath, 384);
+	if (keys.pqEncryption) {
+		const pqPath = join(dir, "pq_encryption.key");
+		fs.writeFileSync(pqPath, toBase64Url(keys.pqEncryption.privateKey), "utf-8");
+		fs.chmodSync(pqPath, 384);
+	}
+}
+function savePqEncryptionKey(configDir, agentId, pqKeyPair) {
+	validatePathId(agentId, "agent ID");
+	const dir = join(configDir, "keys", agentId);
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const pqPath = join(dir, "pq_encryption.key");
+	fs.writeFileSync(pqPath, toBase64Url(pqKeyPair.privateKey), "utf-8");
+	fs.chmodSync(pqPath, 384);
 }
 function loadAgentKeys(configDir, agentId) {
 	validatePathId(agentId, "agent ID");
@@ -495,7 +625,7 @@ function loadAgentKeys(configDir, agentId) {
 	const encPriv = fromBase64Url(fs.readFileSync(join(dir, "encryption.key"), "utf-8").trim());
 	if (encPriv.length !== 32) throw new Error(`Corrupt encryption key: expected 32 bytes, got ${encPriv.length}`);
 	const encPub = x25519.getPublicKey(encPriv);
-	return {
+	const keys = {
 		signing: {
 			privateKey: sigPriv,
 			publicKey: sigPub
@@ -505,6 +635,16 @@ function loadAgentKeys(configDir, agentId) {
 			publicKey: encPub
 		}
 	};
+	const pqPath = join(dir, "pq_encryption.key");
+	if (fs.existsSync(pqPath)) {
+		const pqPriv = fromBase64Url(fs.readFileSync(pqPath, "utf-8").trim());
+		if (pqPriv.length !== MLKEM_SECRET_KEY_SIZE) throw new Error(`Corrupt PQ key: expected ${MLKEM_SECRET_KEY_SIZE} bytes, got ${pqPriv.length}`);
+		keys.pqEncryption = {
+			privateKey: pqPriv,
+			publicKey: ml_kem768.getPublicKey(pqPriv)
+		};
+	}
+	return keys;
 }
 function validateSigningKey(bytes) {
 	if (bytes.length !== 32) throw new Error(`expected 32 bytes, got ${bytes.length}`);
@@ -728,6 +868,662 @@ async function openGroup(senderKeyStates, encryptedPayload) {
 	};
 }
 //#endregion
+//#region src/crypto/mls-init.ts
+let cachedCs = null;
+let cachedCtx = null;
+let initPromise = null;
+async function ensureInit() {
+	if (cachedCs) return;
+	cachedCs = await getCiphersuiteImpl("MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519");
+	cachedCtx = {
+		cipherSuite: cachedCs,
+		authService: unsafeTestingAuthenticationService
+	};
+}
+/** Lazily initializes and returns the MLS cipher suite singleton. */
+async function getMlsCipherSuite() {
+	if (!initPromise) initPromise = ensureInit();
+	await initPromise;
+	return cachedCs;
+}
+/** Lazily initializes and returns the MLS context singleton. */
+async function getMlsContext() {
+	if (!initPromise) initPromise = ensureInit();
+	await initPromise;
+	return cachedCtx;
+}
+const MLS_CIPHER_SUITE_ID = 1;
+//#endregion
+//#region src/crypto/mls.ts
+const VERSION_MLS = 4;
+function encState(s) {
+	return encode(clientStateEncoder, s);
+}
+function decState(b) {
+	const s = decode(clientStateDecoder, b);
+	if (!s) throw new Error("Failed to decode MLS client state");
+	return s;
+}
+function zeroConsumed(consumed) {
+	for (const c of consumed) zeroOutUint8Array(c);
+}
+function basicCred(publicKey) {
+	return {
+		credentialType: defaultCredentialTypes.basic,
+		identity: publicKey
+	};
+}
+/**
+* Build a fresh, current-epoch GroupInfo blob (with external_pub + ratchet_tree)
+* so a subsequent external joiner can self-join against this group's latest
+* epoch. Single-use per epoch (RFC 9420 §12.4.3.2) — every commit must publish
+* a fresh one or the next external join targets a stale epoch and is rejected.
+*/
+async function freshGroupInfoBlob(state, cs) {
+	const gi = await createGroupInfoWithExternalPubAndRatchetTree(state, [], cs);
+	return encode(mlsMessageEncoder, {
+		wireformat: wireformats.mls_group_info,
+		groupInfo: gi,
+		version: protocolVersions.mls10
+	});
+}
+async function generateMlsKeyPackage(signingKey) {
+	const cs = await getMlsCipherSuite();
+	const publicKey = ed25519.getPublicKey(signingKey);
+	const { publicPackage, privatePackage } = await generateKeyPackageWithKey({
+		credential: basicCred(publicKey),
+		signatureKeyPair: {
+			signKey: signingKey,
+			publicKey
+		},
+		cipherSuite: cs
+	});
+	return {
+		publicBlob: encode(keyPackageEncoder, publicPackage),
+		privateBlob: encode(privateKeyPackageEncoder, privatePackage),
+		keyPackageRef: await makeKeyPackageRef(publicPackage, cs.hash)
+	};
+}
+async function createMlsGroup(signingKey, _cipherSuite) {
+	const cs = await getMlsCipherSuite();
+	const ctx = await getMlsContext();
+	const publicKey = ed25519.getPublicKey(signingKey);
+	const { publicPackage, privatePackage } = await generateKeyPackageWithKey({
+		credential: basicCred(publicKey),
+		signatureKeyPair: {
+			signKey: signingKey,
+			publicKey
+		},
+		cipherSuite: cs
+	});
+	const { newState, commit, consumed } = await createCommit({
+		context: ctx,
+		state: await createGroup({
+			context: ctx,
+			groupId: crypto.getRandomValues(new Uint8Array(16)),
+			keyPackage: publicPackage,
+			privateKeyPackage: privatePackage
+		})
+	});
+	zeroConsumed(consumed);
+	return {
+		stateBlob: encState(newState),
+		groupInfo: await freshGroupInfoBlob(newState, cs),
+		commitBlob: encode(mlsMessageEncoder, commit),
+		epoch: Number(newState.groupContext.epoch)
+	};
+}
+async function addMemberToMlsGroup(stateBlob, keyPackageBlob) {
+	const cs = await getMlsCipherSuite();
+	const ctx = await getMlsContext();
+	const kp = decode(keyPackageDecoder, keyPackageBlob);
+	if (!kp) throw new Error("Failed to decode key package");
+	const { newState, welcome, commit, consumed } = await createCommit({
+		context: ctx,
+		state: decState(stateBlob),
+		extraProposals: [{
+			proposalType: 1,
+			add: { keyPackage: kp }
+		}],
+		ratchetTreeExtension: true
+	});
+	zeroConsumed(consumed);
+	if (!welcome) throw new Error("createCommit produced no welcome for add");
+	return {
+		commitBlob: encode(mlsMessageEncoder, commit),
+		welcomeBlob: encode(mlsMessageEncoder, welcome),
+		updatedState: encState(newState),
+		groupInfo: await freshGroupInfoBlob(newState, cs),
+		epoch: Number(newState.groupContext.epoch)
+	};
+}
+async function removeMemberFromMlsGroup(stateBlob, leafIndex) {
+	const cs = await getMlsCipherSuite();
+	const { newState, commit, consumed } = await createCommit({
+		context: await getMlsContext(),
+		state: decState(stateBlob),
+		extraProposals: [{
+			proposalType: 3,
+			remove: { removed: leafIndex }
+		}]
+	});
+	zeroConsumed(consumed);
+	return {
+		commitBlob: encode(mlsMessageEncoder, commit),
+		updatedState: encState(newState),
+		groupInfo: await freshGroupInfoBlob(newState, cs),
+		epoch: Number(newState.groupContext.epoch)
+	};
+}
+async function processMlsWelcome(welcomeBlob, keyPackageBlob, privateKeyBlob) {
+	const ctx = await getMlsContext();
+	const msg = decode(mlsMessageDecoder, welcomeBlob);
+	if (!msg || msg.wireformat !== wireformats.mls_welcome) throw new Error("Failed to decode MLS welcome message");
+	const kp = decode(keyPackageDecoder, keyPackageBlob);
+	if (!kp) throw new Error("Failed to decode key package for welcome");
+	const pkp = decode(privateKeyPackageDecoder, privateKeyBlob);
+	if (!pkp) throw new Error("Failed to decode private key package for welcome");
+	const state = await joinGroup({
+		context: ctx,
+		welcome: msg.welcome,
+		keyPackage: kp,
+		privateKeys: pkp
+	});
+	return {
+		stateBlob: encState(state),
+		groupId: new TextDecoder().decode(state.groupContext.groupId),
+		epoch: Number(state.groupContext.epoch),
+		cipherSuite: state.groupContext.cipherSuite
+	};
+}
+async function processMlsCommit(stateBlob, commitBlob) {
+	const ctx = await getMlsContext();
+	const msg = decode(mlsMessageDecoder, commitBlob);
+	if (!msg) throw new MlsError("Failed to decode MLS commit message");
+	if (msg.wireformat !== wireformats.mls_private_message && msg.wireformat !== wireformats.mls_public_message) throw new MlsError(`Unexpected wireformat for commit: ${msg.wireformat}`);
+	const result = await processMessage({
+		context: ctx,
+		state: decState(stateBlob),
+		message: msg,
+		callback: acceptAll
+	});
+	if (result.kind !== "newState") throw new MlsError("Expected commit to produce newState");
+	zeroConsumed(result.consumed);
+	return {
+		updatedState: encState(result.newState),
+		epoch: Number(result.newState.groupContext.epoch)
+	};
+}
+/**
+* Self-join an MLS group via an RFC 9420 external commit (no Welcome required).
+* The joiner mints a fresh KeyPackage with its own Ed25519 signing key, derives
+* a fresh init_secret against the published GroupInfo's external_pub, and emits
+* a public External Commit that existing members process to advance the epoch.
+* Returns the public commit (to broadcast), the joiner's new state, a fresh
+* GroupInfo (so the NEXT external joiner has a current-epoch token), and the new
+* epoch. `resync: false` — the joiner is a brand-new member, not in the tree.
+*/
+async function externalJoinMlsGroup$1(signingKey, groupInfoBlob) {
+	const cs = await getMlsCipherSuite();
+	const ctx = await getMlsContext();
+	const msg = decode(mlsMessageDecoder, groupInfoBlob);
+	if (!msg || msg.wireformat !== wireformats.mls_group_info) throw new Error("Failed to decode MLS GroupInfo for external join");
+	const groupInfo = msg.groupInfo;
+	const publicKey = ed25519.getPublicKey(signingKey);
+	const { publicPackage, privatePackage } = await generateKeyPackageWithKey({
+		credential: basicCred(publicKey),
+		signatureKeyPair: {
+			signKey: signingKey,
+			publicKey
+		},
+		cipherSuite: cs
+	});
+	const { publicMessage, newState } = await joinGroupExternal({
+		context: ctx,
+		groupInfo,
+		keyPackage: publicPackage,
+		privateKeys: privatePackage,
+		resync: false
+	});
+	return {
+		commitBlob: encode(mlsMessageEncoder, {
+			wireformat: wireformats.mls_public_message,
+			publicMessage,
+			version: protocolVersions.mls10
+		}),
+		stateBlob: encState(newState),
+		groupInfo: await freshGroupInfoBlob(newState, cs),
+		epoch: Number(newState.groupContext.epoch)
+	};
+}
+async function encryptMlsAppMessage(stateBlob, plaintext) {
+	const { newState, message, consumed } = await createApplicationMessage({
+		context: await getMlsContext(),
+		state: decState(stateBlob),
+		message: plaintext
+	});
+	zeroConsumed(consumed);
+	return {
+		ciphertext: encode(mlsMessageEncoder, message),
+		updatedState: encState(newState)
+	};
+}
+async function decryptMlsAppMessage(stateBlob, ciphertext) {
+	const ctx = await getMlsContext();
+	const msg = decode(mlsMessageDecoder, ciphertext);
+	if (!msg || msg.wireformat !== wireformats.mls_private_message) throw new Error("Failed to decode MLS private message");
+	const result = await processPrivateMessage({
+		context: ctx,
+		state: decState(stateBlob),
+		privateMessage: msg.privateMessage,
+		callback: acceptAll
+	});
+	if (result.kind !== "applicationMessage") throw new Error("Expected application message, got commit/proposal");
+	zeroConsumed(result.consumed);
+	return {
+		plaintext: result.message,
+		updatedState: encState(result.newState)
+	};
+}
+//#endregion
+//#region src/crypto/mls-state.ts
+function mlsGroupDir(configDir, agentId, groupId) {
+	return join(configDir, "keys", agentId, "mls", groupId);
+}
+function saveMlsState(configDir, agentId, groupId, stateBlob, metadata) {
+	validatePathId(agentId, "agent ID");
+	validatePathId(groupId, "group ID");
+	const dir = mlsGroupDir(configDir, agentId, groupId);
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const statePath = join(dir, "state.bin");
+	fs.writeFileSync(statePath, Buffer.from(stateBlob));
+	fs.chmodSync(statePath, 384);
+	const metaPath = join(dir, "epoch.json");
+	fs.writeFileSync(metaPath, JSON.stringify(metadata), "utf-8");
+	fs.chmodSync(metaPath, 384);
+}
+function loadMlsState(configDir, agentId, groupId) {
+	validatePathId(agentId, "agent ID");
+	validatePathId(groupId, "group ID");
+	const dir = mlsGroupDir(configDir, agentId, groupId);
+	const statePath = join(dir, "state.bin");
+	const metaPath = join(dir, "epoch.json");
+	if (!fs.existsSync(statePath) || !fs.existsSync(metaPath)) return null;
+	return {
+		stateBlob: new Uint8Array(fs.readFileSync(statePath)),
+		metadata: JSON.parse(fs.readFileSync(metaPath, "utf-8"))
+	};
+}
+function deleteMlsState(configDir, agentId, groupId) {
+	validatePathId(agentId, "agent ID");
+	validatePathId(groupId, "group ID");
+	const dir = mlsGroupDir(configDir, agentId, groupId);
+	fs.rmSync(dir, {
+		recursive: true,
+		force: true
+	});
+}
+const SELF_READ_MAX = 256;
+function selfReadCachePath(configDir, agentId, groupId) {
+	return join(mlsGroupDir(configDir, agentId, groupId), "self-read-cache.json");
+}
+function cacheMlsSelfRead(configDir, agentId, groupId, encryptedPayload, envelope) {
+	const cachePath = selfReadCachePath(configDir, agentId, groupId);
+	let cache = {};
+	try {
+		cache = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+	} catch {}
+	cache[encryptedPayload] = Buffer.from(envelope).toString("base64");
+	const keys = Object.keys(cache);
+	if (keys.length > SELF_READ_MAX) for (const k of keys.slice(0, keys.length - SELF_READ_MAX)) delete cache[k];
+	fs.writeFileSync(cachePath, JSON.stringify(cache), "utf-8");
+	fs.chmodSync(cachePath, 384);
+}
+function lookupMlsSelfRead(configDir, agentId, groupId, encryptedPayload) {
+	const cachePath = selfReadCachePath(configDir, agentId, groupId);
+	try {
+		const entry = JSON.parse(fs.readFileSync(cachePath, "utf-8"))[encryptedPayload];
+		if (entry) return new Uint8Array(Buffer.from(entry, "base64"));
+	} catch {}
+	return null;
+}
+function keyPackagesDir(configDir, agentId) {
+	return join(configDir, "keys", agentId, "mls", "key_packages");
+}
+function hexRef(ref) {
+	return Buffer.from(ref).toString("hex");
+}
+function savePrivateKeyPackages(configDir, agentId, packages) {
+	validatePathId(agentId, "agent ID");
+	const dir = keyPackagesDir(configDir, agentId);
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	for (const pkg of packages) {
+		const filePath = join(dir, `${hexRef(pkg.ref)}.json`);
+		const data = JSON.stringify({
+			publicBlob: Buffer.from(pkg.publicBlob).toString("base64"),
+			privateBlob: Buffer.from(pkg.privateBlob).toString("base64")
+		});
+		fs.writeFileSync(filePath, data, "utf-8");
+		fs.chmodSync(filePath, 384);
+	}
+}
+function loadPrivateKeyPackage(configDir, agentId, ref) {
+	validatePathId(agentId, "agent ID");
+	const filePath = join(keyPackagesDir(configDir, agentId), `${hexRef(ref)}.json`);
+	if (!fs.existsSync(filePath)) return null;
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	return {
+		publicBlob: new Uint8Array(Buffer.from(raw.publicBlob, "base64")),
+		privateBlob: new Uint8Array(Buffer.from(raw.privateBlob, "base64"))
+	};
+}
+function deletePrivateKeyPackage(configDir, agentId, ref) {
+	validatePathId(agentId, "agent ID");
+	const filePath = join(keyPackagesDir(configDir, agentId), `${hexRef(ref)}.json`);
+	fs.rmSync(filePath, { force: true });
+}
+function listPrivateKeyPackages(configDir, agentId) {
+	validatePathId(agentId, "agent ID");
+	const dir = keyPackagesDir(configDir, agentId);
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => {
+		const ref = f.replace(".json", "");
+		const raw = JSON.parse(fs.readFileSync(join(dir, f), "utf-8"));
+		return {
+			ref,
+			publicBlob: new Uint8Array(Buffer.from(raw.publicBlob, "base64")),
+			privateBlob: new Uint8Array(Buffer.from(raw.privateBlob, "base64"))
+		};
+	});
+}
+//#endregion
+//#region src/crypto/mls-api.ts
+function toBase64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+function fromBase64(s) {
+	return new Uint8Array(Buffer.from(s, "base64"));
+}
+async function uploadKeyPackages(client, agentId, packages) {
+	return await client.post(`/agents/${agentId}/mls/key-packages`, { packages });
+}
+async function claimKeyPackages(client, agentId, count = 1) {
+	return await client.get(`/agents/${agentId}/mls/key-packages`, { count: String(count) });
+}
+async function mlsInit(client, groupId, extraHeaders) {
+	return await client.post(`/groups/${groupId}/mls/init`, {}, extraHeaders);
+}
+async function mlsCommit(client, groupId, body, extraHeaders) {
+	return await client.post(`/groups/${groupId}/mls/commit`, body, extraHeaders);
+}
+/**
+* ACK a handshake the local client processed cleanly (H4). Once MLS_ACK_QUORUM
+* distinct clean ACKs land server-side, the tentative commit + its GroupInfo are
+* confirmed and mls_confirmed_epoch advances. extraHeaders is threaded so a
+* multi-agent client ACKs as the right acting agent (sibling /groups bug: do not
+* drop extraHeaders here).
+*/
+async function mlsAck(client, groupId, body, extraHeaders) {
+	return await client.post(`/groups/${groupId}/mls/ack`, body, extraHeaders);
+}
+/**
+* NACK a handshake the local client could NOT process (H4). The server marks the
+* delivery and lazily rolls the tentative commit back. A NACK is non-destructive:
+* it only ever un-advances unconfirmed, never-served state. extraHeaders threaded.
+*/
+async function mlsNack(client, groupId, body, extraHeaders) {
+	return await client.post(`/groups/${groupId}/mls/nack`, body, extraHeaders);
+}
+async function fetchHandshakes(client, groupId, sinceEpoch, extraHeaders) {
+	const params = {};
+	if (sinceEpoch !== void 0) params["since_epoch"] = String(sinceEpoch);
+	return await client.get(`/groups/${groupId}/mls/handshakes`, params, extraHeaders);
+}
+async function fetchWelcomes(client, agentId) {
+	return await client.get(`/agents/${agentId}/mls/welcomes`);
+}
+async function fetchGroupInfo(client, groupId, extraHeaders) {
+	return await client.get(`/groups/${groupId}/mls/group-info`, void 0, extraHeaders);
+}
+async function submitProposal(client, groupId, proposal, extraHeaders) {
+	return await client.post(`/groups/${groupId}/mls/proposals`, { proposal }, extraHeaders);
+}
+//#endregion
+//#region src/mls-ops-join.ts
+/** A commit was rejected because our GroupInfo targeted a stale epoch. */
+function isEpochConflict(err) {
+	return err instanceof RineApiError && err.code === "epoch_conflict";
+}
+/**
+* The group's only GroupInfo is still tentative (awaiting a peer ACK), so the
+* server has no confirmed join token yet (H4). Distinct from epoch_conflict: a
+* short bounded retry resolves it once a peer ACKs, so it must NOT consume the
+* single epoch-conflict retry below.
+*/
+function isPendingConfirmation(err) {
+	return err instanceof RineApiError && err.code === "pending_confirmation";
+}
+const CIPHER_SUITE = 1;
+const PENDING_RETRY_LIMIT = 3;
+const PENDING_RETRY_DELAY_MS = 400;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Self-join an MLS-active group via an RFC 9420 external commit (Phase 6).
+*
+* Used for OPEN enrollment, where the rine server adds a joiner to the group
+* with no member in the loop — so nobody mints a Welcome and the joiner is a
+* rine member but not yet an MLS member. The joiner fetches the group's latest
+* published GroupInfo, derives a fresh init_secret against its external_pub,
+* and posts a public External Commit that existing members process (via the
+* EXISTING syncMlsGroup path) to advance the epoch.
+*
+* State is keyed by the RINE group UUID (groupId) — the same key
+* encrypt/decryptGroupMessage use — so the joiner can immediately send/receive.
+*
+* Epoch-conflict handling (research-guided, RFC 9420 §12.4.3.2 + RFC 9750):
+* a GroupInfo is single-use per epoch. If a competing external join lands first,
+* our GroupInfo is stale and our commit targets a stale epoch (members reject).
+* We do a single discard-and-rebuild retry against a freshly-fetched GroupInfo;
+* on a second failure we surface a clear, actionable terminal error rather than
+* looping (an unbounded retry against an advancing epoch is a self-DoS).
+*/
+async function externalJoinMlsGroup(configDir, agentId, groupId, client, extraHeaders) {
+	const keys = loadAgentKeys(configDir, agentId);
+	const attempt = async () => {
+		const info = await fetchGroupInfo(client, groupId, extraHeaders);
+		if (!info.group_info) throw new Error(`Cannot self-join MLS group ${groupId}: no published GroupInfo. An existing member must publish one (open enrollment requires a current-epoch GroupInfo).`);
+		const groupInfoBlob = fromBase64(info.group_info);
+		const joined = await externalJoinMlsGroup$1(keys.signing.privateKey, groupInfoBlob);
+		const epoch = (await mlsCommit(client, groupId, {
+			commit: toBase64(joined.commitBlob),
+			group_info: toBase64(joined.groupInfo),
+			epoch: joined.epoch
+		}, extraHeaders)).epoch ?? joined.epoch;
+		saveMlsState(configDir, agentId, groupId, joined.stateBlob, {
+			groupId,
+			epoch,
+			cipherSuite: CIPHER_SUITE
+		});
+		return { epoch };
+	};
+	let firstErr = void 0;
+	for (let i = 0;; i++) try {
+		return await attempt();
+	} catch (err) {
+		if (!isPendingConfirmation(err)) {
+			firstErr = err;
+			break;
+		}
+		if (i >= PENDING_RETRY_LIMIT - 1) throw new Error(`Cannot self-join MLS group ${groupId}: GroupInfo is still pending peer confirmation after a brief retry. Try again shortly.`, { cause: err });
+		await sleep(PENDING_RETRY_DELAY_MS);
+	}
+	if (!isEpochConflict(firstErr)) throw firstErr;
+	try {
+		return await attempt();
+	} catch (retryErr) {
+		const detail = retryErr instanceof Error ? retryErr.message : String(retryErr);
+		throw new Error(`External MLS self-join failed for group ${groupId} after one retry (likely an epoch conflict — another joiner landed first): ${detail}`, { cause: firstErr });
+	}
+}
+//#endregion
+//#region src/mls-ops-sync.ts
+/**
+* Fetch all pending MLS welcomes for an agent and process them, establishing
+* local group state for each group the agent has been added to.
+*/
+async function processMlsWelcomes(configDir, agentId, client) {
+	const { welcomes } = await fetchWelcomes(client, agentId);
+	const storedPkgs = listPrivateKeyPackages(configDir, agentId);
+	const pkgByRef = new Map(storedPkgs.map((p) => [p.ref, p]));
+	const groupIds = [];
+	for (const welcome of welcomes) {
+		const rineGroupId = welcome.group_id;
+		if (!rineGroupId) continue;
+		const welcomeBlob = fromBase64(welcome.blob);
+		const msg = decode(mlsMessageDecoder, welcomeBlob);
+		if (!msg || msg.wireformat !== wireformats.mls_welcome) throw new Error("Failed to decode welcome message");
+		const welcomeData = msg.welcome;
+		let matched = null;
+		for (const secret of welcomeData.secrets) {
+			const refHex = Buffer.from(secret.newMember).toString("hex");
+			const pkg = pkgByRef.get(refHex);
+			if (pkg) {
+				matched = {
+					publicBlob: pkg.publicBlob,
+					privateBlob: pkg.privateBlob,
+					refHex
+				};
+				break;
+			}
+		}
+		if (!matched) throw new Error("No matching private key package found for welcome");
+		const { stateBlob, epoch, cipherSuite } = await processMlsWelcome(welcomeBlob, matched.publicBlob, matched.privateBlob);
+		saveMlsState(configDir, agentId, rineGroupId, stateBlob, {
+			groupId: rineGroupId,
+			epoch,
+			cipherSuite
+		});
+		deletePrivateKeyPackage(configDir, agentId, Buffer.from(matched.refHex, "hex"));
+		groupIds.push(rineGroupId);
+	}
+	return {
+		processed: groupIds.length,
+		groupIds
+	};
+}
+/**
+* Remove a member from an MLS group by leaf index and post the remove commit.
+*/
+async function removeMlsGroupMember(configDir, agentId, groupId, leafIndex, client, extraHeaders) {
+	const stored = loadMlsState(configDir, agentId, groupId);
+	if (!stored) throw new Error(`No MLS state for group ${groupId}`);
+	const { commitBlob, updatedState, groupInfo, epoch: commitEpoch } = await removeMemberFromMlsGroup(stored.stateBlob, leafIndex);
+	const epoch = (await mlsCommit(client, groupId, {
+		commit: toBase64(commitBlob),
+		group_info: toBase64(groupInfo),
+		epoch: commitEpoch
+	}, extraHeaders)).epoch ?? commitEpoch;
+	saveMlsState(configDir, agentId, groupId, updatedState, {
+		...stored.metadata,
+		epoch
+	});
+	return { epoch };
+}
+/**
+* Sync local MLS group state by fetching and applying all commits posted
+* since the current epoch.
+*/
+async function syncMlsGroup(configDir, agentId, groupId, client, extraHeaders) {
+	const stored = loadMlsState(configDir, agentId, groupId);
+	if (!stored) throw new Error(`No MLS state for group ${groupId}`);
+	const currentEpoch = stored.metadata.epoch;
+	const { handshakes } = await fetchHandshakes(client, groupId, currentEpoch, extraHeaders);
+	let currentState = stored.stateBlob;
+	let epoch = currentEpoch;
+	let processed = 0;
+	for (const handshake of handshakes) {
+		const commitBlob = fromBase64(handshake.blob);
+		let result;
+		try {
+			result = await processMlsCommit(currentState, commitBlob);
+		} catch (err) {
+			if (err instanceof MlsError) {
+				const reconciled = await reconcileIfOrphaned(configDir, agentId, groupId, epoch, client, extraHeaders);
+				if (reconciled !== null) return {
+					epoch: reconciled,
+					processed
+				};
+				await emitNack(client, groupId, handshake, err, extraHeaders);
+				break;
+			}
+			throw err;
+		}
+		currentState = result.updatedState;
+		epoch = result.epoch;
+		processed += 1;
+		saveMlsState(configDir, agentId, groupId, currentState, {
+			...stored.metadata,
+			epoch
+		});
+		await emitAck(client, groupId, handshake, extraHeaders);
+	}
+	return {
+		epoch,
+		processed
+	};
+}
+/**
+* H4 (MEDIUM-1) reconcile: detect whether a processMlsCommit failure is caused
+* by our OWN local state being orphaned (ahead of the server's confirmed epoch)
+* rather than by a genuinely un-processable commit.
+*
+* The orphan signal: the server's confirmed GroupInfo epoch is BELOW our local
+* epoch. That can only happen if our own tentative commit was rolled back — the
+* server cannot serve a confirmed token as high as the epoch we locally hold. In
+* that case we re-bootstrap via an external self-join from mls_confirmed_epoch
+* (no un-processing of honestly-confirmed state — the B1 win); the re-join only
+* overwrites the stale local state once the server accepts the commit, so a
+* mid-flight re-join failure leaves the stale state intact for the next sync to
+* retry rather than stranding the agent stateless. Returns the re-bootstrapped
+* epoch on reconcile, or null when the state is NOT orphaned (caller should NACK
+* the garbage commit).
+*/
+async function reconcileIfOrphaned(configDir, agentId, groupId, localEpoch, client, extraHeaders) {
+	let confirmedEpoch;
+	try {
+		confirmedEpoch = (await fetchGroupInfo(client, groupId, extraHeaders)).epoch;
+	} catch {
+		return null;
+	}
+	if (confirmedEpoch === null || confirmedEpoch >= localEpoch) return null;
+	const { epoch } = await externalJoinMlsGroup(configDir, agentId, groupId, client, extraHeaders);
+	return epoch;
+}
+/** Fire-and-forget ACK; a failed ACK must never fail the sync. */
+async function emitAck(client, groupId, handshake, extraHeaders) {
+	try {
+		await mlsAck(client, groupId, { object_id: handshake.id }, extraHeaders);
+	} catch {}
+}
+/** Fire-and-forget NACK; a failed NACK must never fail the sync. */
+async function emitNack(client, groupId, handshake, err, extraHeaders) {
+	try {
+		await mlsNack(client, groupId, {
+			object_id: handshake.id,
+			epoch: handshake.epoch ?? 0,
+			reason: err.message.slice(0, 256)
+		}, extraHeaders);
+	} catch {}
+}
+//#endregion
 //#region src/crypto/message.ts
 async function verifyEnvelopeSender(decoded, client) {
 	let verified = false;
@@ -745,23 +1541,38 @@ async function verifyEnvelopeSender(decoded, client) {
 function signingKid(agentId) {
 	return `rine:${agentId}`;
 }
-async function encryptMessage(configDir, senderAgentId, recipientEncryptionPk, payload) {
+async function encryptMessage(configDir, senderAgentId, recipientEncryptionPk, payload, recipientPqEncryptionPk) {
 	const keys = loadAgentKeys(configDir, senderAgentId);
 	const plaintext = new TextEncoder().encode(JSON.stringify(payload));
 	const kid = signingKid(senderAgentId);
+	const envelope = encodeEnvelope(kid, signPayload(keys.signing.privateKey, plaintext), plaintext);
+	if (recipientPqEncryptionPk && recipientPqEncryptionPk.length > 0) return {
+		encrypted_payload: toBase64Url(await sealHybrid(recipientEncryptionPk, recipientPqEncryptionPk, envelope)),
+		encryption_version: "hpke-hybrid-v1",
+		sender_signing_kid: kid
+	};
 	return {
-		encrypted_payload: toBase64Url(await seal(recipientEncryptionPk, encodeEnvelope(kid, signPayload(keys.signing.privateKey, plaintext), plaintext))),
+		encrypted_payload: toBase64Url(await seal(recipientEncryptionPk, envelope)),
 		encryption_version: "hpke-v1",
 		sender_signing_kid: kid
 	};
 }
-async function fetchRecipientEncryptionKey(client, agentId) {
-	return jwkToPublicKey((await client.get(`/agents/${agentId}/keys`)).encryption_public_key);
+/** Fetch a recipient's encryption keys, including the optional PQ key for hybrid mode. */
+async function fetchRecipientKeys(client, agentId) {
+	const data = await client.get(`/agents/${agentId}/keys`);
+	const out = { encryption: jwkToPublicKey(data.encryption_public_key) };
+	if (data.pq_encryption_public_key) out.pqEncryption = jwkToPqPublicKey(data.pq_encryption_public_key);
+	return out;
 }
 async function decryptMessage(configDir, recipientAgentId, encryptedPayloadB64, client) {
 	const keys = loadAgentKeys(configDir, recipientAgentId);
 	const encrypted = fromBase64Url(encryptedPayloadB64);
-	const decoded = decodeEnvelope(await open(keys.encryption.privateKey, encrypted));
+	let envelopeBytes;
+	if (encrypted[0] === 3) {
+		if (!keys.pqEncryption) throw new Error("received hpke-hybrid-v1 message but recipient has no PQ encryption key");
+		envelopeBytes = await openHybrid(keys.encryption.privateKey, keys.pqEncryption.privateKey, encrypted);
+	} else envelopeBytes = await open(keys.encryption.privateKey, encrypted);
+	const decoded = decodeEnvelope(envelopeBytes);
 	const plaintext = new TextDecoder("utf-8", { fatal: true }).decode(decoded.payload);
 	const { verified, verificationStatus } = await verifyEnvelopeSender(decoded, client);
 	return {
@@ -793,11 +1604,87 @@ async function encryptGroupMessage(configDir, senderAgentId, groupId, senderKeyS
 		updatedState
 	};
 }
+/**
+* Encrypt a payload for an MLS-active group.
+*
+* Mirrors {@link encryptGroupMessage} but uses MLS instead of sender keys.
+* The signed inner envelope (kid + Ed25519 signature + plaintext) is the MLS
+* application-message payload, so {@link decryptGroupMessage}'s 0x04 branch can
+* run `decodeEnvelope` + `verifyEnvelopeSender` unchanged. The MLS ciphertext is
+* prefixed with {@link VERSION_MLS} (0x04) and base64url-encoded to match the
+* version-byte dispatch in `decryptGroupMessage`.
+*
+* State is keyed by the rine group UUID (`groupId`), the same identifier used by
+* `decryptGroupMessage` and the MLS API routes — never the opaque `mls_group_id`
+* latch or the MLS-internal group id.
+*/
+async function encryptMlsGroupMessage(configDir, senderAgentId, groupId, payload) {
+	const stored = loadMlsState(configDir, senderAgentId, groupId);
+	if (!stored) throw new Error(`No MLS state for group ${groupId}`);
+	const keys = loadAgentKeys(configDir, senderAgentId);
+	const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+	const kid = signingKid(senderAgentId);
+	const envelope = encodeEnvelope(kid, signPayload(keys.signing.privateKey, plaintext), plaintext);
+	const { ciphertext, updatedState } = await encryptMlsAppMessage(stored.stateBlob, envelope);
+	saveMlsState(configDir, senderAgentId, groupId, updatedState, stored.metadata);
+	const tagged = new Uint8Array(1 + ciphertext.length);
+	tagged[0] = 4;
+	tagged.set(ciphertext, 1);
+	const encrypted_payload = toBase64Url(tagged);
+	cacheMlsSelfRead(configDir, senderAgentId, groupId, encrypted_payload, envelope);
+	return {
+		encrypted_payload,
+		encryption_version: "mls-v1",
+		sender_signing_kid: kid
+	};
+}
+async function decryptMlsMessage(configDir, recipientAgentId, groupId, mlsCiphertext, client) {
+	const stored = loadMlsState(configDir, recipientAgentId, groupId);
+	if (!stored) throw new Error(`No MLS state for group ${groupId}`);
+	const { plaintext: mlsPlain, updatedState } = await decryptMlsAppMessage(stored.stateBlob, mlsCiphertext);
+	saveMlsState(configDir, recipientAgentId, groupId, updatedState, stored.metadata);
+	const mlsEnvelope = decodeEnvelope(mlsPlain);
+	const mlsText = new TextDecoder("utf-8", { fatal: true }).decode(mlsEnvelope.payload);
+	const { verified, verificationStatus } = await verifyEnvelopeSender(mlsEnvelope, client);
+	if (verificationStatus === "invalid") throw new Error("Sender signature verification failed");
+	return {
+		plaintext: mlsText,
+		senderKid: mlsEnvelope.kid,
+		verified,
+		verificationStatus
+	};
+}
 async function decryptGroupMessage(configDir, recipientAgentId, groupId, encryptedPayloadB64, client) {
 	const states = loadSenderKeyStates(configDir, recipientAgentId, groupId);
 	const stateMap = /* @__PURE__ */ new Map();
 	for (const s of states) stateMap.set(s.senderKeyId, s);
-	const { innerEnvelope, updatedState, messageIndex } = await openGroup(stateMap, fromBase64Url(encryptedPayloadB64));
+	const encrypted = fromBase64Url(encryptedPayloadB64);
+	if (encrypted[0] === 4) {
+		const cached = lookupMlsSelfRead(configDir, recipientAgentId, groupId, encryptedPayloadB64);
+		if (cached) {
+			const env = decodeEnvelope(cached);
+			const text = new TextDecoder("utf-8", { fatal: true }).decode(env.payload);
+			const { verified, verificationStatus } = await verifyEnvelopeSender(env, client);
+			if (verificationStatus === "invalid") throw new Error("Sender signature verification failed");
+			return {
+				plaintext: text,
+				senderKid: env.kid,
+				verified,
+				verificationStatus
+			};
+		}
+		const mlsCiphertext = encrypted.slice(1);
+		try {
+			return await decryptMlsMessage(configDir, recipientAgentId, groupId, mlsCiphertext, client);
+		} catch (err) {
+			if (!(err instanceof MlsError || err instanceof Error && err.message.startsWith("No MLS state for group"))) throw err;
+		}
+		await processMlsWelcomes(configDir, recipientAgentId, client);
+		if (!loadMlsState(configDir, recipientAgentId, groupId)) await externalJoinMlsGroup(configDir, recipientAgentId, groupId, client);
+		await syncMlsGroup(configDir, recipientAgentId, groupId, client);
+		return await decryptMlsMessage(configDir, recipientAgentId, groupId, mlsCiphertext, client);
+	}
+	const { innerEnvelope, updatedState, messageIndex } = await openGroup(stateMap, encrypted);
 	const decoded = decodeEnvelope(innerEnvelope);
 	const plaintext = new TextDecoder("utf-8", { fatal: true }).decode(decoded.payload);
 	const { verified, verificationStatus } = await verifyEnvelopeSender(decoded, client);
@@ -820,7 +1707,7 @@ async function decryptGroupMessage(configDir, recipientAgentId, groupId, encrypt
 }
 function getAgentPublicKeys(configDir, agentId, agentKeys) {
 	const keys = agentKeys ?? loadAgentKeys(configDir, agentId);
-	return {
+	const result = {
 		signing_public_key: signingPublicKeyToJWK(keys.signing.publicKey),
 		encryption_public_key: {
 			kty: "OKP",
@@ -828,6 +1715,8 @@ function getAgentPublicKeys(configDir, agentId, agentKeys) {
 			x: toBase64Url(keys.encryption.publicKey)
 		}
 	};
+	if (keys.pqEncryption) result.pq_encryption_public_key = pqPublicKeyToJWK(keys.pqEncryption.publicKey);
+	return result;
 }
 //#endregion
 //#region src/crypto/ingest.ts
@@ -886,7 +1775,7 @@ async function distributeSenderKey(client, configDir, senderAgentId, state, grou
 			continue;
 		}
 		try {
-			const encrypted = await encryptMessage(configDir, senderAgentId, fromBase64Url(recipientKeyData.encryption_public_key.x), distPayload);
+			const encrypted = await encryptMessage(configDir, senderAgentId, fromBase64Url(recipientKeyData.encryption_public_key.x), distPayload, recipientKeyData.pq_encryption_public_key ? jwkToPqPublicKey(recipientKeyData.pq_encryption_public_key) : void 0);
 			await client.post("/messages", {
 				to_agent_id: recipientId,
 				type: "rine.v1.sender_key_distribution",
@@ -968,6 +1857,99 @@ async function fetchAndIngestPendingSKDistributions(client, configDir, agentId,
 	return ingested;
 }
 //#endregion
+//#region src/mls-ops.ts
+/**
+* Generate and upload MLS key packages for an agent, enabling other agents
+* to add them to MLS groups.
+*/
+async function publishMlsKeyPackages(configDir, agentId, client, count = 10) {
+	const keys = loadAgentKeys(configDir, agentId);
+	const packages = [];
+	const privatePackages = [];
+	for (let i = 0; i < count; i++) {
+		const kp = await generateMlsKeyPackage(keys.signing.privateKey);
+		packages.push(toBase64(kp.publicBlob));
+		privatePackages.push({
+			ref: kp.keyPackageRef,
+			publicBlob: kp.publicBlob,
+			privateBlob: kp.privateBlob
+		});
+	}
+	savePrivateKeyPackages(configDir, agentId, privatePackages);
+	return uploadKeyPackages(client, agentId, packages);
+}
+/**
+* Initialize an MLS group: create the group state, add all members who have
+* uploaded key packages, and post the initial commit + welcomes to the server.
+*/
+async function initMlsGroup(configDir, agentId, groupId, client, extraHeaders) {
+	const initResp = await mlsInit(client, groupId, extraHeaders);
+	const { stateBlob, groupInfo, commitBlob, epoch: createEpoch } = await createMlsGroup(loadAgentKeys(configDir, agentId).signing.privateKey);
+	const agentIdLower = agentId.toLowerCase();
+	const eligibleMembers = initResp.members.filter((m) => m.has_key_package && m.agent_id.toLowerCase() !== agentIdLower);
+	let currentState = stateBlob;
+	let currentCommit = commitBlob;
+	let currentGroupInfo = groupInfo;
+	let currentEpoch = createEpoch;
+	const welcomes = [];
+	for (const member of eligibleMembers) {
+		const firstPackage = (await claimKeyPackages(client, member.agent_id)).packages[0];
+		if (!firstPackage) continue;
+		const kpBlob = fromBase64(firstPackage);
+		const result = await addMemberToMlsGroup(currentState, kpBlob);
+		welcomes.push({
+			agent_id: member.agent_id,
+			welcome: toBase64(result.welcomeBlob)
+		});
+		currentState = result.updatedState;
+		currentCommit = result.commitBlob;
+		currentGroupInfo = result.groupInfo;
+		currentEpoch = result.epoch;
+	}
+	const epoch = (await mlsCommit(client, groupId, {
+		commit: toBase64(currentCommit),
+		welcomes,
+		group_info: toBase64(currentGroupInfo),
+		cipher_suite: 1,
+		epoch: currentEpoch
+	}, extraHeaders)).epoch ?? currentEpoch;
+	saveMlsState(configDir, agentId, groupId, currentState, {
+		groupId,
+		epoch,
+		cipherSuite: 1
+	});
+	return {
+		epoch,
+		membersAdded: welcomes.length
+	};
+}
+/**
+* Add a single member to an existing MLS group by claiming their key package
+* and posting an add commit + welcome.
+*/
+async function addMlsGroupMember(configDir, agentId, groupId, memberAgentId, client, extraHeaders) {
+	const stored = loadMlsState(configDir, agentId, groupId);
+	if (!stored) throw new Error(`No MLS state for group ${groupId}`);
+	const firstPackage = (await claimKeyPackages(client, memberAgentId)).packages[0];
+	if (!firstPackage) throw new Error(`No key packages available for ${memberAgentId}`);
+	const kpBlob = fromBase64(firstPackage);
+	const { commitBlob, welcomeBlob, updatedState, groupInfo, epoch: commitEpoch } = await addMemberToMlsGroup(stored.stateBlob, kpBlob);
+	const epoch = (await mlsCommit(client, groupId, {
+		commit: toBase64(commitBlob),
+		welcomes: [{
+			agent_id: memberAgentId,
+			welcome: toBase64(welcomeBlob)
+		}],
+		group_info: toBase64(groupInfo),
+		epoch: commitEpoch
+	}, extraHeaders)).epoch ?? commitEpoch;
+	saveMlsState(configDir, agentId, groupId, updatedState, {
+		...stored.metadata,
+		epoch
+	});
+	return { epoch };
+}
+//#endregion
 //#region src/onboard.ts
 /** Validate an org slug: 2-32 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphen. */
 function validateSlug(slug) {
@@ -1039,10 +2021,14 @@ async function performAgentCreation(client, configDir, profile, params) {
 		signing_public_key: signingPublicKeyToJWK(agentKeys.signing.publicKey),
 		encryption_public_key: encryptionPublicKeyToJWK(agentKeys.encryption.publicKey)
 	};
+	if (agentKeys.pqEncryption) body.pq_encryption_public_key = pqPublicKeyToJWK(agentKeys.pqEncryption.publicKey);
 	if (params.humanOversight !== void 0) body.human_oversight = params.humanOversight;
 	if (params.unlisted !== void 0) body.unlisted = params.unlisted;
 	const agent = await client.post("/agents", body);
 	saveAgentKeys(configDir, agent.id, agentKeys);
+	try {
+		await publishMlsKeyPackages(configDir, agent.id, client);
+	} catch {}
 	if (agent.poll_url) {
 		const creds = loadCredentials(configDir);
 		if (creds[profile]) {
@@ -1053,4 +2039,4 @@ async function performAgentCreation(client, configDir, profile, params) {
 	return agent;
 }
 //#endregion
-export { DEFAULT_API_URL, HttpClient, RineApiError, UUID_RE, advanceChain, agentIdFromKid, agentKeysExist, bytesToUuid, cacheToken, decodeEnvelope, decryptGroupMessage, decryptMessage, deriveMessageKey, distributeSenderKey, encodeEnvelope, encryptGroupMessage, encryptMessage, encryptionPublicKeyToJWK, fetchAgents, fetchAndIngestPendingSKDistributions, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, generateEncryptionKeyPair, generateSenderKey, generateSigningKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, jwkToPublicKey, loadAgentKeys, loadCredentials, loadSenderKeyStates, loadTokenCache, needsRotation, normalizeHandle, open, openGroup, performAgentCreation, performRegistration, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveSenderKeyState, saveTokenCache, seal, sealGroup, signPayload, signingPublicKeyToJWK, solveTimeLock, solveTimeLockWithProgress, toBase64Url, uuidToBytes, validateEncryptionKey, validatePathId, validateSigningKey, validateSlug, verifySignature };
+export { DEFAULT_API_URL, HttpClient, MLKEM_CT_SIZE, MLS_CIPHER_SUITE_ID, RineApiError, UUID_RE, VERSION_HYBRID, VERSION_MLS, addMemberToMlsGroup, addMlsGroupMember, advanceChain, agentIdFromKid, agentKeysExist, bytesToUuid, cacheMlsSelfRead, cacheToken, claimKeyPackages, createMlsGroup, decodeEnvelope, decryptGroupMessage, decryptMessage, decryptMlsAppMessage, deleteMlsState, deletePrivateKeyPackage, deriveMessageKey, distributeSenderKey, encodeEnvelope, encryptGroupMessage, encryptMessage, encryptMlsAppMessage, encryptMlsGroupMessage, encryptionPublicKeyToJWK, externalJoinMlsGroup, fetchAgents, fetchAndIngestPendingSKDistributions, fetchGroupInfo, fetchHandshakes, fetchOAuthToken, fetchRecipientKeys, fetchWelcomes, formatError, fromBase64Url, generateAgentKeys, generateEncryptionKeyPair, generateMlsKeyPackage, generatePqKeyPair, generateSenderKey, generateSigningKeyPair, getAgentPublicKeys, getCredentialEntry, getMlsCipherSuite, getMlsContext, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, initMlsGroup, isBareAgentName, jwkToPqPublicKey, jwkToPublicKey, listPrivateKeyPackages, loadAgentKeys, loadCredentials, loadMlsState, loadPrivateKeyPackage, loadSenderKeyStates, loadTokenCache, lookupMlsSelfRead, mlsAck, mlsCommit, fromBase64 as mlsFromBase64, mlsInit, mlsNack, toBase64 as mlsToBase64, needsRotation, normalizeHandle, open, openGroup, openHybrid, performAgentCreation, performRegistration, pqPublicKeyToJWK, processMlsCommit, processMlsWelcome, processMlsWelcomes, publishMlsKeyPackages, removeMemberFromMlsGroup, removeMlsGroupMember, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveMlsState, savePqEncryptionKey, savePrivateKeyPackages, saveSenderKeyState, saveTokenCache, seal, sealGroup, sealHybrid, signPayload, signingPublicKeyToJWK, solveTimeLock, solveTimeLockWithProgress, submitProposal, syncMlsGroup, toBase64Url, uploadKeyPackages, uuidToBytes, validateEncryptionKey, validatePathId, validateSigningKey, validateSlug, verifySignature };