@textrp/briij-js-sdk 43.2.1 → 44.1.0

package/src/client.ts

@@ -204,6 +204,11 @@ import {
 } from "./webrtc/groupCall.ts";
 import { MediaHandler } from "./webrtc/mediaHandler.ts";
 import {
+    type CredentialCreateResult,
+    type CredentialVerifyResult,
+    type DidCredentialMetadata,
+    type DidResolutionResult,
+    type ZkpVerifyResult,
     type ILoginFlowsResponse,
     type IRefreshTokenResponse,
     type LoginRequest,
@@ -220,6 +225,15 @@ import {
     type XrplAuthCompleteRequest,
     type XrplWalletChallengePayload,
 } from "./@types/auth.ts";
+import { createMinimalDidDocument, deriveXrplDid, resolveDidViaHomeserver } from "./auth/did.ts";
+import {
+    loadDidCredentialMetadata,
+    requestCredentialCreate,
+    storeDidCredentialMetadata,
+    verifyCredential,
+} from "./auth/credential.ts";
+import { generateE2eeZkProof } from "./auth/zkpE2EE.ts";
+import { buildWalletLoginSubmission, type WalletProofProvider, type WalletProofResult } from "./auth/wallet.ts";
 import { TypedEventEmitter } from "./models/typed-event-emitter.ts";
 import { MAIN_ROOM_TIMELINE, ReceiptType } from "./@types/read_receipts.ts";
 import { type MSC3575SlidingSyncRequest, type MSC3575SlidingSyncResponse, type SlidingSync } from "./sliding-sync.ts";
@@ -6997,6 +7011,179 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
         });
     }
 
+    /**
+     * XRPL DID + credential login flow:
+     * 1) challenge request, 2) wallet proof submission, 3) DID resolve, 4) credential request.
+     */
+    public async loginWithXrplDidCredential(params: {
+        address: string;
+        username?: string;
+        network?: string;
+        didNetwork?: "testnet" | "mainnet";
+        e2eePubkeyCommitment?: string;
+        longevityMode?: boolean;
+        walletProofProvider: WalletProofProvider;
+        zkpLongevityMode?: {
+            enabled: boolean;
+            e2eePrivateKey?: string;
+            strict?: boolean;
+            generateProof?: (context: {
+                didUri: string;
+                xrplAddress: string;
+                credentialId: string;
+                e2eePubkeyCommitment: string;
+            }) => Promise<{ proof: Record<string, unknown>; publicSignals: string[] | Record<string, string> }>;
+        };
+    }): Promise<
+        LoginResponse & {
+            did: DidResolutionResult;
+            didDocument: ReturnType<typeof createMinimalDidDocument>;
+            credential: CredentialCreateResult;
+            credentialVerification: CredentialVerifyResult;
+            metadata: DidCredentialMetadata;
+            zkp?: ZkpVerifyResult;
+        }
+    > {
+        const network = params.network ?? "xrpl";
+        const didNetwork = params.didNetwork ?? "testnet";
+
+        const challenge = await this.getXrplAuthChallenge({
+            address: params.address,
+            network,
+            username: params.username,
+            preferred_localpart: params.username,
+        });
+
+        const walletProof: WalletProofResult = await params.walletProofProvider(challenge.challenge, network);
+        if (walletProof.address !== params.address) {
+            throw new Error("Wallet proof address mismatch");
+        }
+
+        const loginResponse = await this.completeXrplAuth(
+            buildWalletLoginSubmission(walletProof, challenge.session, network, params.username),
+        );
+        await this.applyLoginResponse(loginResponse, XRPL_WALLET_LOGIN_TYPE);
+
+        const didUri = deriveXrplDid(walletProof.address, didNetwork);
+        const commitment = params.e2eePubkeyCommitment ?? (await this.createE2eeCommitment(loginResponse.user_id));
+        const didDocument = createMinimalDidDocument(didUri, commitment);
+
+        const did = await resolveDidViaHomeserver(async (path: string) => {
+            return this.http.authedRequest<DidResolutionResult>(Method.Get, path);
+        }, walletProof.address);
+
+        const credential = await requestCredentialCreate(
+            async (path, method, body) => this.http.authedRequest<CredentialCreateResult>(Method.Post, path, undefined, body),
+            {
+                subject: walletProof.address,
+                did_uri: did.did_uri ?? didUri,
+                e2ee_pubkey_commitment: commitment,
+            },
+        );
+
+        const credentialVerification = await verifyCredential(
+            async (path, method, body) =>
+                this.http.authedRequest<CredentialVerifyResult>(Method.Post, path, undefined, body),
+            credential.credential_id,
+        );
+
+        const zkpModeEnabled = params.longevityMode ?? params.zkpLongevityMode?.enabled ?? false;
+        let zkp: ZkpVerifyResult | undefined;
+        if (zkpModeEnabled) {
+            try {
+                const generatedProof =
+                    (await params.zkpLongevityMode?.generateProof?.({
+                        didUri: did.did_uri ?? didUri,
+                        xrplAddress: walletProof.address,
+                        credentialId: credential.credential_id,
+                        e2eePubkeyCommitment: commitment,
+                    })) ??
+                    (await generateE2eeZkProof(
+                        {
+                            didUri: did.did_uri ?? didUri,
+                            xrplAddress: walletProof.address,
+                            credentialId: credential.credential_id,
+                            e2eePrivateKey: params.zkpLongevityMode?.e2eePrivateKey ?? commitment,
+                        },
+                        {
+                            wasmPath: "/circuits/e2ee_credential.wasm",
+                            zkeyPath: "/circuits/e2ee_credential.zkey",
+                        },
+                    ));
+
+                zkp = await this.http.authedRequest<ZkpVerifyResult>(Method.Post, "/zkp/verify", undefined, {
+                    proof: generatedProof.proof,
+                    public_signals: generatedProof.publicSignals,
+                    e2ee_pubkey_commitment: commitment,
+                });
+            } catch (error) {
+                if (params.zkpLongevityMode?.strict) {
+                    throw error;
+                }
+                zkp = { valid: false, reason: "zkp_verification_skipped" };
+            }
+        }
+
+        const metadata: DidCredentialMetadata = {
+            didUri: did.did_uri ?? didUri,
+            credentialId: credential.credential_id,
+            issuedAt: Date.now(),
+        };
+        storeDidCredentialMetadata(loginResponse.user_id, metadata);
+        await this.persistDidDeviceBinding({
+            didUri: metadata.didUri,
+            credentialId: metadata.credentialId,
+            e2eePubkeyCommitment: commitment,
+            xrplAddress: walletProof.address,
+            network,
+        });
+
+        return {
+            ...loginResponse,
+            did,
+            didDocument,
+            credential,
+            credentialVerification,
+            metadata,
+            zkp,
+        };
+    }
+
+    public getStoredDidCredentialMetadata(userId: string): DidCredentialMetadata | null {
+        return loadDidCredentialMetadata(userId);
+    }
+
+    private async createE2eeCommitment(seed: string): Promise<string> {
+        if (!globalThis.crypto?.subtle) {
+            return encodeUnpaddedBase64Url(new TextEncoder().encode(seed));
+        }
+        const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(seed));
+        return Array.from(new Uint8Array(digest))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+
+    private async persistDidDeviceBinding(binding: {
+        didUri: string;
+        credentialId: string;
+        e2eePubkeyCommitment: string;
+        xrplAddress: string;
+        network: string;
+    }): Promise<void> {
+        try {
+            await this.setAccountData(WALLET_IDENTITY_ACCOUNT_DATA_TYPE, {
+                chain_id: "xrpl",
+                account_id: binding.xrplAddress,
+                network: binding.network,
+                did_uri: binding.didUri,
+                credential_id: binding.credentialId,
+                e2ee_pubkey_commitment: binding.e2eePubkeyCommitment,
+            });
+        } catch (error) {
+            logger.warn("Failed to persist DID/E2EE device binding metadata", error);
+        }
+    }
+
     /**
      * Store a chain-agnostic wallet recovery envelope in account data.
      *

package/src/components/LoginStepper.tsx

@@ -0,0 +1,50 @@
+/*
+Copyright 2026 Xurge Digital Lab
+
+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
+*/
+
+/* Mermaid flow reference:
+flowchart LR
+  wallet[Connect Wallet] --> login[Submit wallet proof to /login]
+  login --> did[Resolve/Create DID]
+  did --> cred[Request CredentialCreate]
+  cred --> done[Persist DID + credential metadata]
+*/
+
+export interface LoginStepperProps {
+    currentStep: 1 | 2 | 3 | 4 | 5;
+    longevityModeEnabled?: boolean;
+}
+
+/**
+ * Lightweight JSX component for apps consuming the SDK.
+ */
+export function LoginStepper({ currentStep, longevityModeEnabled = false }: LoginStepperProps): string {
+    const longevityToggle = `${longevityModeEnabled ? "[x]" : "[ ]"} Enable Longevity Mode (ZKP)`;
+    const warning = longevityModeEnabled
+        ? "ZKP path enabled: strongest DID-bound E2EE continuity."
+        : "Warning: continuing without ZKP uses wallet-signature fallback only.";
+    const steps = [
+        "1. Wallet Proof",
+        "2. DID Resolve/Create",
+        "3. Credential Create",
+        "4. Persist Metadata",
+        "5. ZKP Longevity Verify (optional)",
+    ];
+    const renderedSteps = steps
+        .map((step, idx) => {
+            if (idx === 4 && !longevityModeEnabled) {
+                return `[ ] ${step}`;
+            }
+            const active = idx + 1 <= currentStep ? "[x]" : "[ ]";
+            return `${active} ${step}`;
+        })
+        .join("\n");
+
+    return `${longevityToggle}\n${warning}\n${renderedSteps}`;
+}

package/src/xrpl/clientSignedBinding.ts

@@ -0,0 +1,136 @@
+/*
+Copyright 2026 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";
+
+export interface XrplClientSignedWalletAdapter {
+    getAddress(): Promise<string>;
+    signAndSubmit(tx: Record<string, unknown>): Promise<{
+        hash: string;
+        txBlob?: string;
+        signedTxBlob?: string;
+    }>;
+}
+
+export interface XrplClientSignedBindingConfig {
+    homeserverBaseUrl: string;
+    accessToken: string;
+    wallet: XrplClientSignedWalletAdapter;
+    network?: "xrpl" | "xahau";
+}
+
+export interface XrplClientSignedBindingResult {
+    did: Record<string, unknown>;
+    credential: Record<string, unknown>;
+}
+
+let bindingConfig: Partial<XrplClientSignedBindingConfig> = {};
+
+export function configureXrplClientSignedBinding(config: Partial<XrplClientSignedBindingConfig>): void {
+    bindingConfig = {
+        ...bindingConfig,
+        ...config,
+    };
+}
+
+export async function runClientSignedDidCredentialBinding(
+    e2eePubkeyCommitment: string,
+): Promise<XrplClientSignedBindingResult> {
+    const { homeserverBaseUrl, accessToken, wallet } = bindingConfig;
+    const network = bindingConfig.network ?? "xrpl";
+    if (!homeserverBaseUrl || !accessToken || !wallet) {
+        throw new Error("XRPL client-signed binding is not configured");
+    }
+
+    const xrplAddress = await wallet.getAddress();
+    const didPrepare = await postJson(homeserverBaseUrl, accessToken, "/_matrix/client/v3/did/prepare", {
+        xrpl_address: xrplAddress,
+        network,
+        e2ee_pubkey_commitment: e2eePubkeyCommitment,
+    });
+    const didSignResult = await wallet.signAndSubmit(asObject(didPrepare.unsigned_tx, "did unsigned_tx"));
+    const didTxBlob = didSignResult.txBlob ?? didSignResult.signedTxBlob;
+    if (!didTxBlob) {
+        throw new Error("Wallet adapter must return txBlob/signedTxBlob for DID finalize");
+    }
+    const didFinalize = await postJson(homeserverBaseUrl, accessToken, "/_matrix/client/v3/did/finalize", {
+        xrpl_address: xrplAddress,
+        network,
+        session: didPrepare.session,
+        tx_blob: didTxBlob,
+        tx_hash: didSignResult.hash,
+    });
+
+    const credentialPrepare = await postJson(homeserverBaseUrl, accessToken, "/_matrix/client/v3/credential/prepare", {
+        xrpl_address: xrplAddress,
+        network,
+        e2ee_pubkey_commitment: e2eePubkeyCommitment,
+    });
+    const credentialSignResult = await wallet.signAndSubmit(
+        asObject(credentialPrepare.unsigned_tx, "credential unsigned_tx"),
+    );
+    const credentialTxBlob = credentialSignResult.txBlob ?? credentialSignResult.signedTxBlob;
+    if (!credentialTxBlob) {
+        throw new Error("Wallet adapter must return txBlob/signedTxBlob for credential finalize");
+    }
+    const credentialFinalize = await postJson(
+        homeserverBaseUrl,
+        accessToken,
+        "/_matrix/client/v3/credential/finalize",
+        {
+            xrpl_address: xrplAddress,
+            network,
+            session: credentialPrepare.session,
+            tx_blob: credentialTxBlob,
+            tx_hash: credentialSignResult.hash,
+        },
+    );
+
+    logger.info("Completed client-signed DID/Credential binding for %s", xrplAddress);
+    return {
+        did: didFinalize,
+        credential: credentialFinalize,
+    };
+}
+
+function asObject(value: unknown, name: string): Record<string, unknown> {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid ${name} payload from homeserver`);
+    }
+    return value as Record<string, unknown>;
+}
+
+async function postJson(
+    homeserverBaseUrl: string,
+    accessToken: string,
+    path: string,
+    body: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+    const response = await fetch(`${homeserverBaseUrl.replace(/\/+$/, "")}${path}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!response.ok) {
+        const message = typeof payload.error === "string" ? payload.error : `HTTP ${response.status}`;
+        throw new Error(`XRPL client-signed request failed (${path}): ${message}`);
+    }
+    return payload;
+}