@textrp/briij-js-sdk 41.0.0

package/src/rendezvous/channels/MSC4108SecureChannel.ts

@@ -0,0 +1,270 @@
+/*
+Copyright 2024 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import {
+    type Curve25519PublicKey,
+    Ecies,
+    type EstablishedEcies,
+    QrCodeData,
+    QrCodeMode,
+} from "@matrix-org/matrix-sdk-crypto-wasm";
+
+import {
+    ClientRendezvousFailureReason,
+    MSC4108FailureReason,
+    type MSC4108Payload,
+    RendezvousError,
+    type RendezvousFailureListener,
+} from "../index.ts";
+import { type MSC4108RendezvousSession } from "../transports/MSC4108RendezvousSession.ts";
+import { logger } from "../../logger.ts";
+
+/**
+ * Prototype of the unstable [MSC4108](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
+ * secure rendezvous session protocol.
+ * @experimental Note that this is UNSTABLE and may have breaking changes without notice.
+ * Imports @matrix-org/matrix-sdk-crypto-wasm so should be async-imported to avoid bundling the WASM into the main bundle.
+ */
+export class MSC4108SecureChannel {
+    private readonly secureChannel: Ecies;
+    private establishedChannel?: EstablishedEcies;
+    private connected = false;
+
+    public constructor(
+        private rendezvousSession: MSC4108RendezvousSession,
+        private theirPublicKey?: Curve25519PublicKey,
+        public onFailure?: RendezvousFailureListener,
+    ) {
+        this.secureChannel = new Ecies();
+    }
+
+    /**
+     * Generate a QR code for the current session.
+     * @param mode the mode to generate the QR code in, either `Login` or `Reciprocate`.
+     * @param serverName the name of the homeserver to connect to, as defined by server discovery in the spec, required for `Reciprocate` mode.
+     */
+    public async generateCode(mode: QrCodeMode.Login): Promise<Uint8Array>;
+    public async generateCode(mode: QrCodeMode.Reciprocate, serverName: string): Promise<Uint8Array>;
+    public async generateCode(mode: QrCodeMode, serverName?: string): Promise<Uint8Array> {
+        const { url } = this.rendezvousSession;
+
+        if (!url) {
+            throw new Error("No rendezvous session URL");
+        }
+
+        return new QrCodeData(
+            this.secureChannel.public_key(),
+            url,
+            mode === QrCodeMode.Reciprocate ? serverName : undefined,
+        ).toBytes();
+    }
+
+    /**
+     * Returns the check code for the secure channel or undefined if not generated yet.
+     */
+    public getCheckCode(): string | undefined {
+        const x = this.establishedChannel?.check_code();
+
+        if (!x) {
+            return undefined;
+        }
+        return Array.from(x.as_bytes())
+            .map((b) => `${b % 10}`)
+            .join("");
+    }
+
+    /**
+     * Connects and establishes a secure channel with the other device.
+     */
+    public async connect(): Promise<void> {
+        if (this.connected) {
+            throw new Error("Channel already connected");
+        }
+
+        if (this.theirPublicKey) {
+            // We are the scanning device
+            const result = this.secureChannel.establish_outbound_channel(
+                this.theirPublicKey,
+                "MATRIX_QR_CODE_LOGIN_INITIATE",
+            );
+            this.establishedChannel = result.channel;
+
+            /*
+             Secure Channel step 4. Device S sends the initial message
+
+             Nonce := 0
+             SH := ECDH(Ss, Gp)
+             EncKey := HKDF_SHA256(SH, "MATRIX_QR_CODE_LOGIN|" || Gp || "|" || Sp, 0, 32)
+             TaggedCiphertext := ChaCha20Poly1305_Encrypt(EncKey, Nonce, "MATRIX_QR_CODE_LOGIN_INITIATE")
+             Nonce := Nonce + 2
+             LoginInitiateMessage := UnpaddedBase64(TaggedCiphertext) || "|" || UnpaddedBase64(Sp)
+             */
+            {
+                logger.info("Sending LoginInitiateMessage");
+                await this.rendezvousSession.send(result.initial_message);
+            }
+
+            /*
+            Secure Channel step 6. Verification by Device S
+
+            Nonce_G := 1
+            (TaggedCiphertext, Sp) := Unpack(Message)
+            Plaintext := ChaCha20Poly1305_Decrypt(EncKey, Nonce_G, TaggedCiphertext)
+            Nonce_G := Nonce_G + 2
+
+            unless Plaintext == "MATRIX_QR_CODE_LOGIN_OK":
+                FAIL
+             */
+            {
+                logger.info("Waiting for LoginOkMessage");
+                const ciphertext = await this.rendezvousSession.receive();
+
+                if (!ciphertext) {
+                    throw new RendezvousError(
+                        "No response from other device",
+                        MSC4108FailureReason.UnexpectedMessageReceived,
+                    );
+                }
+                const candidateLoginOkMessage = await this.decrypt(ciphertext);
+
+                if (candidateLoginOkMessage !== "MATRIX_QR_CODE_LOGIN_OK") {
+                    throw new RendezvousError(
+                        "Invalid response from other device",
+                        ClientRendezvousFailureReason.InsecureChannelDetected,
+                    );
+                }
+
+                // Step 6 is now complete. We trust the channel
+            }
+        } else {
+            /*
+            Secure Channel step 5. Device G confirms
+
+            Nonce_S := 0
+            (TaggedCiphertext, Sp) := Unpack(LoginInitiateMessage)
+            SH := ECDH(Gs, Sp)
+            EncKey := HKDF_SHA256(SH, "MATRIX_QR_CODE_LOGIN|" || Gp || "|" || Sp, 0, 32)
+            Plaintext := ChaCha20Poly1305_Decrypt(EncKey, Nonce_S, TaggedCiphertext)
+            Nonce_S := Nonce_S + 2
+             */
+            // wait for the other side to send us their public key
+            logger.info("Waiting for LoginInitiateMessage");
+            const loginInitiateMessage = await this.rendezvousSession.receive();
+            if (!loginInitiateMessage) {
+                throw new Error("No response from other device");
+            }
+
+            const { channel, message: candidateLoginInitiateMessage } =
+                this.secureChannel.establish_inbound_channel(loginInitiateMessage);
+            this.establishedChannel = channel;
+
+            if (candidateLoginInitiateMessage !== "MATRIX_QR_CODE_LOGIN_INITIATE") {
+                throw new RendezvousError(
+                    "Invalid response from other device",
+                    ClientRendezvousFailureReason.InsecureChannelDetected,
+                );
+            }
+            logger.info("LoginInitiateMessage received");
+
+            logger.info("Sending LoginOkMessage");
+            const loginOkMessage = await this.encrypt("MATRIX_QR_CODE_LOGIN_OK");
+            await this.rendezvousSession.send(loginOkMessage);
+
+            // Step 5 is complete. We don't yet trust the channel
+
+            // next step will be for the user to confirm the check code on the other device
+        }
+
+        this.connected = true;
+    }
+
+    private async decrypt(ciphertext: string): Promise<string> {
+        if (!this.establishedChannel) {
+            throw new Error("Channel closed");
+        }
+
+        return this.establishedChannel.decrypt(ciphertext);
+    }
+
+    private async encrypt(plaintext: string): Promise<string> {
+        if (!this.establishedChannel) {
+            throw new Error("Channel closed");
+        }
+
+        return this.establishedChannel.encrypt(plaintext);
+    }
+
+    /**
+     * Sends a payload securely to the other device.
+     * @param payload the payload to encrypt and send
+     */
+    public async secureSend<T extends MSC4108Payload>(payload: T): Promise<void> {
+        if (!this.connected) {
+            throw new Error("Channel closed");
+        }
+
+        const stringifiedPayload = JSON.stringify(payload);
+        logger.debug(`=> {"type": ${JSON.stringify(payload.type)}, ...}`);
+
+        await this.rendezvousSession.send(await this.encrypt(stringifiedPayload));
+    }
+
+    /**
+     * Receives an encrypted payload from the other device and decrypts it.
+     */
+    public async secureReceive<T extends MSC4108Payload>(): Promise<Partial<T> | undefined> {
+        if (!this.establishedChannel) {
+            throw new Error("Channel closed");
+        }
+
+        const ciphertext = await this.rendezvousSession.receive();
+        if (!ciphertext) {
+            return undefined;
+        }
+        const plaintext = await this.decrypt(ciphertext);
+        const json = JSON.parse(plaintext);
+
+        logger.debug(`<= {"type": ${JSON.stringify(json.type)}, ...}`);
+        return json as Partial<T> | undefined;
+    }
+
+    /**
+     * Closes the secure channel.
+     */
+    public async close(): Promise<void> {
+        await this.rendezvousSession.close();
+    }
+
+    /**
+     * Cancels the secure channel.
+     * @param reason the reason for the cancellation
+     */
+    public async cancel(reason: MSC4108FailureReason | ClientRendezvousFailureReason): Promise<void> {
+        try {
+            await this.rendezvousSession.cancel(reason);
+            this.onFailure?.(reason);
+        } finally {
+            await this.close();
+        }
+    }
+
+    /**
+     * Returns whether the rendezvous session has been cancelled.
+     */
+    public get cancelled(): boolean {
+        return this.rendezvousSession.cancelled;
+    }
+}

package/src/rendezvous/channels/index.ts

@@ -0,0 +1,17 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export * from "./MSC4108SecureChannel.ts";

package/src/rendezvous/index.ts

@@ -0,0 +1,25 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export * from "./MSC4108SignInWithQR.ts";
+export type * from "./RendezvousChannel.ts";
+export type * from "./RendezvousCode.ts";
+export * from "./RendezvousError.ts";
+export * from "./RendezvousFailureReason.ts";
+export * from "./RendezvousIntent.ts";
+export type * from "./RendezvousTransport.ts";
+export * from "./transports/index.ts";
+export * from "./channels/index.ts";

package/src/rendezvous/transports/MSC4108RendezvousSession.ts

@@ -0,0 +1,272 @@
+/*
+Copyright 2024 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { logger } from "../../logger.ts";
+import { sleep } from "../../utils.ts";
+import { ClientRendezvousFailureReason, MSC4108FailureReason, type RendezvousFailureListener } from "../index.ts";
+import { type BriijClient } from "../../client.ts";
+import { ClientPrefix, Method } from "../../http-api/index.ts";
+
+/**
+ * Prototype of the unstable [MSC4108](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
+ * insecure rendezvous session protocol.
+ * @experimental Note that this is UNSTABLE and may have breaking changes without notice.
+ */
+export class MSC4108RendezvousSession {
+    public url?: string;
+    private readonly client?: BriijClient;
+    private readonly fallbackRzServer?: string;
+    private readonly fetchFn?: typeof globalThis.fetch;
+    private readonly onFailure?: RendezvousFailureListener;
+    private etag?: string;
+    private expiresAt?: Date;
+    private expiresTimer?: ReturnType<typeof setTimeout>;
+    private _cancelled = false;
+    private _ready = false;
+
+    public constructor({
+        onFailure,
+        url,
+        fetchFn,
+    }: {
+        fetchFn?: typeof globalThis.fetch;
+        onFailure?: RendezvousFailureListener;
+        url: string;
+    });
+    public constructor({
+        onFailure,
+        client,
+        fallbackRzServer,
+        fetchFn,
+    }: {
+        fetchFn?: typeof globalThis.fetch;
+        onFailure?: RendezvousFailureListener;
+        client?: BriijClient;
+        fallbackRzServer?: string;
+    });
+    public constructor({
+        fetchFn,
+        onFailure,
+        url,
+        client,
+        fallbackRzServer,
+    }: {
+        fetchFn?: typeof globalThis.fetch;
+        onFailure?: RendezvousFailureListener;
+        url?: string;
+        client?: BriijClient;
+        fallbackRzServer?: string;
+    }) {
+        this.fetchFn = fetchFn;
+        this.onFailure = onFailure;
+        this.client = client;
+        this.fallbackRzServer = fallbackRzServer;
+        this.url = url;
+    }
+
+    /**
+     * Returns whether the channel is ready to be used.
+     */
+    public get ready(): boolean {
+        return this._ready;
+    }
+
+    /**
+     * Returns whether the channel has been cancelled.
+     */
+    public get cancelled(): boolean {
+        return this._cancelled;
+    }
+
+    private fetch(resource: URL | string, options?: RequestInit): ReturnType<typeof globalThis.fetch> {
+        if (this.fetchFn) {
+            return this.fetchFn(resource, options);
+        }
+        return globalThis.fetch(resource, options);
+    }
+
+    private async getPostEndpoint(): Promise<string | undefined> {
+        if (this.client) {
+            try {
+                if (await this.client.doesServerSupportUnstableFeature("org.matrix.msc4108")) {
+                    return this.client.http
+                        .getUrl("/org.matrix.msc4108/rendezvous", undefined, ClientPrefix.Unstable)
+                        .toString();
+                }
+            } catch (err) {
+                logger.warn("Failed to get unstable features", err);
+            }
+        }
+
+        return this.fallbackRzServer;
+    }
+
+    /**
+     * Sends data via the rendezvous channel.
+     * @param data the payload to send
+     */
+    public async send(data: string): Promise<void> {
+        if (this._cancelled) {
+            return;
+        }
+        const method = this.url ? Method.Put : Method.Post;
+        const uri = this.url ?? (await this.getPostEndpoint());
+
+        if (!uri) {
+            throw new Error("Invalid rendezvous URI");
+        }
+
+        const headers: Record<string, string> = { "content-type": "text/plain" };
+
+        // if we didn't create the rendezvous channel, we need to fetch the first etag if needed
+        if (!this.etag && this.url) {
+            await this.receive();
+        }
+
+        if (this.etag) {
+            headers["if-match"] = this.etag;
+        }
+
+        logger.info(`=> ${method} ${uri} with ${data} if-match: ${this.etag}`);
+
+        const res = await this.fetch(uri, { method, headers, body: data, redirect: "follow" });
+        if (res.status === 404) {
+            return this.cancel(ClientRendezvousFailureReason.Unknown);
+        }
+        this.etag = res.headers.get("etag") ?? undefined;
+
+        logger.info(`Received etag: ${this.etag}`);
+
+        if (method === Method.Post) {
+            const expires = res.headers.get("expires");
+            if (expires) {
+                if (this.expiresTimer) {
+                    clearTimeout(this.expiresTimer);
+                    this.expiresTimer = undefined;
+                }
+                this.expiresAt = new Date(expires);
+                this.expiresTimer = setTimeout(() => {
+                    this.expiresTimer = undefined;
+                    this.cancel(ClientRendezvousFailureReason.Expired);
+                }, this.expiresAt.getTime() - Date.now());
+            }
+            // MSC4108: we expect a JSON response with a rendezvous URL
+            const json = await res.json();
+            if (typeof json.url !== "string") {
+                throw new Error("No rendezvous URL given");
+            }
+            this.url = json.url;
+            this._ready = true;
+        }
+    }
+
+    /**
+     * Receives data from the rendezvous channel.
+     * @return the returned promise won't resolve until new data is acquired or the channel is closed either by the server or the other party.
+     */
+    public async receive(): Promise<string | undefined> {
+        if (!this.url) {
+            throw new Error("Rendezvous not set up");
+        }
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (this._cancelled) {
+                return undefined;
+            }
+
+            const headers: Record<string, string> = {};
+            if (this.etag) {
+                headers["if-none-match"] = this.etag;
+            }
+
+            logger.info(`=> GET ${this.url} if-none-match: ${this.etag}`);
+            const poll = await this.fetch(this.url, { method: Method.Get, headers });
+
+            if (poll.status === 404) {
+                await this.cancel(ClientRendezvousFailureReason.Unknown);
+                return undefined;
+            }
+
+            // rely on server expiring the channel rather than checking ourselves
+
+            const etag = poll.headers.get("etag") ?? undefined;
+            if (poll.headers.get("content-type") !== "text/plain") {
+                this.etag = etag;
+            } else if (poll.status === 200) {
+                if (!etag) {
+                    // Some browsers & extensions block the ETag header for anti-tracking purposes
+                    // We try and detect this so the client can give the user a somewhat helpful message
+                    await this.cancel(ClientRendezvousFailureReason.ETagMissing);
+                    return undefined;
+                }
+
+                this.etag = etag;
+                const text = await poll.text();
+                logger.info(`Received: ${text} with etag ${this.etag}`);
+                return text;
+            }
+            await sleep(1000);
+        }
+    }
+
+    /**
+     * Cancels the rendezvous channel.
+     * If the reason is user_declined or user_cancelled then the channel will also be closed.
+     * @param reason the reason to cancel with
+     */
+    public async cancel(reason: MSC4108FailureReason | ClientRendezvousFailureReason): Promise<void> {
+        if (this._cancelled) return;
+        if (this.expiresTimer) {
+            clearTimeout(this.expiresTimer);
+            this.expiresTimer = undefined;
+        }
+
+        if (
+            reason === ClientRendezvousFailureReason.Unknown &&
+            this.expiresAt &&
+            this.expiresAt.getTime() < Date.now()
+        ) {
+            reason = ClientRendezvousFailureReason.Expired;
+        }
+
+        this._cancelled = true;
+        this._ready = false;
+        this.onFailure?.(reason);
+
+        if (reason === ClientRendezvousFailureReason.UserDeclined || reason === MSC4108FailureReason.UserCancelled) {
+            await this.close();
+        }
+    }
+
+    /**
+     * Closes the rendezvous channel.
+     */
+    public async close(): Promise<void> {
+        if (this.expiresTimer) {
+            clearTimeout(this.expiresTimer);
+            this.expiresTimer = undefined;
+        }
+
+        if (!this.url) return;
+        try {
+            const method = Method.Delete;
+            logger.info(`=> ${method} ${this.url}`);
+            await this.fetch(this.url, { method });
+        } catch (e) {
+            logger.warn(e);
+        }
+    }
+}

package/src/rendezvous/transports/index.ts

@@ -0,0 +1,17 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export * from "./MSC4108RendezvousSession.ts";