chapterjs 0.1.2 → 0.2.0

package/dist/voice/dave.js

@@ -0,0 +1,245 @@
+// End-to-end encryption of voice (DAVE), on Discord's own libdave compiled
+// to WebAssembly (vendor/dave, built by scripts/build-dave.sh). libdave
+// keeps the MLS group and encrypts frames; this file follows the voice
+// gateway through the protocol: key packages, proposals, commits, welcomes
+// and transitions.
+// https://docs.discord.com/developers/topics/voice-connections#end-to-end-encryption-dave-protocol
+// https://daveprotocol.com/#voice-gateway-opcodes
+import { VoiceOpcode } from '../discord/codes.js';
+let loading = null;
+/** libdave, loaded the first time a voice connection needs it. */
+export function loadDave() {
+    loading ??= (async () => {
+        const url = new URL('../../vendor/dave/libdave.mjs', import.meta.url);
+        const { default: factory } = (await import(url.href));
+        // libdave logs every step, MLS messages included: not for the
+        // terminal of the developer. What fails reaches the session callback.
+        return factory({ print: () => { }, printErr: () => { } });
+    })();
+    return loading;
+}
+/**
+ * The DAVE state of one voice connection: the MLS group of the call and
+ * the encryptor of what the bot sends.
+ */
+export class DaveSession {
+    #dave;
+    #transport;
+    #userId;
+    #channelId;
+    #warn;
+    #keys;
+    #session;
+    #encryptor;
+    /** Who the voice gateway says is in the call: the members it may add. */
+    #connected = new Set();
+    /** The protocol version each announced transition moves to. */
+    #transitions = new Map();
+    #version = 0;
+    /** Whether frames can be sent: no E2EE, or the bot has its key. */
+    #ready = true;
+    #waiting = [];
+    #ssrc = null;
+    constructor(dave, options) {
+        this.#dave = dave;
+        this.#transport = options.transport;
+        this.#userId = options.userId;
+        this.#channelId = options.channelId;
+        this.#warn = options.warn;
+        this.#keys = new dave.TransientKeys();
+        // libdave also reports what is normal in a call (a commit that arrives
+        // while the group starts over): only a recovery is worth saying.
+        this.#session = new dave.Session('', '', () => { });
+        this.#encryptor = new dave.Encryptor();
+        this.#encryptor.SetPassthroughMode(true);
+        this.#connected.add(this.#userId);
+    }
+    /** The highest DAVE version the bot speaks, for Identify. */
+    get maxVersion() {
+        return this.#dave.MaxSupportedProtocolVersion();
+    }
+    /** The protocol version of the call; 0 without E2EE. */
+    get version() {
+        return this.#version;
+    }
+    /** Whether frames can be sent now. */
+    get canSend() {
+        return this.#ready;
+    }
+    /** Resolves once frames can be sent. */
+    ready() {
+        if (this.#ready)
+            return Promise.resolve();
+        return new Promise(resolve => this.#waiting.push(resolve));
+    }
+    /** The SSRC of the bot, which the encryptor files its frames under. */
+    setSsrc(ssrc) {
+        this.#ssrc = ssrc;
+        this.#encryptor.AssignSsrcToCodec(ssrc, this.#dave.Codec.Opus);
+    }
+    /** Session Description (4): the version the call starts with. */
+    start(version) {
+        this.#version = version;
+        if (version > 0) {
+            this.#setReady(false);
+            this.#reinit(version);
+        }
+    }
+    /** Clients Connect (11) and Client Disconnect (13). */
+    clientsConnect(userIds) {
+        for (const id of userIds)
+            this.#connected.add(id);
+    }
+    clientDisconnect(userId) {
+        this.#connected.delete(userId);
+    }
+    /** DAVE Prepare Transition (21): a move to another version, 0 included. */
+    prepareTransition(transitionId, version) {
+        this.#transitions.set(transitionId, version);
+        if (transitionId === 0)
+            this.executeTransition(0);
+        else {
+            this.#transport.json(VoiceOpcode.DaveTransitionReady, {
+                transition_id: transitionId,
+            });
+        }
+    }
+    /** DAVE Execute Transition (22): senders switch now. */
+    executeTransition(transitionId) {
+        const version = this.#transitions.get(transitionId);
+        if (version === undefined)
+            return;
+        this.#transitions.delete(transitionId);
+        const previous = this.#version;
+        this.#version = version;
+        if (version === 0) {
+            this.#encryptor.SetPassthroughMode(true);
+            this.#setReady(true);
+            return;
+        }
+        if (previous === 0 && transitionId !== 0) {
+            // An upgrade: the group of the new version was made before this.
+            this.#session.SetProtocolVersion(version);
+        }
+        this.#useOwnKey();
+    }
+    /** DAVE Prepare Epoch (24): a new group when `epoch` is 1. */
+    prepareEpoch(epoch, version) {
+        if (epoch === 1) {
+            this.#version = version;
+            this.#setReady(false);
+            this.#reinit(version);
+        }
+    }
+    /** DAVE MLS External Sender (25). */
+    externalSender(payload) {
+        this.#session.SetExternalSender(payload);
+    }
+    /** DAVE MLS Proposals (27): answered with a commit when there is one. */
+    proposals(payload) {
+        const commit = this.#session.ProcessProposals(payload, [
+            ...this.#connected,
+        ]);
+        if (commit) {
+            this.#transport.binary(VoiceOpcode.DaveMlsCommitWelcome, Uint8Array.from(commit));
+        }
+    }
+    /** DAVE MLS Announce Commit Transition (29). */
+    announceCommit(transitionId, commit) {
+        let result;
+        try {
+            result = this.#session.ProcessCommit(commit);
+        }
+        catch {
+            result = { failed: true, ignored: false };
+        }
+        if (result.ignored)
+            return;
+        if (result.failed)
+            return this.#recover(transitionId);
+        this.#prepared(transitionId);
+    }
+    /** DAVE MLS Welcome (30): the bot joins the group. */
+    welcome(transitionId, welcome) {
+        let roster;
+        try {
+            roster = this.#session.ProcessWelcome(welcome, [...this.#connected]);
+        }
+        catch {
+            roster = null;
+        }
+        if (!roster)
+            return this.#recover(transitionId);
+        this.#prepared(transitionId);
+    }
+    /**
+     * One Opus frame as it travels: end-to-end encrypted when the call is,
+     * unchanged otherwise.
+     */
+    encrypt(frame) {
+        if (this.#version === 0 || this.#ssrc === null)
+            return frame;
+        const dave = this.#dave;
+        const capacity = this.#encryptor.GetMaxCiphertextByteSize(dave.MediaType.Audio, frame.length);
+        const pointer = dave._malloc(capacity);
+        try {
+            dave.HEAPU8.set(frame, pointer);
+            const written = this.#encryptor.Encrypt(dave.MediaType.Audio, this.#ssrc, pointer, frame.length, capacity);
+            if (written === 0) {
+                throw new Error('libdave could not encrypt a voice frame.');
+            }
+            return dave.HEAPU8.slice(pointer, pointer + written);
+        }
+        finally {
+            dave._free(pointer);
+        }
+    }
+    /** Frees what libdave holds for this connection. */
+    close() {
+        this.#setReady(true);
+        this.#encryptor.delete();
+        this.#session.delete();
+        this.#keys.delete();
+    }
+    /** A new local group for `version`, and a key package to join it. */
+    #reinit(version) {
+        this.#session.Init(version, BigInt(this.#channelId), this.#userId, this.#keys.GetTransientPrivateKey(version));
+        this.#transport.binary(VoiceOpcode.DaveMlsKeyPackage, Uint8Array.from(this.#session.GetMarshalledKeyPackage()));
+    }
+    /** The bot processed a commit or a welcome: ready for the transition. */
+    #prepared(transitionId) {
+        this.#transitions.set(transitionId, this.#session.GetProtocolVersion());
+        if (transitionId === 0)
+            this.executeTransition(0);
+        else {
+            this.#transport.json(VoiceOpcode.DaveTransitionReady, {
+                transition_id: transitionId,
+            });
+        }
+    }
+    /** A commit or welcome that could not be processed: start over. */
+    #recover(transitionId) {
+        this.#warn(`the end-to-end encryption of the call could not be updated (transition ${transitionId}): joining it again.`);
+        this.#transport.json(VoiceOpcode.DaveMlsInvalidCommitWelcome, {
+            transition_id: transitionId,
+        });
+        this.#reinit(this.#version || this.#session.GetProtocolVersion());
+    }
+    #useOwnKey() {
+        const ratchet = this.#session.GetKeyRatchet(this.#userId);
+        if (!ratchet)
+            return;
+        this.#encryptor.SetKeyRatchet(ratchet);
+        this.#encryptor.SetPassthroughMode(false);
+        this.#setReady(true);
+    }
+    #setReady(ready) {
+        this.#ready = ready;
+        if (!ready)
+            return;
+        const waiting = this.#waiting;
+        this.#waiting = [];
+        for (const resolve of waiting)
+            resolve();
+    }
+}

package/dist/voice/opus.d.ts

@@ -0,0 +1,19 @@
+/** A file that holds no Opus audio this module can read. */
+export declare class NotOpusError extends Error {
+}
+/**
+ * How many samples (at 48 kHz) an Opus packet plays, from its TOC byte.
+ * https://www.rfc-editor.org/rfc/rfc6716#section-3.1
+ */
+export declare function opusSamples(packet: Uint8Array): number;
+/**
+ * The Opus packets of an Ogg stream, in order, without its two header
+ * packets (OpusHead, OpusTags). Only the first logical stream is read.
+ * https://www.rfc-editor.org/rfc/rfc3533 https://www.rfc-editor.org/rfc/rfc7845
+ */
+export declare function oggOpusPackets(source: AsyncIterable<Uint8Array>): AsyncGenerator<Buffer>;
+/**
+ * The Opus packets of a WebM/Matroska stream, from its first Opus track.
+ * https://www.matroska.org/technical/elements.html
+ */
+export declare function webmOpusPackets(source: AsyncIterable<Uint8Array>): AsyncGenerator<Buffer>;

package/dist/voice/opus.js

@@ -0,0 +1,273 @@
+// Opus packets out of the files that already hold them: Ogg (`.ogg`,
+// `.opus`) and WebM/Matroska (`.webm`, `.mka`). Discord takes Opus as is,
+// so nothing is decoded: packets are only taken out of their container.
+/** A file that holds no Opus audio this module can read. */
+export class NotOpusError extends Error {
+}
+/**
+ * How many samples (at 48 kHz) an Opus packet plays, from its TOC byte.
+ * https://www.rfc-editor.org/rfc/rfc6716#section-3.1
+ */
+export function opusSamples(packet) {
+    const toc = packet[0];
+    if (toc === undefined)
+        return 0;
+    const config = toc >> 3;
+    // Frame size in 1/400 s (2.5 ms), per configuration group.
+    const tenths = config < 12
+        ? [4, 8, 16, 24][config % 4]
+        : config < 16
+            ? [4, 8][config % 2]
+            : [1, 2, 4, 8][config % 4];
+    const code = toc & 3;
+    const frames = code === 0 ? 1 : code === 3 ? (packet[1] ?? 0) & 0x3f : 2;
+    return tenths * 120 * frames;
+}
+/** Bytes coming in pieces, read as they are needed. */
+class Reader {
+    #chunks = [];
+    #length = 0;
+    #source;
+    #done = false;
+    constructor(source) {
+        this.#source = source[Symbol.asyncIterator]();
+    }
+    /** Makes at least `size` bytes available; `false` at the end. */
+    async need(size) {
+        while (this.#length < size && !this.#done) {
+            const next = await this.#source.next();
+            if (next.done)
+                this.#done = true;
+            else if (next.value.length > 0) {
+                this.#chunks.push(next.value);
+                this.#length += next.value.length;
+            }
+        }
+        return this.#length >= size;
+    }
+    /** The first `size` bytes, without consuming them. */
+    peek(size) {
+        if (this.#chunks.length !== 1) {
+            const all = Buffer.concat(this.#chunks);
+            this.#chunks = [all];
+        }
+        return Buffer.from(this.#chunks[0].subarray(0, size));
+    }
+    async take(size) {
+        if (!(await this.need(size)))
+            return null;
+        const out = this.peek(size);
+        const first = this.#chunks[0].subarray(size);
+        this.#chunks = first.length > 0 ? [first] : [];
+        this.#length -= size;
+        return out;
+    }
+    async skip(size) {
+        let left = size;
+        while (left > 0) {
+            if (!(await this.need(Math.min(left, 65536))))
+                return false;
+            const step = Math.min(left, this.#length);
+            await this.take(step);
+            left -= step;
+        }
+        return true;
+    }
+    get ended() {
+        return this.#done && this.#length === 0;
+    }
+}
+/**
+ * The Opus packets of an Ogg stream, in order, without its two header
+ * packets (OpusHead, OpusTags). Only the first logical stream is read.
+ * https://www.rfc-editor.org/rfc/rfc3533 https://www.rfc-editor.org/rfc/rfc7845
+ */
+export async function* oggOpusPackets(source) {
+    const reader = new Reader(source);
+    let serial = null;
+    let index = 0;
+    let pending = [];
+    for (;;) {
+        const head = await reader.take(27);
+        if (!head)
+            return;
+        if (head.toString('latin1', 0, 4) !== 'OggS') {
+            throw new NotOpusError('This is not an Ogg file.');
+        }
+        const segments = head[26];
+        const lacing = await reader.take(segments);
+        if (!lacing)
+            return;
+        const size = lacing.reduce((sum, value) => sum + value, 0);
+        const body = await reader.take(size);
+        if (!body)
+            return;
+        const pageSerial = head.readUInt32LE(14);
+        if (serial === null)
+            serial = pageSerial;
+        if (pageSerial !== serial)
+            continue;
+        let offset = 0;
+        for (const value of lacing) {
+            pending.push(body.subarray(offset, offset + value));
+            offset += value;
+            if (value === 255)
+                continue;
+            const packet = Buffer.concat(pending);
+            pending = [];
+            if (index === 0 && packet.toString('latin1', 0, 8) !== 'OpusHead') {
+                throw new NotOpusError('This Ogg file holds no Opus audio.');
+            }
+            if (index >= 2 && packet.length > 0)
+                yield packet;
+            index++;
+        }
+    }
+}
+const EBML = 0x1a45dfa3;
+const SEGMENT = 0x18538067;
+const TRACKS = 0x1654ae6b;
+const TRACK_ENTRY = 0xae;
+const TRACK_NUMBER = 0xd7;
+const CODEC_ID = 0x86;
+const CLUSTER = 0x1f43b675;
+const BLOCK_GROUP = 0xa0;
+const BLOCK = 0xa1;
+const SIMPLE_BLOCK = 0xa3;
+/** Elements whose children are read; everything else is skipped. */
+const MASTERS = new Set([SEGMENT, TRACKS, TRACK_ENTRY, CLUSTER, BLOCK_GROUP]);
+/** The length of an EBML variable-size integer, from its first byte. */
+const vintLength = (first) => {
+    for (let length = 1; length <= 8; length++) {
+        if (first & (0x80 >> (length - 1)))
+            return length;
+    }
+    return 0;
+};
+/** A variable-size integer, without its marker; `-1` for "unknown". */
+function readVint(bytes, offset = 0) {
+    const length = vintLength(bytes[offset]);
+    if (length === 0)
+        throw new NotOpusError('This WebM file is damaged.');
+    let value = bytes[offset] & (0xff >> length);
+    let unknown = value === 0xff >> length;
+    for (let i = 1; i < length; i++) {
+        const byte = bytes[offset + i];
+        if (byte !== 0xff)
+            unknown = false;
+        value = value * 256 + byte;
+    }
+    return { value: unknown ? -1 : value, length };
+}
+/**
+ * The Opus packets of a WebM/Matroska stream, from its first Opus track.
+ * https://www.matroska.org/technical/elements.html
+ */
+export async function* webmOpusPackets(source) {
+    const reader = new Reader(source);
+    let track = null;
+    let entry = null;
+    let first = true;
+    while (await reader.need(1)) {
+        // An element: its id (marker kept), then its size.
+        const idLength = vintLength(reader.peek(1)[0]);
+        if (idLength === 0 || idLength > 4 || !(await reader.need(idLength + 1))) {
+            throw new NotOpusError('This WebM file is damaged.');
+        }
+        const id = reader.peek(idLength).readUIntBE(0, idLength);
+        const sizeLength = vintLength(reader.peek(idLength + 1)[idLength]);
+        if (!(await reader.need(idLength + sizeLength)))
+            return;
+        const { value: size } = readVint(reader.peek(idLength + sizeLength), idLength);
+        await reader.take(idLength + sizeLength);
+        if (first) {
+            if (id !== EBML)
+                throw new NotOpusError('This is not a WebM file.');
+            first = false;
+        }
+        if (MASTERS.has(id)) {
+            if (id === TRACK_ENTRY)
+                entry = { number: null, codec: null };
+            continue;
+        }
+        if (size < 0)
+            throw new NotOpusError('This WebM file is damaged.');
+        if (id === TRACK_NUMBER || id === CODEC_ID) {
+            const data = await reader.take(size);
+            if (!data || !entry)
+                continue;
+            if (id === TRACK_NUMBER)
+                entry.number = data.readUIntBE(0, size);
+            else
+                entry.codec = data.toString('latin1').replace(/\0+$/, '');
+            if (track === null && entry.codec === 'A_OPUS' && entry.number !== null) {
+                track = entry.number;
+            }
+            continue;
+        }
+        if (id === SIMPLE_BLOCK || id === BLOCK) {
+            const data = await reader.take(size);
+            if (!data)
+                return;
+            if (track === null) {
+                throw new NotOpusError('This WebM file holds no Opus audio.');
+            }
+            const number = readVint(data);
+            if (number.value !== track)
+                continue;
+            yield* laced(data, number.length + 3);
+            continue;
+        }
+        if (!(await reader.skip(size)))
+            return;
+    }
+    if (track === null) {
+        throw new NotOpusError('This WebM file holds no Opus audio.');
+    }
+}
+/** The frames of a block, after its header, whatever its lacing. */
+function* laced(block, start) {
+    const lacing = (block[start - 1] >> 1) & 3;
+    if (lacing === 0) {
+        yield block.subarray(start);
+        return;
+    }
+    const count = block[start] + 1;
+    let offset = start + 1;
+    const sizes = [];
+    if (lacing === 1) {
+        // Xiph: each size is a run of 255s and a last byte.
+        for (let i = 0; i < count - 1; i++) {
+            let size = 0;
+            let byte;
+            do {
+                byte = block[offset++];
+                size += byte;
+            } while (byte === 255);
+            sizes.push(size);
+        }
+    }
+    else if (lacing === 3) {
+        // EBML: the first size, then signed differences.
+        const firstSize = readVint(block, offset);
+        offset += firstSize.length;
+        sizes.push(firstSize.value);
+        for (let i = 1; i < count - 1; i++) {
+            const delta = readVint(block, offset);
+            offset += delta.length;
+            const bias = 2 ** (7 * delta.length - 1) - 1;
+            sizes.push(sizes[i - 1] + delta.value - bias);
+        }
+    }
+    else {
+        // Fixed: every frame has the same size.
+        const each = (block.length - offset) / count;
+        for (let i = 0; i < count - 1; i++)
+            sizes.push(each);
+    }
+    for (const size of sizes) {
+        yield block.subarray(offset, offset + size);
+        offset += size;
+    }
+    yield block.subarray(offset);
+}

package/dist/voice/session.d.ts

@@ -0,0 +1,55 @@
+import type { Snowflake } from '../discord/types/common.js';
+import { DaveSession, type loadDave } from './dave.js';
+export declare const VOICE_GATEWAY_VERSION = 8;
+/** What a voice server needs to know who the bot is. */
+export interface VoiceServer {
+    endpoint: string;
+    token: string;
+    guildId: Snowflake;
+    channelId: Snowflake;
+    userId: Snowflake;
+    sessionId: string;
+}
+/** How a session ended, when it did not end on purpose. */
+export type SessionEnd = 
+/** Discord ended it (the bot was disconnected, the call ended...). */
+{
+    type: 'ended';
+    code: number;
+}
+/** The session can't be resumed: ask the gateway for a new one. */
+ | {
+    type: 'lost';
+    code: number;
+}
+/** Discord refused the session: something to fix. */
+ | {
+    type: 'refused';
+    code: number;
+    reason: string;
+};
+export interface SessionOptions {
+    dave: Awaited<ReturnType<typeof loadDave>>;
+    /** The session can no longer send; the connection decides what next. */
+    onEnd: (end: SessionEnd) => void;
+    warn: (message: string) => void;
+    /** Only tests change these. */
+    secure?: boolean;
+    timeout?: number;
+}
+export declare class VoiceSession {
+    #private;
+    readonly server: VoiceServer;
+    readonly dave: DaveSession;
+    constructor(server: VoiceServer, options: SessionOptions);
+    /** Resolves once the session can send audio. */
+    connect(): Promise<void>;
+    /** Sends one Opus packet that plays `samples` samples. */
+    sendOpus(packet: Uint8Array, samples: number): void;
+    /** The five frames of silence Discord asks for before a pause. */
+    sendSilence(): void;
+    /** Speaking (5): needed before audio, and shown in Discord. */
+    setSpeaking(speaking: boolean): void;
+    /** Closes the session for good. */
+    close(): void;
+}