@textrp/briij-js-sdk 42.0.0 → 43.0.0

package/src/@types/auth.ts

@@ -39,6 +39,8 @@ export interface ILoginFlowsResponse {
 }
 
 export const XRPL_WALLET_LOGIN_TYPE = "io.briij.login.xrpl";
+export const WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE = "org.textrp.wallet.e2ee_recovery.v1";
+export const WALLET_IDENTITY_ACCOUNT_DATA_TYPE = "org.textrp.wallet.identity";
 
 export type LoginFlow = ISSOFlow | IPasswordFlow | IXrplWalletLoginFlow | ILoginFlow;
 
@@ -206,6 +208,7 @@ export interface LoginRequest {
 export type ILoginParams = LoginRequest;
 
 export interface XrplWalletChallengePayload {
+    session?: string;
     nonce: string;
     timestamp: number | string;
     message: string;
@@ -213,6 +216,63 @@ export interface XrplWalletChallengePayload {
     algorithm?: "secp256k1" | "ed25519" | string;
 }
 
+export interface XrplAuthChallengeRequest extends Omit<LoginRequest, "type"> {
+    type: typeof XRPL_WALLET_LOGIN_TYPE;
+    address: string;
+    network: string;
+    preferred_localpart?: string;
+    username?: string;
+    display_name?: string;
+}
+
+export interface XrplAuthChallengeResponse {
+    session: string;
+    challenge: string;
+}
+
+export interface XrplAuthCompleteRequest extends Omit<LoginRequest, "type"> {
+    type: typeof XRPL_WALLET_LOGIN_TYPE;
+    session: string;
+    address: string;
+    signature: string;
+    public_key?: string;
+    network?: string;
+    wallet_e2ee_recovery?: WalletE2eeRecoveryEnvelope;
+}
+
+export interface WalletRecoveryWrap {
+    alg: string;
+    kdf: string;
+    salt: string;
+    nonce: string;
+    ciphertext: string;
+    aad?: string;
+    params?: Record<string, unknown>;
+}
+
+export interface WalletRecoveryPasswordWrap extends WalletRecoveryWrap {
+    kdf: string;
+    params?: Record<string, unknown>;
+}
+
+export interface WalletE2eeRecoveryEnvelope {
+    envelope_version: number;
+    chain_id: string;
+    account_id: string;
+    created_at_ms: number;
+    key_id: string;
+    wallet_wrap: WalletRecoveryWrap;
+    password_wrap: WalletRecoveryPasswordWrap;
+}
+
+export interface WalletIdentityAccountData {
+    chain_id: string;
+    account_id: string;
+    public_key: string | null;
+    network?: string | null;
+    key_type?: string | null;
+}
+
 export interface XrplWalletLoginRequest extends Omit<LoginRequest, "type"> {
     type: typeof XRPL_WALLET_LOGIN_TYPE;
     wallet_address: string;

package/src/@types/event.ts

@@ -455,6 +455,38 @@ export interface AccountDataEvents extends SecretStorageAccountDataEvents {
     [POLICIES_ACCOUNT_EVENT_TYPE.altName]: { [key: string]: any };
 
     [EventType.InvitePermissionConfig]: { default_action?: string };
+    "org.textrp.wallet.e2ee_recovery.v1": {
+        envelope_version: number;
+        chain_id: string;
+        account_id: string;
+        created_at_ms: number;
+        key_id: string;
+        wallet_wrap: {
+            alg: string;
+            kdf: string;
+            salt: string;
+            nonce: string;
+            ciphertext: string;
+            aad?: string;
+            params?: Record<string, unknown>;
+        };
+        password_wrap: {
+            alg: string;
+            kdf: string;
+            salt: string;
+            nonce: string;
+            ciphertext: string;
+            aad?: string;
+            params?: Record<string, unknown>;
+        };
+    };
+    "org.textrp.wallet.identity": {
+        chain_id: string;
+        account_id: string;
+        public_key: string | null;
+        network?: string | null;
+        key_type?: string | null;
+    };
 }
 
 /**

package/src/briij.ts

@@ -52,6 +52,7 @@ export * from "./interactive-auth.ts";
 export * from "./xrpl/identity.ts";
 export * from "./xrpl/trust.ts";
 export * from "./xrpl/verification.ts";
+export * from "./wallet-recovery.ts";
 export * from "./version-support.ts";
 export * from "./service-types.ts";
 export * from "./store/memory.ts";

package/src/client.ts

@@ -198,7 +198,14 @@ 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";
@@ -6724,31 +6731,117 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
     }
 
     /**
-     * @param user - Matrix user ID localpart or fully qualified MXID.
-     * @param walletAddress - XRPL/Xahau classic wallet address.
-     * @param signature - Hex signature for the challenge message.
-     * @param challenge - Signed challenge payload.
-     * @param network - Ledger network identifier. Defaults to `xrpl`.
+     * 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 loginWithXrplWallet(
+    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> {
-        return this.login(XRPL_WALLET_LOGIN_TYPE, {
-            user: user,
+        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: user,
+                user,
             },
-            wallet_address: walletAddress,
-            signature: signature,
-            challenge: typeof challenge === "string" ? challenge : JSON.stringify(challenge),
-            network: network,
+            session,
+            address: walletAddress,
+            signature,
+            public_key: parsedChallenge?.public_key,
+            network,
         });
     }
 

package/src/wallet-recovery.ts

@@ -0,0 +1,252 @@
+/*
+Copyright 2026 TextRP
+
+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 WalletE2eeRecoveryEnvelope, type WalletRecoveryWrap } from "./@types/auth.ts";
+
+const ENVELOPE_VERSION = 1;
+const KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const SALT_BYTES = 16;
+const PASSWORD_KDF_ITERATIONS = 210_000;
+
+export interface CreateDualWrapEnvelopeParams {
+    chainId: string;
+    accountId: string;
+    backupPassword: string;
+    walletWrapKey: Uint8Array;
+    createdAtMs?: number;
+    keyId?: string;
+    recoveryKey?: Uint8Array;
+}
+
+export interface UnwrapWithWalletParams {
+    envelope: WalletE2eeRecoveryEnvelope;
+    walletWrapKey: Uint8Array;
+}
+
+export interface UnwrapWithPasswordParams {
+    envelope: WalletE2eeRecoveryEnvelope;
+    backupPassword: string;
+}
+
+function assert(condition: boolean, message: string): asserts condition {
+    if (!condition) throw new Error(message);
+}
+
+function toBase64(bytes: Uint8Array): string {
+    if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+    let binary = "";
+    bytes.forEach((b) => (binary += String.fromCodePoint(b)));
+    return btoa(binary);
+}
+
+function fromBase64(value: string): Uint8Array {
+    if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "base64"));
+    const binary = atob(value);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) out[i] = binary.codePointAt(i)!;
+    return out;
+}
+
+function toUtf8(value: string): Uint8Array {
+    return new TextEncoder().encode(value);
+}
+
+function toArrayBuffer(value: Uint8Array): ArrayBuffer {
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
+}
+
+function randomBytes(len: number): Uint8Array {
+    const out = new Uint8Array(len);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+}
+
+async function importAesGcmKey(key: Uint8Array): Promise<CryptoKey> {
+    return await globalThis.crypto.subtle.importKey(
+        "raw",
+        toArrayBuffer(key),
+        { name: "AES-GCM" },
+        false,
+        ["encrypt", "decrypt"],
+    );
+}
+
+async function encryptWrap(
+    plaintext: Uint8Array,
+    {
+        key,
+        aad,
+        kdf,
+        params,
+    }: {
+        key: Uint8Array;
+        aad: Uint8Array;
+        kdf: string;
+        params?: Record<string, unknown>;
+    },
+): Promise<WalletRecoveryWrap> {
+    assert(key.length >= KEY_BYTES, "wallet recovery key must be at least 32 bytes");
+    const salt = randomBytes(SALT_BYTES);
+    const nonce = randomBytes(NONCE_BYTES);
+    const cryptoKey = await importAesGcmKey(key.slice(0, KEY_BYTES));
+    const ciphertext = await globalThis.crypto.subtle.encrypt(
+        {
+            name: "AES-GCM",
+            iv: toArrayBuffer(nonce),
+            additionalData: toArrayBuffer(aad),
+            tagLength: 128,
+        },
+        cryptoKey,
+        toArrayBuffer(plaintext),
+    );
+    return {
+        alg: "aes-256-gcm",
+        kdf,
+        salt: toBase64(salt),
+        nonce: toBase64(nonce),
+        ciphertext: toBase64(new Uint8Array(ciphertext)),
+        aad: toBase64(aad),
+        params,
+    };
+}
+
+async function decryptWrap(wrap: WalletRecoveryWrap, key: Uint8Array): Promise<Uint8Array> {
+    const nonce = fromBase64(wrap.nonce);
+    const aad = wrap.aad ? fromBase64(wrap.aad) : new Uint8Array();
+    const ciphertext = fromBase64(wrap.ciphertext);
+    const cryptoKey = await importAesGcmKey(key.slice(0, KEY_BYTES));
+    const plaintext = await globalThis.crypto.subtle.decrypt(
+        {
+            name: "AES-GCM",
+            iv: toArrayBuffer(nonce),
+            additionalData: toArrayBuffer(aad),
+            tagLength: 128,
+        },
+        cryptoKey,
+        toArrayBuffer(ciphertext),
+    );
+    return new Uint8Array(plaintext);
+}
+
+async function derivePasswordWrapKey(password: string, salt: Uint8Array): Promise<Uint8Array> {
+    const keyMaterial = await globalThis.crypto.subtle.importKey("raw", toArrayBuffer(toUtf8(password)), "PBKDF2", false, [
+        "deriveBits",
+    ]);
+    const bits = await globalThis.crypto.subtle.deriveBits(
+        {
+            name: "PBKDF2",
+            hash: "SHA-256",
+            salt: toArrayBuffer(salt),
+            iterations: PASSWORD_KDF_ITERATIONS,
+        },
+        keyMaterial,
+        KEY_BYTES * 8,
+    );
+    return new Uint8Array(bits);
+}
+
+export async function deriveWalletWrapKeyFromSecret(
+    walletSecret: string,
+    chainId: string,
+    accountId: string,
+    homeserver: string,
+): Promise<Uint8Array> {
+    const context = `briij-wallet-auth-wrap-v1:${homeserver}:${chainId}:${accountId}`;
+    const digest = await globalThis.crypto.subtle.digest(
+        "SHA-256",
+        toArrayBuffer(toUtf8(`${context}:${walletSecret}`)),
+    );
+    return new Uint8Array(digest);
+}
+
+export function validateRecoveryEnvelopeShape(
+    value: unknown,
+): asserts value is WalletE2eeRecoveryEnvelope {
+    assert(!!value && typeof value === "object", "recovery envelope must be an object");
+    const envelope = value as WalletE2eeRecoveryEnvelope;
+    assert(typeof envelope.envelope_version === "number", "envelope_version must be a number");
+    assert(typeof envelope.chain_id === "string" && envelope.chain_id.length > 0, "chain_id is required");
+    assert(typeof envelope.account_id === "string" && envelope.account_id.length > 0, "account_id is required");
+    assert(typeof envelope.created_at_ms === "number", "created_at_ms must be a number");
+    assert(typeof envelope.key_id === "string" && envelope.key_id.length > 0, "key_id is required");
+    assert(!!envelope.wallet_wrap && typeof envelope.wallet_wrap === "object", "wallet_wrap is required");
+    assert(!!envelope.password_wrap && typeof envelope.password_wrap === "object", "password_wrap is required");
+    for (const wrap of [envelope.wallet_wrap, envelope.password_wrap]) {
+        assert(typeof wrap.alg === "string" && wrap.alg.length > 0, "wrap.alg is required");
+        assert(typeof wrap.kdf === "string" && wrap.kdf.length > 0, "wrap.kdf is required");
+        assert(typeof wrap.salt === "string" && wrap.salt.length > 0, "wrap.salt is required");
+        assert(typeof wrap.nonce === "string" && wrap.nonce.length > 0, "wrap.nonce is required");
+        assert(typeof wrap.ciphertext === "string" && wrap.ciphertext.length > 0, "wrap.ciphertext is required");
+    }
+}
+
+export async function createDualWrapEnvelope(params: CreateDualWrapEnvelopeParams): Promise<WalletE2eeRecoveryEnvelope> {
+    assert(params.chainId.length > 0, "chainId is required");
+    assert(params.accountId.length > 0, "accountId is required");
+    assert(params.backupPassword.length > 0, "backupPassword is required");
+    assert(params.walletWrapKey.length >= KEY_BYTES, "walletWrapKey must be at least 32 bytes");
+
+    const createdAtMs = params.createdAtMs ?? Date.now();
+    const keyId = params.keyId ?? `k-${toBase64(randomBytes(8)).replace(/=+$/g, "")}`;
+    const recoveryKey = params.recoveryKey ?? randomBytes(KEY_BYTES);
+    assert(recoveryKey.length === KEY_BYTES, "recoveryKey must be 32 bytes");
+
+    const aad = toUtf8(`briij-recovery-envelope-v1:${params.chainId}:${params.accountId}:${keyId}:${createdAtMs}`);
+    const walletWrap = await encryptWrap(recoveryKey, {
+        key: params.walletWrapKey,
+        aad,
+        kdf: "sha256-context-v1",
+    });
+
+    const passwordSalt = randomBytes(SALT_BYTES);
+    const passwordWrapKey = await derivePasswordWrapKey(params.backupPassword, passwordSalt);
+    const passwordWrap = await encryptWrap(recoveryKey, {
+        key: passwordWrapKey,
+        aad,
+        kdf: "pbkdf2-sha256-v1",
+        params: {
+            iterations: PASSWORD_KDF_ITERATIONS,
+            hash: "SHA-256",
+        },
+    });
+    passwordWrap.salt = toBase64(passwordSalt);
+
+    return {
+        envelope_version: ENVELOPE_VERSION,
+        chain_id: params.chainId,
+        account_id: params.accountId,
+        created_at_ms: createdAtMs,
+        key_id: keyId,
+        wallet_wrap: walletWrap,
+        password_wrap: passwordWrap,
+    };
+}
+
+export async function unwrapWithWallet({ envelope, walletWrapKey }: UnwrapWithWalletParams): Promise<Uint8Array> {
+    validateRecoveryEnvelopeShape(envelope);
+    return await decryptWrap(envelope.wallet_wrap, walletWrapKey);
+}
+
+export async function unwrapWithPassword({
+    envelope,
+    backupPassword,
+}: UnwrapWithPasswordParams): Promise<Uint8Array> {
+    validateRecoveryEnvelopeShape(envelope);
+    const passwordSalt = fromBase64(envelope.password_wrap.salt);
+    const passwordWrapKey = await derivePasswordWrapKey(backupPassword, passwordSalt);
+    return await decryptWrap(envelope.password_wrap, passwordWrapKey);
+}