@minionry/minion 0.7.36

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

@@ -0,0 +1,421 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { buildAad, counterNonce, fromBase64Url, isContentMessageType, open, seal, toBase64Url, utf8Decode, utf8Encode, } from '@minionry/e2ee';
+import { deriveFromGroupKey, deriveFromGroupKeyForEpoch, getGroupKeyEpochState, } from './e2ee-group-key.js';
+import { E2EE_CONTENT_VERSION, ENVELOPE_VERSION, isNeverSealedType, unwrapEnvelopeV1, } from './platform-envelope.js';
+export const CONTENT_KEY_SALT = new Uint8Array(32);
+export function contentKeyInfo(sid) {
+    return `minionry/e2ee/content/v1|${sid}`;
+}
+const REKEY_HINT_AFTER_CONSECUTIVE_FAILURES = 3;
+const MAX_TRACKED_SENDERS = 256;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function shouldSealContent(type, decision) {
+    return (!isNeverSealedType(type) &&
+        decision.visibility !== 'public' &&
+        decision.allViewersCapable &&
+        decision.keyAvailable &&
+        isContentMessageType(type));
+}
+export function readViewerE2eeCapability(message) {
+    const advertised = message.e2ee;
+    if (advertised === E2EE_CONTENT_VERSION)
+        return true;
+    return isRecord(advertised) && advertised.v === E2EE_CONTENT_VERSION;
+}
+const outboundSequences = new Map();
+function nextOutboundSeq(orchestraKey, epoch) {
+    const key = `${orchestraKey}|${epoch}`;
+    const next = (outboundSequences.get(key) ?? 0) + 1;
+    outboundSequences.set(key, next);
+    return next;
+}
+export function resetE2eeContentSequencesForTests() {
+    outboundSequences.clear();
+}
+function readSealedEnvelopeFields(envelope) {
+    if (envelope.enc !== true)
+        return null;
+    const { type, sid, seq, epoch } = envelope;
+    if (typeof type !== 'string' || type.length === 0)
+        return null;
+    if (!isContentMessageType(type))
+        return null;
+    if (typeof sid !== 'string' || sid.length === 0)
+        return null;
+    if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0)
+        return null;
+    if (typeof epoch !== 'number' || !Number.isSafeInteger(epoch) || epoch < 0)
+        return null;
+    const box = readSealedBox(envelope.payload);
+    if (!box)
+        return null;
+    return { type, sid, seq, epoch, box };
+}
+function readSealedBox(payload) {
+    if (!isRecord(payload))
+        return null;
+    const { n, c } = payload;
+    if (typeof n !== 'string' || typeof c !== 'string')
+        return null;
+    try {
+        const nonce = fromBase64Url(n);
+        const ct = fromBase64Url(c);
+        if (nonce.length !== 12)
+            return null;
+        return { nonce, ct };
+    }
+    catch {
+        return null;
+    }
+}
+function warn(message) {
+    console.warn(`[e2ee] ${message}`);
+}
+export class E2eeContentCodec {
+    ctx;
+    viewers = new Map();
+    keyEpoch = null;
+    cleartextEpoch = null;
+    senderKey = null;
+    receiverKeys = new Map();
+    inboundLastSeq = new Map();
+    outboundChain = Promise.resolve();
+    outboundPending = 0;
+    inboundChain = Promise.resolve();
+    inboundPending = 0;
+    keyProbe = Promise.resolve();
+    consecutiveOpenFailures = 0;
+    openFailureWarned = false;
+    rekeyHintSent = false;
+    replayWarned = false;
+    cleartextWhileKeyedWarned = false;
+    sealFailureWarned = false;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    onSocketReset() {
+        this.viewers.clear();
+        this.consecutiveOpenFailures = 0;
+        this.openFailureWarned = false;
+        this.rekeyHintSent = false;
+        this.replayWarned = false;
+        this.cleartextWhileKeyedWarned = false;
+        this.sealFailureWarned = false;
+    }
+    onViewerConnected(viewerId, message) {
+        this.markViewer(viewerId, readViewerE2eeCapability(message));
+    }
+    onViewerDisconnected(viewerId) {
+        this.viewers.delete(viewerId);
+    }
+    onKeyRequestSettled(message) {
+        const viewerId = message._viewer;
+        if (typeof viewerId === 'string' && viewerId.length > 0) {
+            this.markViewer(viewerId, true);
+        }
+        this.refreshKeyState();
+    }
+    onGroupKeyRotated() {
+        this.refreshKeyState();
+    }
+    refreshKeyState() {
+        const probe = deriveFromGroupKey(this.ctx.orchestraKey, CONTENT_KEY_SALT, contentKeyInfo(this.ctx.orchestraKey));
+        this.senderKey = probe;
+        this.keyProbe = probe.then((derived) => {
+            this.keyEpoch = derived ? derived.epoch : null;
+            const state = getGroupKeyEpochState(this.ctx.orchestraKey);
+            this.cleartextEpoch = state?.cleartext ? state.epoch : null;
+        }, () => {
+            this.keyEpoch = null;
+            this.cleartextEpoch = null;
+        });
+    }
+    markViewer(viewerId, capable) {
+        const existing = this.viewers.get(viewerId);
+        if (existing === undefined && this.viewers.size >= MAX_TRACKED_SENDERS) {
+            const oldest = this.viewers.keys().next().value;
+            if (oldest !== undefined)
+                this.viewers.delete(oldest);
+        }
+        this.viewers.set(viewerId, existing === true || capable);
+    }
+    allViewersCapable() {
+        for (const capable of this.viewers.values()) {
+            if (!capable)
+                return false;
+        }
+        return true;
+    }
+    currentDecision() {
+        return {
+            visibility: this.ctx.getVisibility(),
+            allViewersCapable: this.allViewersCapable(),
+            keyAvailable: this.keyEpoch !== null,
+        };
+    }
+    sendOutbound(wire, write) {
+        if (!this.isContentEnvelope(wire)) {
+            write(JSON.stringify(wire));
+            return;
+        }
+        const type = wire.type;
+        if (this.outboundPending === 0 && !shouldSealContent(type, this.currentDecision())) {
+            write(JSON.stringify(this.tagCleartextEpoch(wire)));
+            return;
+        }
+        this.outboundPending++;
+        this.outboundChain = this.outboundChain.then(async () => {
+            try {
+                if (shouldSealContent(type, this.currentDecision())) {
+                    const sealed = await this.sealContentEnvelope(wire);
+                    if (sealed) {
+                        write(JSON.stringify(sealed));
+                    }
+                    else {
+                        this.warnSealFailureOnce();
+                    }
+                }
+                else {
+                    write(JSON.stringify(this.tagCleartextEpoch(wire)));
+                }
+            }
+            catch {
+                this.warnSealFailureOnce();
+            }
+            finally {
+                this.outboundPending--;
+            }
+        });
+    }
+    tagCleartextEpoch(wire) {
+        if (this.cleartextEpoch === null)
+            return wire;
+        const { to, payload, ...rest } = wire;
+        const tagged = { ...rest, epoch: this.cleartextEpoch };
+        if (to !== undefined)
+            tagged.to = to;
+        tagged.payload = payload;
+        return tagged;
+    }
+    isContentEnvelope(wire) {
+        return (isRecord(wire) &&
+            typeof wire.v === 'number' &&
+            wire.v >= 1 &&
+            wire.enc === false &&
+            typeof wire.type === 'string' &&
+            isContentMessageType(wire.type) &&
+            isRecord(wire.payload));
+    }
+    async sealContentEnvelope(envelope) {
+        const derived = await (this.senderKey ?? Promise.resolve(null));
+        if (!derived)
+            return null;
+        const type = envelope.type;
+        const msgId = typeof envelope.msgId === 'string' ? envelope.msgId : undefined;
+        const seq = nextOutboundSeq(this.ctx.orchestraKey, derived.epoch);
+        const aad = buildAad({
+            v: ENVELOPE_VERSION,
+            type,
+            msgId: msgId ?? null,
+            sid: this.ctx.orchestraKey,
+            dir: 'cw',
+            seq,
+            epoch: derived.epoch,
+        });
+        const plaintext = utf8Encode(JSON.stringify(envelope.payload));
+        const box = await seal(derived.key, plaintext, aad, counterNonce('cw', seq));
+        const sealed = { v: ENVELOPE_VERSION, type };
+        if (msgId !== undefined)
+            sealed.msgId = msgId;
+        if (typeof envelope.tabId === 'string')
+            sealed.tabId = envelope.tabId;
+        sealed.enc = true;
+        sealed.sid = this.ctx.orchestraKey;
+        sealed.seq = seq;
+        sealed.epoch = derived.epoch;
+        if (typeof envelope.to === 'string')
+            sealed.to = envelope.to;
+        sealed.payload = { n: toBase64Url(box.nonce), c: toBase64Url(box.ct) };
+        return sealed;
+    }
+    warnSealFailureOnce() {
+        if (this.sealFailureWarned)
+            return;
+        this.sealFailureWarned = true;
+        warn('Dropped outbound content that failed to seal (fail-closed) — further drops muted');
+    }
+    handleSealedInbound(envelope, dispatch) {
+        this.inboundPending++;
+        this.inboundChain = this.inboundChain.then(async () => {
+            try {
+                const legacy = await this.openContentEnvelope(envelope);
+                if (legacy)
+                    this.dispatchGuarded(legacy, dispatch);
+            }
+            catch {
+                this.noteOpenFailure();
+            }
+            finally {
+                this.inboundPending--;
+            }
+        });
+    }
+    dispatchInboundContent(message, dispatch) {
+        if (this.keyEpoch !== null &&
+            typeof message.type === 'string' &&
+            isContentMessageType(message.type) &&
+            !this.cleartextWhileKeyedWarned) {
+            this.cleartextWhileKeyedWarned = true;
+            warn('Receiving cleartext content while a group key is held — session is (partially) cleartext');
+        }
+        if (this.inboundPending === 0) {
+            dispatch(message);
+            return;
+        }
+        this.inboundPending++;
+        this.inboundChain = this.inboundChain.then(() => {
+            try {
+                this.dispatchGuarded(message, dispatch);
+            }
+            finally {
+                this.inboundPending--;
+            }
+        });
+    }
+    dispatchGuarded(message, dispatch) {
+        try {
+            dispatch(message);
+        }
+        catch (err) {
+            console.error('Failed to handle relayed message:', err);
+        }
+    }
+    async openContentEnvelope(envelope) {
+        try {
+            const fields = readSealedEnvelopeFields(envelope);
+            if (!fields)
+                return this.rejectFrame();
+            const { type, sid, seq, epoch, box } = fields;
+            const streamKey = `${epoch}|${sid}`;
+            const lastSeq = this.inboundLastSeq.get(streamKey) ?? -1;
+            if (seq <= lastSeq)
+                return this.rejectReplay();
+            const derived = await this.receiverKey(sid, epoch);
+            if (!derived || derived.epoch !== epoch)
+                return this.rejectFrame();
+            const aad = buildAad({
+                v: envelope.v,
+                type,
+                msgId: typeof envelope.msgId === 'string' ? envelope.msgId : null,
+                sid,
+                dir: 'wc',
+                seq,
+                epoch,
+            });
+            const plainBytes = await open(derived.key, box, aad);
+            const parsed = JSON.parse(utf8Decode(plainBytes));
+            if (!isRecord(parsed))
+                return this.rejectFrame();
+            this.rememberInboundSeq(streamKey, seq);
+            if (this.cleartextEpoch === null &&
+                (this.keyEpoch === null || derived.epoch > this.keyEpoch)) {
+                this.keyEpoch = derived.epoch;
+            }
+            this.consecutiveOpenFailures = 0;
+            this.openFailureWarned = false;
+            this.rekeyHintSent = false;
+            this.replayWarned = false;
+            return unwrapEnvelopeV1({ ...envelope, enc: false, payload: parsed });
+        }
+        catch {
+            return this.rejectFrame();
+        }
+    }
+    receiverKey(sid, epoch) {
+        const cacheKey = `${epoch}|${sid}`;
+        const cached = this.receiverKeys.get(cacheKey);
+        if (cached) {
+            return cached.then((derived) => {
+                if (derived)
+                    return derived;
+                return this.deriveReceiverKey(cacheKey, sid, epoch);
+            });
+        }
+        return this.deriveReceiverKey(cacheKey, sid, epoch);
+    }
+    deriveReceiverKey(cacheKey, sid, epoch) {
+        if (!this.receiverKeys.has(cacheKey) && this.receiverKeys.size >= MAX_TRACKED_SENDERS) {
+            const oldest = this.receiverKeys.keys().next().value;
+            if (oldest !== undefined)
+                this.receiverKeys.delete(oldest);
+        }
+        const promise = deriveFromGroupKeyForEpoch(this.ctx.orchestraKey, epoch, CONTENT_KEY_SALT, contentKeyInfo(sid));
+        this.receiverKeys.set(cacheKey, promise);
+        return promise;
+    }
+    rememberInboundSeq(streamKey, seq) {
+        if (!this.inboundLastSeq.has(streamKey) && this.inboundLastSeq.size >= MAX_TRACKED_SENDERS) {
+            const oldest = this.inboundLastSeq.keys().next().value;
+            if (oldest !== undefined)
+                this.inboundLastSeq.delete(oldest);
+        }
+        this.inboundLastSeq.set(streamKey, seq);
+    }
+    rejectReplay() {
+        if (!this.replayWarned) {
+            this.replayWarned = true;
+            warn('Rejected a replayed/reordered sealed frame — further rejections muted until a good frame arrives');
+        }
+        return null;
+    }
+    rejectFrame() {
+        this.noteOpenFailure();
+        return null;
+    }
+    noteOpenFailure() {
+        this.consecutiveOpenFailures++;
+        if (!this.openFailureWarned) {
+            this.openFailureWarned = true;
+            warn('Dropping sealed relay frame(s) that failed to open — further drops muted until a good frame arrives');
+        }
+        if (this.consecutiveOpenFailures >= REKEY_HINT_AFTER_CONSECUTIVE_FAILURES &&
+            !this.rekeyHintSent) {
+            this.rekeyHintSent = true;
+            this.ctx.sendControlEnvelope({
+                v: ENVELOPE_VERSION,
+                type: 'e2ee_state',
+                enc: false,
+                payload: {
+                    orchestra: this.ctx.orchestraKey,
+                    state: 'decrypt-failed',
+                    epoch: this.keyEpoch,
+                },
+            });
+        }
+    }
+    isSealingActive() {
+        return shouldSealContent('terminalOutput', this.currentDecision());
+    }
+    whenIdle() {
+        return Promise.all([this.outboundChain, this.inboundChain, this.keyProbe]).then(() => undefined);
+    }
+    getDiagnostics() {
+        let capable = 0;
+        for (const isCapable of this.viewers.values()) {
+            if (isCapable)
+                capable++;
+        }
+        return {
+            keyAvailable: this.keyEpoch !== null,
+            epoch: this.keyEpoch,
+            cleartextEpoch: this.cleartextEpoch,
+            viewers: this.viewers.size,
+            capableViewers: capable,
+            sealingActive: this.isSealingActive(),
+            consecutiveOpenFailures: this.consecutiveOpenFailures,
+        };
+    }
+}

package/dist/server/services/platform-envelope.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export const ENVELOPE_VERSION = 1;
+export const E2EE_CONTENT_VERSION = 'v1';
+export const E2EE_CAPABILITIES = {
+    e2ee: { envelope: ENVELOPE_VERSION, e2ee: E2EE_CONTENT_VERSION },
+};
+export const RELAY_TERMINATED_TYPES = new Set([
+    'auth',
+    'ping',
+    'pong',
+    'reportUsage',
+    'sdkGrantState',
+    'clientAuthExpired',
+]);
+export function isNeverSealedType(type) {
+    return type.startsWith('fileShare');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isV1Envelope(message) {
+    return isRecord(message) && typeof message.v === 'number' && message.v >= 1;
+}
+export function encodeForRelay(message) {
+    if (!isRecord(message))
+        return message;
+    const type = message.type;
+    if (typeof type !== 'string' || RELAY_TERMINATED_TYPES.has(type))
+        return message;
+    return wrapEnvelopeV1(message, type);
+}
+export function wrapEnvelopeV1(message, type) {
+    const data = isRecord(message.data) ? message.data : undefined;
+    const msgId = typeof data?.msgId === 'string' ? data.msgId : undefined;
+    const tabId = typeof message.tabId === 'string' ? message.tabId : undefined;
+    const to = typeof message._target === 'string' ? message._target : undefined;
+    const envelope = { v: ENVELOPE_VERSION, type };
+    if (msgId !== undefined)
+        envelope.msgId = msgId;
+    if (tabId !== undefined)
+        envelope.tabId = tabId;
+    envelope.enc = false;
+    if (to !== undefined)
+        envelope.to = to;
+    envelope.payload = buildPayload(message, data, msgId, tabId, to);
+    return envelope;
+}
+function buildPayload(message, data, promotedMsgId, tabId, to) {
+    const payload = {};
+    for (const [key, value] of Object.entries(message)) {
+        if (key === 'type')
+            continue;
+        if (key === 'tabId' && tabId !== undefined)
+            continue;
+        if (key === '_target' && to !== undefined)
+            continue;
+        payload[key] = value;
+    }
+    if (data && promotedMsgId !== undefined) {
+        const { msgId: _promoted, ...rest } = data;
+        payload.data = rest;
+    }
+    return payload;
+}
+export function unwrapEnvelopeV1(envelope) {
+    if (envelope.enc !== false) {
+        throw new Error('unwrapEnvelopeV1: refusing to unwrap a sealed payload (enc !== false)');
+    }
+    const legacy = { type: envelope.type };
+    const tabId = typeof envelope.tabId === 'string' ? envelope.tabId : undefined;
+    if (tabId !== undefined)
+        legacy.tabId = tabId;
+    spreadPayload(legacy, envelope.payload, tabId);
+    if (typeof envelope.msgId === 'string') {
+        const data = isRecord(legacy.data) ? legacy.data : {};
+        legacy.data = { ...data, msgId: envelope.msgId };
+    }
+    if ('_role' in envelope)
+        legacy._role = envelope._role;
+    if ('_viewer' in envelope)
+        legacy._viewer = envelope._viewer;
+    if ('_share' in envelope)
+        legacy._share = envelope._share;
+    return legacy;
+}
+function spreadPayload(legacy, payload, tabId) {
+    if (!isRecord(payload))
+        return;
+    for (const [key, value] of Object.entries(payload)) {
+        if (key === 'type' || (key === 'tabId' && tabId !== undefined))
+            continue;
+        if (key === '_role' || key === '_viewer' || key === '_share')
+            continue;
+        legacy[key] = value;
+    }
+}
+export function readPairedEnvelopeAck(message) {
+    const e2ee = isRecord(message.e2ee) ? message.e2ee : undefined;
+    const acked = e2ee?.envelope;
+    return typeof acked === 'number' && acked >= ENVELOPE_VERSION;
+}

package/dist/server/services/platform-heartbeat.js

@@ -0,0 +1,88 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+const DEFAULT_RESUME_PROBE_MS = 5_000;
+export class HeartbeatMonitor {
+    opts;
+    timer = null;
+    resumeTimer = null;
+    interval = 0;
+    lastTickAt = 0;
+    lastFrameAt = 0;
+    lastPingAt = 0;
+    missed = 0;
+    resumeProbeMs;
+    now;
+    random;
+    constructor(opts) {
+        this.opts = opts;
+        this.resumeProbeMs = opts.resumeProbeMs ?? DEFAULT_RESUME_PROBE_MS;
+        this.now = opts.now ?? (() => Date.now());
+        this.random = opts.random ?? Math.random;
+    }
+    start() {
+        this.stop();
+        this.missed = 0;
+        this.lastPingAt = 0;
+        this.interval = Math.round(this.opts.intervalMs * (0.9 + 0.2 * this.random()));
+        this.lastTickAt = this.now();
+        this.timer = setInterval(() => this.tick(), this.interval);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.clearResumeTimer();
+    }
+    isRunning() {
+        return this.timer !== null;
+    }
+    noteInbound() {
+        this.lastFrameAt = this.now();
+    }
+    missedPings() {
+        return this.missed;
+    }
+    tick() {
+        const now = this.now();
+        const resumed = now - this.lastTickAt > this.interval * 2;
+        this.lastTickAt = now;
+        if (resumed) {
+            this.probeAfterResume(now);
+            return;
+        }
+        if (this.lastPingAt > 0 && this.lastFrameAt < this.lastPingAt) {
+            this.missed++;
+        }
+        else {
+            this.missed = 0;
+        }
+        if (this.missed >= this.opts.maxMissed) {
+            const missed = this.missed;
+            this.stop();
+            this.opts.onDead(missed);
+            return;
+        }
+        this.lastPingAt = now;
+        this.opts.sendPing();
+    }
+    probeAfterResume(pingAt) {
+        this.missed = 0;
+        this.lastPingAt = pingAt;
+        this.opts.sendPing();
+        this.clearResumeTimer();
+        this.resumeTimer = setTimeout(() => {
+            this.resumeTimer = null;
+            if (this.lastFrameAt >= pingAt)
+                return;
+            this.stop();
+            this.opts.onDead(1);
+        }, this.resumeProbeMs);
+    }
+    clearResumeTimer() {
+        if (this.resumeTimer) {
+            clearTimeout(this.resumeTimer);
+            this.resumeTimer = null;
+        }
+    }
+}

package/dist/server/services/platform-reconnect.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export const RELAY_CLOSE = {
+    AUTH_FAILED: 4001,
+    AUTH_EXPIRED: 4008,
+    ORCHESTRA_ELSEWHERE: 4013,
+    SUPERSEDED: 4015,
+    SERVER_ERROR: 4500,
+};
+export function classifyClose(code, reason, opts) {
+    if (opts.protocolUpgradeRequired)
+        return 'protocol_too_old';
+    if ((code === 1002 || code === 1008) && reason?.includes('protocol-too-old'))
+        return 'protocol_too_old';
+    if (code === RELAY_CLOSE.SUPERSEDED)
+        return 'superseded';
+    if (code === RELAY_CLOSE.AUTH_FAILED || reason?.includes('Unauthorized'))
+        return 'auth_failed';
+    return 'reconnect';
+}
+export class ReconnectPolicy {
+    attempts = 0;
+    pairedAt = null;
+    initialMs;
+    maxMs;
+    jitterRatio;
+    stableAfterMs;
+    random;
+    now;
+    constructor(opts = {}) {
+        this.initialMs = opts.initialMs ?? 1_000;
+        this.maxMs = opts.maxMs ?? 30_000;
+        this.jitterRatio = opts.jitterRatio ?? 0.25;
+        this.stableAfterMs = opts.stableAfterMs ?? 10_000;
+        this.random = opts.random ?? Math.random;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    get attempt() {
+        return this.attempts;
+    }
+    nextDelayMs() {
+        this.attempts++;
+        const base = Math.min(this.initialMs * 2 ** (this.attempts - 1), this.maxMs);
+        const jitter = base * this.jitterRatio * (2 * this.random() - 1);
+        return Math.max(0, Math.round(base + jitter));
+    }
+    reset() {
+        this.attempts = 0;
+    }
+    notePaired() {
+        this.pairedAt = this.now();
+    }
+    noteDisconnected() {
+        const pairedAt = this.pairedAt;
+        this.pairedAt = null;
+        if (pairedAt !== null && this.now() - pairedAt >= this.stableAfterMs) {
+            this.reset();
+        }
+    }
+}