@rine-network/core 0.1.0

package/dist/index.js

@@ -0,0 +1,904 @@
+import * as fs from "node:fs";
+import { homedir } from "node:os";
+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 { sha256 } from "@noble/hashes/sha2.js";
+//#region src/errors.ts
+var RineApiError = class extends Error {
+	constructor(status, detail, raw) {
+		super(`${status}: ${detail}`);
+		this.status = status;
+		this.detail = detail;
+		this.raw = raw;
+		this.name = "RineApiError";
+	}
+};
+function formatError(err) {
+	if (err instanceof RineApiError) return err.detail;
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+//#endregion
+//#region src/config.ts
+const DEFAULT_API_URL = "https://rine.network";
+/** Resolve config directory. Priority: RINE_CONFIG_DIR env > cwd/.rine > ~/.config/rine */
+function resolveConfigDir() {
+	if (process.env.RINE_CONFIG_DIR) return process.env.RINE_CONFIG_DIR;
+	const local = join(process.cwd(), ".rine");
+	if (fs.existsSync(local)) return local;
+	return join(homedir(), ".config", "rine");
+}
+/** Resolve API URL from environment or default. */
+function resolveApiUrl() {
+	return (process.env.RINE_API_URL ?? "https://rine.network").replace(/\/$/, "");
+}
+function ensureDir(dir) {
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+}
+function writeAtomic(path, content) {
+	const tmpPath = `${path}.tmp`;
+	fs.writeFileSync(tmpPath, content, "utf-8");
+	fs.renameSync(tmpPath, path);
+	fs.chmodSync(path, 384);
+}
+function loadCredentials(configDir) {
+	const path = join(configDir, "credentials.json");
+	try {
+		const raw = fs.readFileSync(path, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+}
+function saveCredentials(configDir, creds) {
+	ensureDir(configDir);
+	writeAtomic(join(configDir, "credentials.json"), JSON.stringify(creds, null, 2));
+}
+function loadTokenCache(configDir) {
+	const path = join(configDir, "token_cache.json");
+	try {
+		const raw = fs.readFileSync(path, "utf-8");
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+}
+function saveTokenCache(configDir, cache) {
+	ensureDir(configDir);
+	writeAtomic(join(configDir, "token_cache.json"), JSON.stringify(cache, null, 2));
+}
+function cacheToken(configDir, profile, token) {
+	const cache = loadTokenCache(configDir);
+	cache[profile] = {
+		access_token: token.access_token,
+		expires_at: Date.now() / 1e3 + token.expires_in
+	};
+	saveTokenCache(configDir, cache);
+}
+/**
+* Resolves credentials for a profile. Priority:
+* 1. RINE_CLIENT_ID + RINE_CLIENT_SECRET env vars (both required)
+* 2. credentials.json for the given profile
+*/
+function getCredentialEntry(configDir, profile = "default") {
+	const envId = process.env.RINE_CLIENT_ID;
+	const envSecret = process.env.RINE_CLIENT_SECRET;
+	if (envId && envSecret) return {
+		client_id: envId,
+		client_secret: envSecret
+	};
+	return loadCredentials(configDir)[profile];
+}
+//#endregion
+//#region src/http.ts
+async function parseErrorDetail(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("; ");
+	} catch {}
+	return res.statusText;
+}
+var HttpClient = class {
+	baseUrl;
+	tokenFn;
+	canRefresh;
+	defaultHeaders;
+	constructor(opts) {
+		this.baseUrl = opts.apiUrl;
+		this.tokenFn = opts.tokenFn;
+		this.canRefresh = opts.canRefresh ?? true;
+		this.defaultHeaders = opts.defaultHeaders ?? {};
+	}
+	async request(method, path, body, params, extraHeaders) {
+		let url = this.baseUrl + path;
+		if (params) {
+			const qs = new URLSearchParams(Object.entries(params).filter(([, v]) => v !== void 0 && v !== null).map(([k, v]) => [k, String(v)])).toString();
+			if (qs) url += `?${qs}`;
+		}
+		const doFetch = async (force) => {
+			const headers = {
+				Authorization: `Bearer ${await this.tokenFn(force)}`,
+				...this.defaultHeaders,
+				...extraHeaders
+			};
+			if (body !== void 0) headers["Content-Type"] = "application/json";
+			const init = {
+				method,
+				headers
+			};
+			if (body !== void 0) init.body = JSON.stringify(body);
+			return fetch(url, init);
+		};
+		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);
+		}
+		if (res.status === 204) return void 0;
+		return res.json();
+	}
+	get(path, params, extraHeaders) {
+		return this.request("GET", path, void 0, params, extraHeaders);
+	}
+	post(path, body, extraHeaders) {
+		return this.request("POST", path, body, void 0, extraHeaders);
+	}
+	put(path, body, extraHeaders) {
+		return this.request("PUT", path, body, void 0, extraHeaders);
+	}
+	patch(path, body, extraHeaders) {
+		return this.request("PATCH", path, body, void 0, extraHeaders);
+	}
+	delete(path, extraHeaders) {
+		return this.request("DELETE", path, void 0, void 0, extraHeaders);
+	}
+	/** Unauthenticated GET for public endpoints (e.g. /directory/*). */
+	static async publicGet(apiUrl, path, params) {
+		const qs = params?.toString();
+		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);
+		}
+		return res.json();
+	}
+};
+/**
+* Fetches an OAuth token from POST /oauth/token.
+*/
+async function fetchOAuthToken(apiUrl, clientId, clientSecret) {
+	const res = await fetch(`${apiUrl}/oauth/token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			grant_type: "client_credentials",
+			client_id: clientId,
+			client_secret: clientSecret
+		}).toString()
+	});
+	if (!res.ok) {
+		const body = await res.json().catch(() => ({}));
+		throw new RineApiError(res.status, body.detail ?? "Token request failed");
+	}
+	return res.json();
+}
+/**
+* Resolves a valid access token. Priority:
+* 1. opts.envToken — used directly, no cache/refresh
+* 2. Token cache — returned if not expired (60s margin)
+* 3. POST /oauth/token — fetches fresh token and caches it
+*/
+async function getOrRefreshToken(configDir, apiUrl, entry, profileName, opts) {
+	if (opts?.envToken) return opts.envToken;
+	const now = Date.now() / 1e3;
+	if (!opts?.force) {
+		const cached = loadTokenCache(configDir)[profileName];
+		if (cached !== void 0 && cached.expires_at - now > 60) return cached.access_token;
+	}
+	if (!entry) throw new RineApiError(0, "No credentials found. Run login first.");
+	const data = await fetchOAuthToken(apiUrl, entry.client_id, entry.client_secret);
+	cacheToken(configDir, profileName, data);
+	return data.access_token;
+}
+//#endregion
+//#region src/resolve-handle.ts
+const UUID_ALIAS_RE = /\/agents\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* Resolves a handle (e.g. "agent@org.rine.network") to a UUID
+* via WebFinger (RFC 7033).
+*
+* Returns the UUID string on success, or the original input unchanged
+* on failure (caller validates UUID format and reports the error).
+*/
+async function resolveHandleViaWebFinger(apiUrl, handle) {
+	try {
+		const params = new URLSearchParams({ resource: `acct:${handle}` });
+		const data = await HttpClient.publicGet(apiUrl, "/.well-known/webfinger", params);
+		for (const alias of data.aliases ?? []) {
+			const match = UUID_ALIAS_RE.exec(alias);
+			if (match?.[1]) return match[1];
+		}
+	} catch {}
+	return handle;
+}
+//#endregion
+//#region src/resolve-agent.ts
+/**
+* Resolve a value that may be a UUID or a handle (containing @) to a UUID.
+* Handles are resolved via WebFinger.
+*/
+async function resolveToUuid(apiUrl, value) {
+	if (!value.includes("@")) {
+		if (UUID_RE.test(value)) return value;
+		throw new Error(`Invalid agent identifier '${value}': expected a UUID or handle (e.g. agent@org.rine.network).`);
+	}
+	const resolved = await resolveHandleViaWebFinger(apiUrl, value);
+	if (!UUID_RE.test(resolved)) throw new Error(`Cannot resolve handle "${value}" to agent ID. Ensure WebFinger is available or use a UUID.`);
+	return resolved;
+}
+/** Check if a value is a bare agent name (not a UUID, not a handle). */
+function isBareAgentName(value) {
+	return !value.includes("@") && !UUID_RE.test(value);
+}
+/** Fetch the org's agent list. Pure function — no caching. */
+async function fetchAgents(client) {
+	return (await client.get("/agents")).items;
+}
+/** Resolve a bare agent name against an agent list (case-insensitive). */
+function resolveBareName(agents, name) {
+	const lower = name.toLowerCase();
+	const match = agents.find((a) => a.name.toLowerCase() === lower);
+	if (match) return match.id;
+	const lines = agents.map((a) => `  ${a.name}  ${a.handle}`).join("\n");
+	throw new Error(agents.length > 0 ? `No agent named '${name}'. Available agents:\n${lines}` : `No agent named '${name}'. No active agents found.`);
+}
+/**
+* Resolve which agent ID to use.
+* Priority: explicit flag > asFlag > auto-resolve (single-agent shortcut).
+* Accepts UUIDs, handles, or bare names.
+*/
+async function resolveAgent(apiUrl, agents, explicit, asFlag) {
+	if (explicit) {
+		if (isBareAgentName(explicit)) return resolveBareName(agents, explicit);
+		return resolveToUuid(apiUrl, explicit);
+	}
+	if (asFlag) {
+		if (isBareAgentName(asFlag)) return resolveBareName(agents, asFlag);
+		return resolveToUuid(apiUrl, asFlag);
+	}
+	if (agents.length === 1) {
+		const agent = agents[0];
+		if (agent) return agent.id;
+	}
+	if (agents.length === 0) throw new Error("No active agents found.");
+	const lines = agents.map((a) => `  ${a.id}  ${a.handle}`).join("\n");
+	throw new Error(`Multiple agents found. Specify which agent to use:\n${lines}`);
+}
+//#endregion
+//#region src/timelock.ts
+function solveTimeLock(baseHex, modulusHex, T) {
+	const N = BigInt(`0x${modulusHex}`);
+	let x = BigInt(`0x${baseHex}`) % N;
+	for (let i = 0; i < T; i++) x = x * x % N;
+	return x.toString(16);
+}
+async function solveTimeLockWithProgress(baseHex, modulusHex, T, onProgress) {
+	const N = BigInt(`0x${modulusHex}`);
+	let x = BigInt(`0x${baseHex}`) % N;
+	const step = Math.max(1, Math.floor(T / 100));
+	for (let i = 0; i < T; i++) {
+		x = x * x % N;
+		if (i % step === 0) {
+			onProgress?.(Math.floor(i / T * 100));
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+	}
+	return x.toString(16);
+}
+//#endregion
+//#region src/crypto/hpke.ts
+const VERSION_HPKE = 1;
+const ENC_SIZE = 32;
+const INFO = new TextEncoder().encode("rine.e2ee.v1.hpke");
+const suite = new CipherSuite({
+	kem: new DhkemX25519HkdfSha256(),
+	kdf: new HkdfSha256(),
+	aead: new Aes256Gcm()
+});
+async function seal(recipientPublicKey, innerEnvelope, aad) {
+	const pk = await suite.kem.deserializePublicKey(recipientPublicKey);
+	const sender = await suite.createSenderContext({
+		recipientPublicKey: pk,
+		info: INFO
+	});
+	const ciphertext = new Uint8Array(await sender.seal(innerEnvelope, aad));
+	const enc = new Uint8Array(sender.enc);
+	const out = new Uint8Array(1 + ENC_SIZE + ciphertext.length);
+	out[0] = VERSION_HPKE;
+	out.set(enc, 1);
+	out.set(ciphertext, 1 + ENC_SIZE);
+	return out;
+}
+async function open(recipientPrivateKey, encryptedPayload, aad) {
+	if (encryptedPayload.length < 1 + ENC_SIZE + 1) throw new Error("encrypted payload too short");
+	const version = encryptedPayload[0];
+	if (version !== VERSION_HPKE) throw new Error(`unsupported version: 0x${version?.toString(16).padStart(2, "0")}`);
+	const enc = encryptedPayload.slice(1, 1 + ENC_SIZE);
+	const ct = encryptedPayload.slice(1 + ENC_SIZE);
+	const sk = await suite.kem.deserializePrivateKey(recipientPrivateKey);
+	const recipient = await suite.createRecipientContext({
+		recipientKey: sk,
+		enc,
+		info: INFO
+	});
+	return new Uint8Array(await recipient.open(ct, aad));
+}
+//#endregion
+//#region src/crypto/sign.ts
+function signPayload(signingPrivateKey, plaintext) {
+	return ed25519.sign(plaintext, signingPrivateKey);
+}
+function verifySignature(signingPublicKey, plaintext, signature) {
+	try {
+		return ed25519.verify(signature, plaintext, signingPublicKey);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/crypto/envelope.ts
+const SIGNATURE_SIZE = 64;
+const MAX_KID_LENGTH = 255;
+function encodeEnvelope(kid, signature, payload) {
+	const kidBytes = new TextEncoder().encode(kid);
+	if (kidBytes.length > MAX_KID_LENGTH) throw new Error(`kid too long: ${kidBytes.length} bytes (max ${MAX_KID_LENGTH})`);
+	if (signature.length !== SIGNATURE_SIZE) throw new Error(`signature must be ${SIGNATURE_SIZE} bytes, got ${signature.length}`);
+	const buf = new Uint8Array(1 + kidBytes.length + SIGNATURE_SIZE + payload.length);
+	buf[0] = kidBytes.length;
+	buf.set(kidBytes, 1);
+	buf.set(signature, 1 + kidBytes.length);
+	buf.set(payload, 1 + kidBytes.length + SIGNATURE_SIZE);
+	return buf;
+}
+function decodeEnvelope(data) {
+	if (data.length < 1 + SIGNATURE_SIZE) throw new Error("envelope too short");
+	const kidLen = data[0];
+	const minLen = 1 + kidLen + SIGNATURE_SIZE;
+	if (data.length < minLen) throw new Error("envelope too short for declared kid length");
+	return {
+		kid: new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(1, 1 + kidLen)),
+		signature: data.slice(1 + kidLen, 1 + kidLen + SIGNATURE_SIZE),
+		payload: data.slice(1 + kidLen + SIGNATURE_SIZE)
+	};
+}
+//#endregion
+//#region src/crypto/keys.ts
+function toBase64Url(bytes) {
+	return Buffer.from(bytes).toString("base64url");
+}
+function fromBase64Url(s) {
+	return new Uint8Array(Buffer.from(s, "base64url"));
+}
+function generateSigningKeyPair() {
+	const privateKey = ed25519.utils.randomSecretKey();
+	return {
+		privateKey,
+		publicKey: ed25519.getPublicKey(privateKey)
+	};
+}
+function generateEncryptionKeyPair() {
+	const privateKey = x25519.utils.randomSecretKey();
+	return {
+		privateKey,
+		publicKey: x25519.getPublicKey(privateKey)
+	};
+}
+function generateAgentKeys() {
+	return {
+		signing: generateSigningKeyPair(),
+		encryption: generateEncryptionKeyPair()
+	};
+}
+function signingPublicKeyToJWK(publicKey) {
+	return {
+		kty: "OKP",
+		crv: "Ed25519",
+		x: toBase64Url(publicKey)
+	};
+}
+function encryptionPublicKeyToJWK(publicKey) {
+	return {
+		kty: "OKP",
+		crv: "X25519",
+		x: toBase64Url(publicKey)
+	};
+}
+function jwkToPublicKey(jwk) {
+	const key = fromBase64Url(jwk.x);
+	if (key.length !== 32) throw new Error(`Invalid public key: expected 32 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);
+	if (!match) throw new Error(`Invalid sender KID format: ${kid}`);
+	return match[1];
+}
+const PATH_SAFE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function validatePathId(id, label) {
+	if (!PATH_SAFE_RE.test(id)) throw new Error(`Invalid ${label}: must be a UUID, got '${id}'`);
+}
+function saveAgentKeys(configDir, agentId, keys) {
+	validatePathId(agentId, "agent ID");
+	const dir = join(configDir, "keys", agentId);
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const sigPath = join(dir, "signing.key");
+	fs.writeFileSync(sigPath, toBase64Url(keys.signing.privateKey), "utf-8");
+	fs.chmodSync(sigPath, 384);
+	const encPath = join(dir, "encryption.key");
+	fs.writeFileSync(encPath, toBase64Url(keys.encryption.privateKey), "utf-8");
+	fs.chmodSync(encPath, 384);
+}
+function loadAgentKeys(configDir, agentId) {
+	validatePathId(agentId, "agent ID");
+	const dir = join(configDir, "keys", agentId);
+	const sigPriv = fromBase64Url(fs.readFileSync(join(dir, "signing.key"), "utf-8").trim());
+	if (sigPriv.length !== 32) throw new Error(`Corrupt signing key: expected 32 bytes, got ${sigPriv.length}`);
+	const sigPub = ed25519.getPublicKey(sigPriv);
+	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 {
+		signing: {
+			privateKey: sigPriv,
+			publicKey: sigPub
+		},
+		encryption: {
+			privateKey: encPriv,
+			publicKey: encPub
+		}
+	};
+}
+function agentKeysExist(configDir, agentId) {
+	validatePathId(agentId, "agent ID");
+	const dir = join(configDir, "keys", agentId);
+	return fs.existsSync(join(dir, "signing.key")) && fs.existsSync(join(dir, "encryption.key"));
+}
+//#endregion
+//#region src/crypto/sender-keys-helpers.ts
+function uuidToBytes(uuid) {
+	const matches = uuid.replace(/-/g, "").match(/../g);
+	if (!matches) throw new Error(`Invalid UUID: ${uuid}`);
+	return new Uint8Array(matches.map((b) => Number.parseInt(b, 16)));
+}
+function bytesToUuid(bytes) {
+	const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function saveSenderKeyState(configDir, agentId, groupId, states) {
+	validatePathId(agentId, "agent ID");
+	validatePathId(groupId, "group ID");
+	const dir = join(configDir, "keys", agentId, "sender_keys");
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const filePath = join(dir, `${groupId}.json`);
+	const data = states.map((s) => ({
+		...s,
+		chainKey: toBase64Url(s.chainKey)
+	}));
+	fs.writeFileSync(filePath, JSON.stringify(data), "utf-8");
+	fs.chmodSync(filePath, 384);
+}
+function loadSenderKeyStates(configDir, agentId, groupId) {
+	validatePathId(agentId, "agent ID");
+	validatePathId(groupId, "group ID");
+	const filePath = join(configDir, "keys", agentId, "sender_keys", `${groupId}.json`);
+	if (!fs.existsSync(filePath)) return [];
+	const raw = fs.readFileSync(filePath, "utf-8");
+	return JSON.parse(raw).map((s) => ({
+		...s,
+		chainKey: fromBase64Url(s.chainKey)
+	}));
+}
+//#endregion
+//#region src/crypto/sender-keys.ts
+const ROTATION_MESSAGE_LIMIT = 100;
+const ROTATION_AGE_MS = 10080 * 60 * 1e3;
+function needsRotation(state) {
+	if (state.messageIndex >= ROTATION_MESSAGE_LIMIT) return true;
+	if (state.createdAt && Date.now() - state.createdAt > ROTATION_AGE_MS) return true;
+	return false;
+}
+const VERSION_SENDER_KEY = 2;
+const SENDER_KEY_ID_SIZE = 16;
+const MESSAGE_INDEX_SIZE = 4;
+const NONCE_SIZE = 12;
+const MAX_SKIP = 1e3;
+/** Copy Uint8Array into a plain ArrayBuffer-backed Uint8Array (required by Web Crypto). */
+function toPlainBuffer(src) {
+	const buf = new Uint8Array(src.length);
+	buf.set(src);
+	return buf;
+}
+function generateSenderKey(groupId, senderAgentId) {
+	const chainKey = new Uint8Array(32);
+	crypto.getRandomValues(chainKey);
+	return {
+		senderKeyId: crypto.randomUUID(),
+		groupId,
+		senderAgentId,
+		chainKey,
+		messageIndex: 0,
+		createdAt: Date.now()
+	};
+}
+function deriveMessageKey(chainKey) {
+	return {
+		messageKey: hmac(sha256, chainKey, new Uint8Array([1])),
+		nextChainKey: hmac(sha256, chainKey, new Uint8Array([2]))
+	};
+}
+function advanceChain(state, targetIndex) {
+	if (targetIndex - state.messageIndex > MAX_SKIP) throw new Error(`too many skipped messages: ${targetIndex - state.messageIndex} (max ${MAX_SKIP})`);
+	const skippedKeys = /* @__PURE__ */ new Map();
+	let chainKey = state.chainKey;
+	let index = state.messageIndex;
+	while (index < targetIndex) {
+		const { messageKey, nextChainKey } = deriveMessageKey(chainKey);
+		skippedKeys.set(index, messageKey);
+		chainKey = nextChainKey;
+		index++;
+	}
+	return {
+		updatedState: {
+			...state,
+			chainKey,
+			messageIndex: index
+		},
+		skippedKeys
+	};
+}
+/** Build AAD for sender-key encryption: binds ciphertext to sender_key_id and message_index. */
+function buildSenderKeyAad(senderKeyId, messageIndex) {
+	const aad = new Uint8Array(SENDER_KEY_ID_SIZE + MESSAGE_INDEX_SIZE);
+	aad.set(senderKeyId, 0);
+	new DataView(aad.buffer).setUint32(SENDER_KEY_ID_SIZE, messageIndex, false);
+	return aad;
+}
+async function sealGroup(senderSigningPrivateKey, senderSigningKid, state, plaintext) {
+	const innerEnvelope = encodeEnvelope(senderSigningKid, signPayload(senderSigningPrivateKey, plaintext), plaintext);
+	const { messageKey, nextChainKey } = deriveMessageKey(state.chainKey);
+	const nonce = new Uint8Array(NONCE_SIZE);
+	crypto.getRandomValues(nonce);
+	const idBytes = uuidToBytes(state.senderKeyId);
+	const aad = buildSenderKeyAad(idBytes, state.messageIndex);
+	const cryptoKey = await crypto.subtle.importKey("raw", toPlainBuffer(messageKey), "AES-GCM", false, ["encrypt"]);
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv: nonce,
+		additionalData: toPlainBuffer(aad)
+	}, cryptoKey, toPlainBuffer(innerEnvelope)));
+	messageKey.fill(0);
+	const out = new Uint8Array(1 + SENDER_KEY_ID_SIZE + MESSAGE_INDEX_SIZE + NONCE_SIZE + ciphertext.length);
+	let offset = 0;
+	out[offset++] = VERSION_SENDER_KEY;
+	out.set(idBytes, offset);
+	offset += SENDER_KEY_ID_SIZE;
+	new DataView(out.buffer).setUint32(offset, state.messageIndex, false);
+	offset += MESSAGE_INDEX_SIZE;
+	out.set(nonce, offset);
+	offset += NONCE_SIZE;
+	out.set(ciphertext, offset);
+	return {
+		encryptedPayload: out,
+		updatedState: {
+			...state,
+			chainKey: nextChainKey,
+			messageIndex: state.messageIndex + 1
+		}
+	};
+}
+async function openGroup(senderKeyStates, encryptedPayload) {
+	const minLen = 1 + SENDER_KEY_ID_SIZE + MESSAGE_INDEX_SIZE + NONCE_SIZE;
+	if (encryptedPayload.length < minLen) throw new Error("encrypted payload too short");
+	const version = encryptedPayload[0];
+	if (version !== VERSION_SENDER_KEY) throw new Error(`unsupported version: 0x${version?.toString(16).padStart(2, "0")}`);
+	let offset = 1;
+	const senderKeyId = bytesToUuid(encryptedPayload.slice(offset, offset + SENDER_KEY_ID_SIZE));
+	offset += SENDER_KEY_ID_SIZE;
+	const messageIndex = new DataView(encryptedPayload.buffer, encryptedPayload.byteOffset).getUint32(offset, false);
+	offset += MESSAGE_INDEX_SIZE;
+	const nonce = encryptedPayload.slice(offset, offset + NONCE_SIZE);
+	offset += NONCE_SIZE;
+	const ciphertext = encryptedPayload.slice(offset);
+	const state = senderKeyStates.get(senderKeyId);
+	if (!state) throw new Error(`unknown sender key id: ${senderKeyId}`);
+	let messageKey;
+	let updatedState;
+	if (messageIndex < state.messageIndex) {
+		const cached = state.skippedKeys?.[messageIndex];
+		if (!cached) throw new Error("message key expired or already consumed");
+		messageKey = fromBase64Url(cached);
+		const newSkipped = { ...state.skippedKeys };
+		delete newSkipped[messageIndex];
+		updatedState = {
+			...state,
+			skippedKeys: newSkipped
+		};
+	} else if (messageIndex === state.messageIndex) {
+		const { messageKey: mk, nextChainKey } = deriveMessageKey(state.chainKey);
+		messageKey = mk;
+		updatedState = {
+			...state,
+			chainKey: nextChainKey,
+			messageIndex: state.messageIndex + 1
+		};
+	} else {
+		const { updatedState: advanced, skippedKeys: newSkipped } = advanceChain(state, messageIndex);
+		const { messageKey: mk, nextChainKey } = deriveMessageKey(advanced.chainKey);
+		messageKey = mk;
+		const mergedSkipped = { ...state.skippedKeys ?? {} };
+		for (const [idx, key] of newSkipped) {
+			mergedSkipped[idx] = toBase64Url(key);
+			key.fill(0);
+		}
+		const entries = Object.entries(mergedSkipped);
+		if (entries.length > MAX_SKIP) {
+			entries.sort((a, b) => Number(a[0]) - Number(b[0]));
+			const excess = entries.length - MAX_SKIP;
+			for (let i = 0; i < excess; i++) delete mergedSkipped[Number(entries[i][0])];
+		}
+		updatedState = {
+			...advanced,
+			chainKey: nextChainKey,
+			messageIndex: messageIndex + 1,
+			skippedKeys: mergedSkipped
+		};
+	}
+	const aad = buildSenderKeyAad(encryptedPayload.slice(1, 1 + SENDER_KEY_ID_SIZE), messageIndex);
+	const cryptoKey = await crypto.subtle.importKey("raw", toPlainBuffer(messageKey), "AES-GCM", false, ["decrypt"]);
+	const innerEnvelope = new Uint8Array(await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv: nonce,
+		additionalData: toPlainBuffer(aad)
+	}, cryptoKey, toPlainBuffer(ciphertext)));
+	messageKey.fill(0);
+	return {
+		innerEnvelope,
+		senderKeyId,
+		messageIndex,
+		updatedState
+	};
+}
+//#endregion
+//#region src/crypto/message.ts
+async function verifyEnvelopeSender(decoded, client) {
+	let verified = false;
+	let verificationStatus = "unverifiable";
+	try {
+		const senderAgentId = agentIdFromKid(decoded.kid);
+		verified = verifySignature(jwkToPublicKey((await client.get(`/agents/${senderAgentId}/keys`)).signing_public_key), decoded.payload, decoded.signature);
+		verificationStatus = verified ? "verified" : "invalid";
+	} catch {}
+	return {
+		verified,
+		verificationStatus
+	};
+}
+function signingKid(agentId) {
+	return `rine:${agentId}`;
+}
+async function encryptMessage(configDir, senderAgentId, recipientEncryptionPk, payload) {
+	const keys = loadAgentKeys(configDir, senderAgentId);
+	const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+	const kid = signingKid(senderAgentId);
+	return {
+		encrypted_payload: toBase64Url(await seal(recipientEncryptionPk, encodeEnvelope(kid, signPayload(keys.signing.privateKey, plaintext), plaintext))),
+		encryption_version: "hpke-v1",
+		sender_signing_kid: kid
+	};
+}
+async function fetchRecipientEncryptionKey(client, agentId) {
+	return jwkToPublicKey((await client.get(`/agents/${agentId}/keys`)).encryption_public_key);
+}
+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));
+	const plaintext = new TextDecoder("utf-8", { fatal: true }).decode(decoded.payload);
+	const { verified, verificationStatus } = await verifyEnvelopeSender(decoded, client);
+	return {
+		plaintext,
+		senderKid: decoded.kid,
+		verified,
+		verificationStatus
+	};
+}
+async function encryptGroupMessage(configDir, senderAgentId, groupId, senderKeyState, payload) {
+	const keys = loadAgentKeys(configDir, senderAgentId);
+	const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+	const kid = signingKid(senderAgentId);
+	const selfReadKey = deriveMessageKey(senderKeyState.chainKey).messageKey;
+	const selfReadIndex = senderKeyState.messageIndex;
+	const { encryptedPayload, updatedState } = await sealGroup(keys.signing.privateKey, kid, senderKeyState, plaintext);
+	updatedState.skippedKeys = {
+		...updatedState.skippedKeys ?? {},
+		[selfReadIndex]: toBase64Url(selfReadKey)
+	};
+	selfReadKey.fill(0);
+	saveSenderKeyState(configDir, senderAgentId, groupId, [...loadSenderKeyStates(configDir, senderAgentId, groupId).filter((s) => s.senderKeyId !== updatedState.senderKeyId), updatedState]);
+	return {
+		result: {
+			encrypted_payload: toBase64Url(encryptedPayload),
+			encryption_version: "sender-key-v1",
+			sender_signing_kid: kid
+		},
+		updatedState
+	};
+}
+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 decoded = decodeEnvelope(innerEnvelope);
+	const plaintext = new TextDecoder("utf-8", { fatal: true }).decode(decoded.payload);
+	const { verified, verificationStatus } = await verifyEnvelopeSender(decoded, client);
+	if (verificationStatus === "invalid") throw new Error("Sender signature verification failed");
+	if (updatedState.senderAgentId === recipientAgentId) {
+		const prevCached = stateMap.get(updatedState.senderKeyId)?.skippedKeys?.[messageIndex];
+		if (prevCached && !updatedState.skippedKeys?.[messageIndex]) updatedState.skippedKeys = {
+			...updatedState.skippedKeys ?? {},
+			[messageIndex]: prevCached
+		};
+	}
+	stateMap.set(updatedState.senderKeyId, updatedState);
+	saveSenderKeyState(configDir, recipientAgentId, groupId, Array.from(stateMap.values()));
+	return {
+		plaintext,
+		senderKid: decoded.kid,
+		verified,
+		verificationStatus
+	};
+}
+function getAgentPublicKeys(configDir, agentId, agentKeys) {
+	const keys = agentKeys ?? loadAgentKeys(configDir, agentId);
+	return {
+		signing_public_key: signingPublicKeyToJWK(keys.signing.publicKey),
+		encryption_public_key: {
+			kty: "OKP",
+			crv: "X25519",
+			x: toBase64Url(keys.encryption.publicKey)
+		}
+	};
+}
+//#endregion
+//#region src/crypto/ingest.ts
+/**
+* Auto-ingest a sender key distribution from a decrypted message.
+* Only ingests if the message is a `rine.v1.sender_key_distribution`,
+* the signature was verified, and the key ID is not already known.
+*
+* Returns true if a new key was ingested.
+*/
+function ingestSenderKeyDistribution(configDir, agentId, messageType, result) {
+	if (messageType !== "rine.v1.sender_key_distribution") return false;
+	if (!result.verified) return false;
+	try {
+		const dist = JSON.parse(result.plaintext);
+		const existing = loadSenderKeyStates(configDir, agentId, dist.group_id);
+		if (existing.some((s) => s.senderKeyId === dist.sender_key_id)) return false;
+		const newState = {
+			senderKeyId: dist.sender_key_id,
+			groupId: dist.group_id,
+			senderAgentId: agentIdFromKid(result.senderKid),
+			chainKey: fromBase64Url(dist.chain_key),
+			messageIndex: dist.message_index
+		};
+		saveSenderKeyState(configDir, agentId, dist.group_id, [...existing, newState]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/sender-key-ops.ts
+/**
+* Distribute a sender key to group members via encrypted DMs.
+* Returns which recipients succeeded/failed.
+*/
+async function distributeSenderKey(client, configDir, senderAgentId, state, groupId, recipientIds, extraHeaders) {
+	if (recipientIds.length === 0) return {
+		succeeded: [],
+		failed: []
+	};
+	const batchKeys = await client.get("/agents/keys", { ids: recipientIds.join(",") });
+	const distPayload = {
+		group_id: groupId,
+		sender_key_id: state.senderKeyId,
+		chain_key: toBase64Url(state.chainKey),
+		message_index: state.messageIndex,
+		sender_agent_id: senderAgentId
+	};
+	const succeeded = [];
+	const failed = [];
+	for (const recipientId of recipientIds) {
+		const recipientKeyData = batchKeys.keys[recipientId];
+		if (!recipientKeyData) {
+			failed.push(recipientId);
+			continue;
+		}
+		try {
+			const encrypted = await encryptMessage(configDir, senderAgentId, fromBase64Url(recipientKeyData.encryption_public_key.x), distPayload);
+			await client.post("/messages", {
+				to_agent_id: recipientId,
+				type: "rine.v1.sender_key_distribution",
+				...encrypted
+			}, extraHeaders);
+			succeeded.push(recipientId);
+		} catch {
+			failed.push(recipientId);
+		}
+	}
+	return {
+		succeeded,
+		failed
+	};
+}
+/**
+* Get or create a sender key for a group, distributing it to members as needed.
+* Handles rotation on member removal, periodic rotation, and new key generation.
+*/
+async function getOrCreateSenderKey(client, configDir, senderAgentId, groupHandle, extraHeaders) {
+	const firstGroup = (await client.get("/groups", { handle: groupHandle })).items?.[0];
+	if (!firstGroup) throw new Error(`Group not found: ${groupHandle}`);
+	const groupId = firstGroup.id;
+	const memberIds = (await client.get(`/groups/${groupId}/members`)).items.map((m) => m.agent_id);
+	const senderIdLower = senderAgentId.toLowerCase();
+	if (!memberIds.some((id) => id.toLowerCase() === senderIdLower)) throw new Error("You are not a member of this group");
+	const recipientIds = memberIds.filter((id) => id.toLowerCase() !== senderIdLower);
+	const states = loadSenderKeyStates(configDir, senderAgentId, groupId);
+	const own = states.find((s) => s.senderAgentId === senderAgentId);
+	const currentMemberSet = new Set(memberIds.map((id) => id.toLowerCase()));
+	const memberRemoved = own?.distributedTo?.some((id) => !currentMemberSet.has(id.toLowerCase())) ?? false;
+	if (own && !needsRotation(own) && !memberRemoved) {
+		const alreadyDistributed = new Set((own.distributedTo ?? []).map((id) => id.toLowerCase()));
+		const undistributed = recipientIds.filter((id) => !alreadyDistributed.has(id.toLowerCase()));
+		if (undistributed.length > 0) {
+			const { succeeded } = await distributeSenderKey(client, configDir, senderAgentId, own, groupId, undistributed, extraHeaders);
+			if (succeeded.length > 0) {
+				own.distributedTo = [...own.distributedTo ?? [], ...succeeded];
+				saveSenderKeyState(configDir, senderAgentId, groupId, states);
+			}
+		}
+		return {
+			state: own,
+			groupId
+		};
+	}
+	const newState = generateSenderKey(groupId, senderAgentId);
+	const { succeeded } = await distributeSenderKey(client, configDir, senderAgentId, newState, groupId, recipientIds, extraHeaders);
+	newState.distributedTo = succeeded;
+	saveSenderKeyState(configDir, senderAgentId, groupId, [...memberRemoved ? states.filter((s) => currentMemberSet.has(s.senderAgentId.toLowerCase())) : states, newState]);
+	return {
+		state: newState,
+		groupId
+	};
+}
+//#endregion
+export { DEFAULT_API_URL, HttpClient, RineApiError, UUID_RE, advanceChain, agentIdFromKid, agentKeysExist, bytesToUuid, cacheToken, decodeEnvelope, decryptGroupMessage, decryptMessage, deriveMessageKey, distributeSenderKey, encodeEnvelope, encryptGroupMessage, encryptMessage, encryptionPublicKeyToJWK, fetchAgents, fetchOAuthToken, fetchRecipientEncryptionKey, formatError, fromBase64Url, generateAgentKeys, generateEncryptionKeyPair, generateSenderKey, generateSigningKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, isBareAgentName, jwkToPublicKey, loadAgentKeys, loadCredentials, loadSenderKeyStates, loadTokenCache, needsRotation, open, openGroup, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, saveSenderKeyState, saveTokenCache, seal, sealGroup, signPayload, signingPublicKeyToJWK, solveTimeLock, solveTimeLockWithProgress, toBase64Url, uuidToBytes, validatePathId, verifySignature };