@minionry/minion 0.7.36

package/dist/server/services/e2ee-group-key.js

@@ -0,0 +1,197 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomBytes } from 'node:crypto';
+import { deriveKey, seal, toBase64Url, utf8Encode, } from '@minionry/e2ee';
+import { agreeWithPeerPublicKey, E2EE_PUBLIC_KEY_PATTERN, ensureE2eeIdentity, } from './e2ee-identity.js';
+const GROUP_KEY_BYTES = 32;
+export const INITIAL_GROUP_KEY_EPOCH = 1;
+export const RETAINED_PRIOR_EPOCHS = 2;
+const MAX_WRAP_CONTEXTS = 256;
+export const KEK_SALT = new Uint8Array(32);
+export function kekInfo(cliIdentityPublicKey, webEphemeralPublicKey) {
+    return `minionry/e2ee/kek/v1|${cliIdentityPublicKey}|${webEphemeralPublicKey}`;
+}
+export const KEY_DELIVERY_AAD_LABEL = 'minionry/e2ee/key-delivery/v1';
+export function keyDeliveryAad(cliIdentityPublicKey, webEphemeralPublicKey) {
+    return utf8Encode(`${KEY_DELIVERY_AAD_LABEL}|${cliIdentityPublicKey}|${webEphemeralPublicKey}`);
+}
+const sessions = new Map();
+function retireCurrentKey(session) {
+    if (!session.material)
+        return;
+    session.retired.unshift({ epoch: session.epoch, material: session.material });
+    session.material = null;
+    while (session.retired.length > RETAINED_PRIOR_EPOCHS) {
+        const expired = session.retired.pop();
+        expired?.material.fill(0);
+    }
+}
+function ensureGroupKeySession(orchestraKey) {
+    let session = sessions.get(orchestraKey);
+    if (!session) {
+        session = {
+            material: new Uint8Array(randomBytes(GROUP_KEY_BYTES)),
+            epoch: INITIAL_GROUP_KEY_EPOCH,
+            retired: [],
+            wrapContexts: new Map(),
+        };
+        sessions.set(orchestraKey, session);
+        return session;
+    }
+    if (!session.material) {
+        session.epoch++;
+        session.material = new Uint8Array(randomBytes(GROUP_KEY_BYTES));
+    }
+    return session;
+}
+function rotateGroupKeySession(orchestraKey) {
+    const session = sessions.get(orchestraKey);
+    if (!session)
+        return null;
+    retireCurrentKey(session);
+    session.epoch++;
+    session.material = new Uint8Array(randomBytes(GROUP_KEY_BYTES));
+    return session;
+}
+function enterCleartextEpoch(orchestraKey) {
+    const session = sessions.get(orchestraKey);
+    if (!session?.material)
+        return;
+    retireCurrentKey(session);
+    session.epoch++;
+}
+export async function deriveFromGroupKey(orchestraKey, salt, info) {
+    const session = sessions.get(orchestraKey);
+    if (!session?.material)
+        return null;
+    return { key: await deriveKey(session.material, salt, info), epoch: session.epoch };
+}
+export async function deriveFromGroupKeyForEpoch(orchestraKey, epoch, salt, info) {
+    const session = sessions.get(orchestraKey);
+    if (!session)
+        return null;
+    let material = null;
+    if (session.material && session.epoch === epoch) {
+        material = session.material;
+    }
+    else {
+        material = session.retired.find((r) => r.epoch === epoch)?.material ?? null;
+    }
+    if (!material)
+        return null;
+    return { key: await deriveKey(material, salt, info), epoch };
+}
+export function getGroupKeyEpochState(orchestraKey) {
+    const session = sessions.get(orchestraKey);
+    if (!session)
+        return null;
+    return { epoch: session.epoch, cleartext: session.material === null };
+}
+export function dropGroupKeyWrapContext(orchestraKey, viewerId) {
+    sessions.get(orchestraKey)?.wrapContexts.delete(viewerId);
+}
+export function resetE2eeGroupKeysForTests() {
+    sessions.clear();
+}
+function warn(message) {
+    console.warn(`[e2ee] ${message}`);
+}
+async function sealGroupKeyEnvelope(viewerId, webEphemeralPublicKey, session) {
+    if (!session.material)
+        throw new Error('no key material in the current epoch');
+    const identity = await ensureE2eeIdentity();
+    if (!identity.available || !identity.publicKey) {
+        throw new Error('this device has no usable E2EE identity');
+    }
+    const sharedSecret = await agreeWithPeerPublicKey(webEphemeralPublicKey);
+    const kek = await deriveKey(sharedSecret, KEK_SALT, kekInfo(identity.publicKey, webEphemeralPublicKey));
+    const plaintext = utf8Encode(JSON.stringify({ key: toBase64Url(session.material), epoch: session.epoch }));
+    const aad = keyDeliveryAad(identity.publicKey, webEphemeralPublicKey);
+    const box = await seal(kek, plaintext, aad);
+    return {
+        v: 1,
+        type: 'e2ee_key',
+        enc: false,
+        to: viewerId,
+        payload: {
+            data: {
+                publicKey: webEphemeralPublicKey,
+                sealed: { n: toBase64Url(box.nonce), c: toBase64Url(box.ct) },
+            },
+        },
+    };
+}
+function recordWrapContext(session, viewerId, webEphemeralPublicKey) {
+    if (!session.wrapContexts.has(viewerId) && session.wrapContexts.size >= MAX_WRAP_CONTEXTS) {
+        const oldest = session.wrapContexts.keys().next().value;
+        if (oldest !== undefined)
+            session.wrapContexts.delete(oldest);
+    }
+    session.wrapContexts.set(viewerId, webEphemeralPublicKey);
+}
+export async function handleE2eeKeyRequest(message, ctx) {
+    try {
+        if (ctx.visibility === 'public') {
+            warn('Ignoring a group-key request: this Space is public (cleartext by design)');
+            return;
+        }
+        const viewerId = message._viewer;
+        if (typeof viewerId !== 'string' || viewerId.length === 0) {
+            warn('Ignoring a group-key request without a relay-assigned viewer id (older relay?)');
+            return;
+        }
+        const data = message.data;
+        const rawKey = message.publicKey ?? data?.publicKey;
+        const webEphemeralPublicKey = typeof rawKey === 'string' && E2EE_PUBLIC_KEY_PATTERN.test(rawKey) ? rawKey : null;
+        if (!webEphemeralPublicKey) {
+            warn('Ignoring a group-key request with a missing or malformed ephemeral public key');
+            return;
+        }
+        const session = ensureGroupKeySession(ctx.orchestraKey);
+        const envelope = await sealGroupKeyEnvelope(viewerId, webEphemeralPublicKey, session);
+        ctx.sendEnvelope(envelope);
+        recordWrapContext(session, viewerId, webEphemeralPublicKey);
+    }
+    catch (err) {
+        warn(`Group-key delivery failed (${err instanceof Error ? err.message : String(err)}) — the requester will retry or fall back to cleartext`);
+    }
+}
+export async function handleE2eeMembershipChange(message, ctx) {
+    try {
+        const KNOWN_CHANGES = new Set([
+            'share_added',
+            'role_changed',
+            'share_revoked',
+            'share_blocked',
+            'share_unblocked',
+            'visibility_changed',
+        ]);
+        const change = typeof message.change === 'string' && KNOWN_CHANGES.has(message.change)
+            ? message.change
+            : 'membership_changed';
+        if (ctx.visibility === 'public') {
+            enterCleartextEpoch(ctx.orchestraKey);
+            warn(`Space is public after '${change}' — entered the cleartext epoch, encryption off`);
+            return;
+        }
+        const session = rotateGroupKeySession(ctx.orchestraKey);
+        if (!session)
+            return;
+        let pushed = 0;
+        for (const [viewerId, webEphemeralPublicKey] of [...session.wrapContexts]) {
+            try {
+                const envelope = await sealGroupKeyEnvelope(viewerId, webEphemeralPublicKey, session);
+                ctx.sendEnvelope(envelope);
+                pushed++;
+            }
+            catch {
+                session.wrapContexts.delete(viewerId);
+                warn('Dropped a wrap context that failed to re-seal during rotation');
+            }
+        }
+        warn(`Rotated the group key on '${change}' (epoch ${session.epoch}); re-sealed to ${pushed} connected session(s)`);
+    }
+    catch (err) {
+        warn(`Group-key rotation failed (${err instanceof Error ? err.message : String(err)}) — keys unchanged`);
+    }
+}

package/dist/server/services/e2ee-identity.js

@@ -0,0 +1,203 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { chmodSync, existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { agree, deriveSafetyNumber, fromBase64Url, generateIdentityKeyPair, toBase64Url, } from '@minionry/e2ee';
+import { ensureMachineDir, machineFile } from '../../bin/machine-layout.js';
+import { getCredentials } from './platform-credentials.js';
+import { resolvePlatformUrl } from './platform-url.js';
+const IDENTITY_FILE_VERSION = 1;
+export const E2EE_PUBLIC_KEY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+export function getE2eeIdentityPath() {
+    return machineFile('e2eeIdentity');
+}
+function warn(message) {
+    console.warn(`[e2ee] ${message}`);
+}
+function unavailable(reason) {
+    return { available: false, publicKey: null, reason };
+}
+let cachedStatus = null;
+let cachedPrivateKey = null;
+let ensureInFlight = null;
+export function ensureE2eeIdentity() {
+    if (cachedStatus)
+        return Promise.resolve({ ...cachedStatus });
+    ensureInFlight ??= loadOrGenerate()
+        .then((result) => {
+        cachedStatus = result.status;
+        cachedPrivateKey = result.privateKey;
+        return { ...result.status };
+    })
+        .finally(() => {
+        ensureInFlight = null;
+    });
+    return ensureInFlight;
+}
+export async function agreeWithPeerPublicKey(theirPublicKeyBase64Url) {
+    const status = await ensureE2eeIdentity();
+    if (!status.available || !cachedPrivateKey) {
+        throw new Error(`e2ee identity unavailable${status.reason ? `: ${status.reason}` : ''}`);
+    }
+    return agree(fromBase64Url(theirPublicKeyBase64Url), cachedPrivateKey);
+}
+export function safetyNumberFor(publicKeyA, publicKeyB) {
+    return deriveSafetyNumber(fromBase64Url(publicKeyA), fromBase64Url(publicKeyB));
+}
+export async function deriveSessionSafetyNumber(peerPublicKeyBase64Url) {
+    const status = await ensureE2eeIdentity();
+    if (!status.available || !status.publicKey) {
+        throw new Error(`e2ee identity unavailable${status.reason ? `: ${status.reason}` : ''}`);
+    }
+    return safetyNumberFor(status.publicKey, peerPublicKeyBase64Url);
+}
+export const REGISTRATION_RETRY_DELAYS_MS = [
+    60_000,
+    120_000,
+    600_000,
+    1_800_000,
+];
+let registrationRetryTimer = null;
+export async function registerE2eeIdentityWithPlatform(platformUrl, options) {
+    const base = platformUrl ?? resolvePlatformUrl();
+    const outcome = await attemptRegistration(base);
+    if (outcome === 'retryable') {
+        scheduleRegistrationRetry(base, options?.retryDelaysMs ?? REGISTRATION_RETRY_DELAYS_MS, 0);
+    }
+    return outcome === 'registered';
+}
+async function attemptRegistration(base) {
+    const status = await ensureE2eeIdentity();
+    if (!status.available || !status.publicKey)
+        return 'permanent';
+    const creds = getCredentials();
+    if (!creds?.token)
+        return 'permanent';
+    try {
+        const response = await fetch(`${base}/api/auth/device/e2ee-key`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ e2eePublicKey: status.publicKey }),
+        });
+        if (response.ok)
+            return 'registered';
+        const retryable = response.status === 429 || response.status >= 500;
+        warn(`Public-key registration returned ${response.status} — ${retryable ? 'will retry' : 'continuing without E2EE registration (older relay?)'}`);
+        return retryable ? 'retryable' : 'permanent';
+    }
+    catch (err) {
+        warn(`Public-key registration failed (${err instanceof Error ? err.message : String(err)}) — will retry`);
+        return 'retryable';
+    }
+}
+function scheduleRegistrationRetry(base, delays, attempt) {
+    if (delays.length === 0)
+        return;
+    const delay = delays[Math.min(attempt, delays.length - 1)];
+    const jittered = Math.round(delay * (0.75 + Math.random() * 0.5));
+    if (registrationRetryTimer)
+        clearTimeout(registrationRetryTimer);
+    registrationRetryTimer = setTimeout(() => {
+        registrationRetryTimer = null;
+        void attemptRegistration(base).then((outcome) => {
+            if (outcome === 'retryable')
+                scheduleRegistrationRetry(base, delays, attempt + 1);
+        });
+    }, jittered);
+    registrationRetryTimer.unref();
+}
+export function resetE2eeIdentityForTests() {
+    cachedStatus = null;
+    cachedPrivateKey = null;
+    ensureInFlight = null;
+    if (registrationRetryTimer) {
+        clearTimeout(registrationRetryTimer);
+        registrationRetryTimer = null;
+    }
+}
+async function loadOrGenerate() {
+    try {
+        if (existsSync(getE2eeIdentityPath())) {
+            return loadExisting();
+        }
+        return await generateAndPersist();
+    }
+    catch (err) {
+        warn(`Unexpected identity failure (${err instanceof Error ? err.message : String(err)}) — continuing WITHOUT end-to-end encryption`);
+        return { status: unavailable('unexpected identity failure'), privateKey: null };
+    }
+}
+function loadExisting() {
+    const path = getE2eeIdentityPath();
+    if (process.platform !== 'win32') {
+        const mode = statSync(path).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            warn(`Identity key file ${path} has unsafe permissions (0${mode.toString(8)}, expected 0600) — continuing WITHOUT end-to-end encryption. Fix with: chmod 600 ${path}`);
+            return { status: unavailable('identity file has unsafe permissions (expected 0600)'), privateKey: null };
+        }
+    }
+    try {
+        const record = JSON.parse(readFileSync(path, 'utf-8'));
+        if (record.v !== IDENTITY_FILE_VERSION) {
+            warn(`Identity key file ${path} has an unsupported format version — continuing WITHOUT end-to-end encryption. Upgrade the CLI, or delete the file to generate a fresh identity on next login.`);
+            return { status: unavailable('identity file version is not supported by this CLI'), privateKey: null };
+        }
+        const publicKey = record.publicKey;
+        const privateKeyB64u = record.privateKey;
+        if (typeof publicKey !== 'string' ||
+            !E2EE_PUBLIC_KEY_PATTERN.test(publicKey) ||
+            typeof privateKeyB64u !== 'string') {
+            throw new Error('malformed identity record');
+        }
+        const privateKey = fromBase64Url(privateKeyB64u);
+        if (privateKey.length < 32) {
+            throw new Error('malformed identity record');
+        }
+        return { status: { available: true, publicKey }, privateKey };
+    }
+    catch {
+        warn(`Identity key file ${path} is unreadable or corrupt — continuing WITHOUT end-to-end encryption. Delete the file to generate a fresh identity on next login (peers will re-pin the new key).`);
+        return { status: unavailable('identity file is unreadable or corrupt'), privateKey: null };
+    }
+}
+async function generateAndPersist() {
+    const generated = await generateIdentityKeyPair().catch((err) => {
+        warn(`This runtime cannot generate an X25519 identity key (${err instanceof Error ? err.message : String(err)}) — continuing WITHOUT end-to-end encryption`);
+        return null;
+    });
+    if (!generated) {
+        return { status: unavailable('key generation unsupported on this runtime'), privateKey: null };
+    }
+    const publicKey = toBase64Url(generated.publicKey);
+    const record = `${JSON.stringify({
+        v: IDENTITY_FILE_VERSION,
+        publicKey,
+        privateKey: toBase64Url(generated.privateKey),
+        createdAt: new Date().toISOString(),
+    }, null, 2)}\n`;
+    const path = getE2eeIdentityPath();
+    const tmpPath = `${path}.${process.pid}.tmp`;
+    try {
+        ensureMachineDir('credentials');
+        writeFileSync(tmpPath, record, { mode: 0o600 });
+        try {
+            chmodSync(tmpPath, 0o600);
+            renameSync(tmpPath, path);
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        warn(`Could not persist the identity key (${err instanceof Error ? err.message : String(err)}) — continuing WITHOUT end-to-end encryption`);
+        return { status: unavailable('could not persist identity key'), privateKey: null };
+    }
+    return { status: { available: true, publicKey }, privateKey: generated.privateKey };
+}