@textrp/briij-js-sdk 41.0.1 → 43.0.0

package/src/client.ts

@@ -198,6 +198,15 @@ import {
     type LoginResponse,
     type LoginTokenPostResponse,
     type SSOAction,
+    WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE,
+    WALLET_IDENTITY_ACCOUNT_DATA_TYPE,
+    XRPL_WALLET_LOGIN_TYPE,
+    type WalletE2eeRecoveryEnvelope,
+    type WalletIdentityAccountData,
+    type XrplAuthChallengeRequest,
+    type XrplAuthChallengeResponse,
+    type XrplAuthCompleteRequest,
+    type XrplWalletChallengePayload,
 } from "./@types/auth.ts";
 import { TypedEventEmitter } from "./models/typed-event-emitter.ts";
 import { MAIN_ROOM_TIMELINE, ReceiptType } from "./@types/read_receipts.ts";
@@ -246,6 +255,13 @@ import {
     type OidcClientConfig,
     validateAuthMetadataAndKeys,
 } from "./oidc/index.ts";
+import { configureXrplIdentityMinting, mintSoulboundIdentityNFT } from "./xrpl/identity.ts";
+import {
+    XRPL_VERIFIED_EVENT,
+    XRPL_VERIFY_ACCEPT_EVENT,
+    XRPL_VERIFY_REQUEST_EVENT,
+} from "./xrpl/verification.ts";
+import { configureXrplTrust } from "./xrpl/trust.ts";
 import { type EmptyObject } from "./@types/common.ts";
 import { UnsupportedDelayedEventsEndpointError, UnsupportedStickyEventsEndpointError } from "./errors.ts";
 import { type Transport } from "./matrixrtc/index.ts";
@@ -1100,6 +1116,9 @@ export enum ClientEvent {
      */
     ClientWellKnown = "WellKnown.client",
     ReceivedVoipEvent = "received_voip_event",
+    XrplVerificationRequest = "xrpl.verification.request",
+    XrplVerificationAccept = "xrpl.verification.accept",
+    XrplVerified = "xrpl.verification.verified",
     TurnServers = "turnServers",
     TurnServersError = "turnServers.error",
 }
@@ -1170,6 +1189,9 @@ export type ClientEventHandlerMap = {
     [ClientEvent.SyncUnexpectedError]: (error: Error) => void;
     [ClientEvent.ClientWellKnown]: (data: IClientWellKnown) => void;
     [ClientEvent.ReceivedVoipEvent]: (event: BriijEvent) => void;
+    [ClientEvent.XrplVerificationRequest]: (event: BriijEvent) => void;
+    [ClientEvent.XrplVerificationAccept]: (event: BriijEvent) => void;
+    [ClientEvent.XrplVerified]: (event: BriijEvent) => void;
     [ClientEvent.TurnServers]: (servers: ITurnServer[]) => void;
     [ClientEvent.TurnServersError]: (error: Error, fatal: boolean) => void;
 } & RoomEventHandlerMap &
@@ -1394,6 +1416,7 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
         this.serverCapabilitiesService = new ServerCapabilities(this.logger, this.http);
 
         this.on(ClientEvent.Sync, this.fixupRoomNotifications);
+        this.on(ClientEvent.Event, this.dispatchXrplVerificationEvents);
 
         this.timelineSupport = Boolean(opts.timelineSupport);
 
@@ -1440,6 +1463,22 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
         return this._store;
     }
 
+    private readonly dispatchXrplVerificationEvents = (event: BriijEvent): void => {
+        if (event.getType() === XRPL_VERIFY_REQUEST_EVENT) {
+            this.emit(ClientEvent.XrplVerificationRequest, event);
+            return;
+        }
+
+        if (event.getType() === XRPL_VERIFY_ACCEPT_EVENT) {
+            this.emit(ClientEvent.XrplVerificationAccept, event);
+            return;
+        }
+
+        if (event.getType() === XRPL_VERIFIED_EVENT) {
+            this.emit(ClientEvent.XrplVerified, event);
+        }
+    };
+
     /**
      * High level helper method to begin syncing and poll for new events. To listen for these
      * events, add a listener for {@link ClientEvent.Event}
@@ -6642,19 +6681,38 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
      *    returned credentials. Instead, call {@link loginRequest} and create a new `BriijClient` instance using the
      *    results. See https://github.com/matrix-org/briij-js-sdk/issues/4502.
      */
-    public login(loginType: LoginRequest["type"], data: Omit<LoginRequest, "type">): Promise<LoginResponse> {
-        return this.loginRequest({
+    public async login(loginType: LoginRequest["type"], data: Omit<LoginRequest, "type">): Promise<LoginResponse> {
+        const response = await this.loginRequest({
             ...data,
             type: loginType,
-        }).then((response) => {
-            if (response.access_token && response.user_id) {
-                this.http.opts.accessToken = response.access_token;
-                this.credentials = {
-                    userId: response.user_id,
-                };
-            }
-            return response;
         });
+
+        if (response.access_token && response.user_id) {
+            this.http.opts.accessToken = response.access_token;
+            this.credentials = {
+                userId: response.user_id,
+            };
+            configureXrplTrust({
+                homeserverBaseUrl: this.baseUrl,
+                accessToken: response.access_token,
+            });
+        }
+
+        // After Xaman-backed SSO login, mint once and persist identity metadata in account_data.
+        if (loginType === "m.login.token" && response.access_token && response.user_id) {
+            configureXrplIdentityMinting({
+                homeserverBaseUrl: this.baseUrl,
+                accessToken: response.access_token,
+            });
+
+            try {
+                await mintSoulboundIdentityNFT(response.user_id);
+            } catch (error) {
+                logger.warn("XRPL identity NFT minting skipped/failed", error);
+            }
+        }
+
+        return response;
     }
 
     /**
@@ -6672,6 +6730,121 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
         });
     }
 
+    /**
+     * Request an XRPL login challenge from the homeserver.
+     *
+     * The briij homeserver responds with HTTP 401 as the successful challenge
+     * response, so this helper normalizes that into a resolved promise.
+     */
+    public async getXrplAuthChallenge(
+        request: Omit<XrplAuthChallengeRequest, "type">,
+    ): Promise<XrplAuthChallengeResponse> {
+        try {
+            const response = (await this.loginRequest({
+                ...request,
+                type: XRPL_WALLET_LOGIN_TYPE,
+            })) as unknown as XrplAuthChallengeResponse;
+            if (typeof response.session === "string" && typeof response.challenge === "string") {
+                return response;
+            }
+        } catch (error) {
+            if (error instanceof BriijError && error.httpStatus === 401) {
+                const session = error.data?.session;
+                const challenge = error.data?.challenge;
+                if (typeof session === "string" && typeof challenge === "string") {
+                    return { session, challenge };
+                }
+            }
+            throw error;
+        }
+
+        throw new Error("XRPL challenge response was not returned by homeserver");
+    }
+
+    /**
+     * Complete XRPL login using the previously issued challenge session.
+     *
+     * @returns Promise which resolves to a LoginResponse object.
+     * @returns Rejects: with an error response.
+     */
+    public completeXrplAuth(request: Omit<XrplAuthCompleteRequest, "type">): Promise<LoginResponse> {
+        return this.loginRequest({
+            ...request,
+            type: XRPL_WALLET_LOGIN_TYPE,
+        });
+    }
+
+    /**
+     * Store a chain-agnostic wallet recovery envelope in account data.
+     *
+     * This uses a stable account-data type and does not affect core E2EE state.
+     *
+     * @param envelope - Wallet recovery envelope payload.
+     */
+    public setWalletRecoveryEnvelope(envelope: WalletE2eeRecoveryEnvelope): Promise<EmptyObject> {
+        return this.setAccountDataRaw(WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE, envelope);
+    }
+
+    /**
+     * Fetch wallet recovery envelope directly from the homeserver.
+     *
+     * @returns The stored envelope, or null if not found.
+     */
+    public getWalletRecoveryEnvelopeFromServer(): Promise<WalletE2eeRecoveryEnvelope | null> {
+        return this.getAccountDataFromServer(WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE);
+    }
+
+    /**
+     * Fetch canonical wallet identity metadata from the homeserver.
+     *
+     * @returns Wallet identity metadata, or null if not found.
+     */
+    public getWalletIdentityFromServer(): Promise<WalletIdentityAccountData | null> {
+        return this.getAccountDataFromServer(WALLET_IDENTITY_ACCOUNT_DATA_TYPE);
+    }
+
+    /**
+     * @deprecated Use `getXrplAuthChallenge` + `completeXrplAuth` for explicit
+     * two-step XRPL login flow. This wrapper now expects `challenge` to include
+     * the `session` and optional `public_key`.
+     */
+    public async loginWithXrplWallet(
+        user: string,
+        walletAddress: string,
+        signature: string,
+        challenge: string | XrplWalletChallengePayload,
+        network = "xrpl",
+    ): Promise<LoginResponse> {
+        let parsedChallenge: Partial<XrplWalletChallengePayload> | null = null;
+        if (typeof challenge === "string") {
+            try {
+                parsedChallenge = JSON.parse(challenge) as Partial<XrplWalletChallengePayload>;
+            } catch {
+                throw new Error("XRPL challenge must be JSON with a session field");
+            }
+        } else {
+            parsedChallenge = challenge;
+        }
+
+        const session = parsedChallenge?.session;
+        if (!session) {
+            throw new Error("XRPL challenge payload is missing session; call getXrplAuthChallenge first");
+        }
+
+        return this.completeXrplAuth({
+            user,
+            identifier: {
+                type: "m.id.user",
+                user,
+            },
+            session,
+            address: walletAddress,
+            signature,
+            public_key: parsedChallenge?.public_key,
+            network,
+        });
+    }
+
     /**
      * @param redirectUrl - The URL to redirect to after the HS
      * authenticates with CAS.

package/src/common-crypto/README.md

@@ -1,4 +1,4 @@
-This directory contains functionality which is common to both the legacy (libolm-based) crypto implementation,
-and the new rust-based implementation.
-
-It is an internal module, and is _not_ directly exposed to applications.
+This directory contains functionality which is common to both the legacy (libolm-based) crypto implementation,
+and the new rust-based implementation.
+
+It is an internal module, and is _not_ directly exposed to applications.

package/src/common-crypto/key-passphrase.ts

@@ -1,43 +1,43 @@
-/*
- * 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 { deriveRecoveryKeyFromPassphrase } from "../crypto-api/index.ts";
-
-/* eslint-disable camelcase */
-interface IAuthData {
-    private_key_salt?: string;
-    private_key_iterations?: number;
-    private_key_bits?: number;
-}
-
-/**
- * Derive a backup key from a passphrase using the salt and iterations from the auth data.
- * @param authData - The auth data containing the salt and iterations
- * @param passphrase - The passphrase to derive the key from
- * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.
- */
-export function keyFromAuthData(authData: IAuthData, passphrase: string): Promise<Uint8Array> {
-    if (!authData.private_key_salt || !authData.private_key_iterations) {
-        throw new Error("Salt and/or iterations not found: " + "this backup cannot be restored with a passphrase");
-    }
-
-    return deriveRecoveryKeyFromPassphrase(
-        passphrase,
-        authData.private_key_salt,
-        authData.private_key_iterations,
-        authData.private_key_bits,
-    );
-}
+/*
+ * 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 { deriveRecoveryKeyFromPassphrase } from "../crypto-api/index.ts";
+
+/* eslint-disable camelcase */
+interface IAuthData {
+    private_key_salt?: string;
+    private_key_iterations?: number;
+    private_key_bits?: number;
+}
+
+/**
+ * Derive a backup key from a passphrase using the salt and iterations from the auth data.
+ * @param authData - The auth data containing the salt and iterations
+ * @param passphrase - The passphrase to derive the key from
+ * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.
+ */
+export function keyFromAuthData(authData: IAuthData, passphrase: string): Promise<Uint8Array> {
+    if (!authData.private_key_salt || !authData.private_key_iterations) {
+        throw new Error("Salt and/or iterations not found: " + "this backup cannot be restored with a passphrase");
+    }
+
+    return deriveRecoveryKeyFromPassphrase(
+        passphrase,
+        authData.private_key_salt,
+        authData.private_key_iterations,
+        authData.private_key_bits,
+    );
+}