@textrp/briij-js-sdk 41.0.1 → 43.0.0

package/src/xrpl/identity.ts

@@ -0,0 +1,245 @@
+/*
+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 { Client as XrplClient, NFTokenMintFlags, type NFTokenMint } from "xrpl";
+
+import { sha256 } from "../digest.ts";
+import { logger } from "../logger.ts";
+
+const XRPL_IDENTITY_ACCOUNT_DATA_TYPE = "io.textrp.xrpl.identity_nft";
+const DEFAULT_XRPL_NETWORK = "testnet";
+const DEFAULT_XRPL_TESTNET_WS = "wss://s.altnet.rippletest.net:51233";
+const DEFAULT_XRPL_MAINNET_WS = "wss://s1.ripple.com";
+
+export interface XrplIdentityAccountData {
+    nftTokenId: string;
+    xrplAddress: string;
+    ipfsUri: string;
+    txHash: string;
+    mintedAt: string;
+}
+
+export interface XamanWalletAdapter {
+    getAddress(): Promise<string>;
+    signAndSubmit(tx: Record<string, unknown>): Promise<{ hash: string }>;
+}
+
+export interface XrplIdentityMintingConfig {
+    homeserverBaseUrl: string;
+    accessToken: string;
+    websocketUrl?: string;
+    network?: "mainnet" | "testnet";
+    xamanWallet: XamanWalletAdapter;
+    ipfsUriFactory?: (matrixUserId: string, xrplAddress: string) => Promise<string> | string;
+}
+
+export interface XrplIdentityMintResult extends XrplIdentityAccountData {
+    minted: boolean;
+}
+
+let mintingConfig: Partial<XrplIdentityMintingConfig> = {};
+
+export function configureXrplIdentityMinting(config: Partial<XrplIdentityMintingConfig>): void {
+    mintingConfig = {
+        ...mintingConfig,
+        ...config,
+    };
+}
+
+export function setXamanWalletForXrplIdentity(xamanWallet: XamanWalletAdapter): void {
+    mintingConfig = {
+        ...mintingConfig,
+        xamanWallet,
+    };
+}
+
+export async function mintSoulboundIdentityNFT(matrixUserId: string): Promise<XrplIdentityMintResult | null> {
+    const { homeserverBaseUrl, accessToken, xamanWallet } = mintingConfig;
+    if (!homeserverBaseUrl || !accessToken || !xamanWallet) {
+        logger.warn(
+            "Skipping XRPL identity mint for %s: missing homeserver auth and/or Xaman wallet adapter",
+            matrixUserId,
+        );
+        return null;
+    }
+
+    const existing = await getIdentityAccountData(homeserverBaseUrl, accessToken, matrixUserId);
+    if (existing?.nftTokenId && existing.xrplAddress) {
+        return {
+            ...existing,
+            minted: false,
+        };
+    }
+
+    const xrplAddress = await xamanWallet.getAddress();
+    const ipfsUri = await buildIpfsUri(matrixUserId, xrplAddress);
+    const encodedUri = toHex(ipfsUri);
+
+    const xrplClient = new XrplClient(resolveXrplWebSocketUrl());
+    await xrplClient.connect();
+
+    try {
+        const mintTransaction: NFTokenMint = {
+            TransactionType: "NFTokenMint",
+            Account: xrplAddress,
+            NFTokenTaxon: 0,
+            URI: encodedUri,
+            Flags: NFTokenMintFlags.tfMutable | NFTokenMintFlags.tfBurnable,
+        };
+
+        const autofilled = await xrplClient.autofill(mintTransaction);
+        const { hash: txHash } = await xamanWallet.signAndSubmit(autofilled as unknown as Record<string, unknown>);
+        const txResult = await xrplClient.request({
+            command: "tx",
+            transaction: txHash,
+        });
+
+        const nftTokenId =
+            extractNftTokenId(txResult.result?.meta) ??
+            (await findAccountNftByUri(xrplClient, xrplAddress, encodedUri));
+        if (!nftTokenId) {
+            throw new Error(`Unable to resolve NFTokenID for transaction ${txHash}`);
+        }
+
+        const accountData: XrplIdentityAccountData = {
+            nftTokenId,
+            xrplAddress,
+            ipfsUri,
+            txHash,
+            mintedAt: new Date().toISOString(),
+        };
+
+        await setIdentityAccountData(homeserverBaseUrl, accessToken, matrixUserId, accountData);
+
+        return {
+            ...accountData,
+            minted: true,
+        };
+    } finally {
+        await xrplClient.disconnect().catch(() => undefined);
+    }
+}
+
+async function buildIpfsUri(matrixUserId: string, xrplAddress: string): Promise<string> {
+    if (mintingConfig.ipfsUriFactory) {
+        return await mintingConfig.ipfsUriFactory(matrixUserId, xrplAddress);
+    }
+
+    const payload = JSON.stringify({ matrixUserId, xrplAddress });
+    const digest = await sha256(payload);
+    return `ipfs://textrp-briij/${toHex(digest).slice(0, 46)}`;
+}
+
+function resolveXrplWebSocketUrl(): string {
+    if (mintingConfig.websocketUrl) return mintingConfig.websocketUrl;
+    const network = mintingConfig.network ?? DEFAULT_XRPL_NETWORK;
+    return network === "mainnet" ? DEFAULT_XRPL_MAINNET_WS : DEFAULT_XRPL_TESTNET_WS;
+}
+
+function accountDataUrl(baseUrl: string, matrixUserId: string): string {
+    const trimmedBaseUrl = baseUrl.replace(/\/+$/, "");
+    return `${trimmedBaseUrl}/_matrix/client/v3/user/${encodeURIComponent(matrixUserId)}/account_data/${encodeURIComponent(XRPL_IDENTITY_ACCOUNT_DATA_TYPE)}`;
+}
+
+async function getIdentityAccountData(
+    homeserverBaseUrl: string,
+    accessToken: string,
+    matrixUserId: string,
+): Promise<XrplIdentityAccountData | null> {
+    const response = await fetch(accountDataUrl(homeserverBaseUrl, matrixUserId), {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+
+    if (response.status === 404) return null;
+    if (!response.ok) {
+        throw new Error(`Failed to read XRPL identity account_data: HTTP ${response.status}`);
+    }
+
+    return (await response.json()) as XrplIdentityAccountData;
+}
+
+async function setIdentityAccountData(
+    homeserverBaseUrl: string,
+    accessToken: string,
+    matrixUserId: string,
+    payload: XrplIdentityAccountData,
+): Promise<void> {
+    const response = await fetch(accountDataUrl(homeserverBaseUrl, matrixUserId), {
+        method: "PUT",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to persist XRPL identity account_data: HTTP ${response.status}`);
+    }
+}
+
+async function findAccountNftByUri(xrplClient: XrplClient, xrplAddress: string, encodedUri: string): Promise<string | null> {
+    const response = await xrplClient.request({
+        command: "account_nfts",
+        account: xrplAddress,
+    });
+
+    const targetUri = encodedUri.toUpperCase();
+    const nft = response.result?.account_nfts?.find((candidate: { URI?: string }) => {
+        return candidate.URI?.toUpperCase() === targetUri;
+    }) as { NFTokenID?: string } | undefined;
+
+    return nft?.NFTokenID ?? null;
+}
+
+function extractNftTokenId(meta: unknown): string | null {
+    if (!meta || typeof meta !== "object") return null;
+    const affectedNodes = (meta as { AffectedNodes?: unknown[] }).AffectedNodes ?? [];
+
+    for (const nodeWrapper of affectedNodes) {
+        if (!nodeWrapper || typeof nodeWrapper !== "object") continue;
+        const [nodeValue] = Object.values(nodeWrapper as Record<string, unknown>);
+        if (!nodeValue || typeof nodeValue !== "object") continue;
+
+        const newFields = (nodeValue as { NewFields?: unknown }).NewFields;
+        const finalFields = (nodeValue as { FinalFields?: unknown }).FinalFields;
+        const tokensContainer = [newFields, finalFields].find((container) => {
+            if (!container || typeof container !== "object") return false;
+            return Array.isArray((container as { NFTokens?: unknown[] }).NFTokens);
+        }) as { NFTokens?: unknown[] } | undefined;
+
+        const nftokens = tokensContainer?.NFTokens ?? [];
+        for (const tokenEntry of nftokens) {
+            if (!tokenEntry || typeof tokenEntry !== "object") continue;
+            const token = (tokenEntry as { NFToken?: { NFTokenID?: string } }).NFToken;
+            if (token?.NFTokenID) return token.NFTokenID;
+        }
+    }
+
+    return null;
+}
+
+function toHex(input: string | Uint8Array): string {
+    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    return Array.from(bytes)
+        .map((value) => value.toString(16).padStart(2, "0"))
+        .join("")
+        .toUpperCase();
+}

package/src/xrpl/trust.ts

@@ -0,0 +1,64 @@
+/*
+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.
+*/
+
+const DEFAULT_TRUST_PATH = "/_matrix/client/v3/org.textrp.xrpl/trust";
+
+export interface XrplTrustConfig {
+    homeserverBaseUrl: string;
+    accessToken: string;
+    trustPath?: string;
+}
+
+let xrplTrustConfig: Partial<XrplTrustConfig> = {};
+
+export function configureXrplTrust(config: Partial<XrplTrustConfig>): void {
+    xrplTrustConfig = {
+        ...xrplTrustConfig,
+        ...config,
+    };
+}
+
+export async function getTrustScore(payer: string, payee: string): Promise<number> {
+    const homeserverBaseUrl = xrplTrustConfig.homeserverBaseUrl;
+    const accessToken = xrplTrustConfig.accessToken;
+    if (!homeserverBaseUrl || !accessToken) {
+        throw new Error("XRPL trust config is incomplete");
+    }
+
+    const trimmedBaseUrl = homeserverBaseUrl.replace(/\/+$/, "");
+    const trustPath = xrplTrustConfig.trustPath ?? DEFAULT_TRUST_PATH;
+    const query = new URLSearchParams({
+        payer,
+        payee,
+    });
+    const response = await fetch(`${trimmedBaseUrl}${trustPath}?${query.toString()}`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to fetch trust score: HTTP ${response.status}`);
+    }
+
+    const payload = (await response.json()) as { score?: number; trusted?: boolean };
+    if (typeof payload.score === "number") {
+        return payload.score;
+    }
+    return payload.trusted ? 1 : 0;
+}

package/src/xrpl/verification.ts

@@ -0,0 +1,284 @@
+/*
+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 { Client as XrplClient, type SubmittableTransaction } from "xrpl";
+
+import { EventType } from "../@types/event.ts";
+import type { BriijClient } from "../client.ts";
+import { type XamanWalletAdapter, type XrplIdentityAccountData } from "./identity.ts";
+
+export const XRPL_VERIFY_REQUEST_EVENT: EventType.UserVerifyRequest = EventType.UserVerifyRequest;
+export const XRPL_VERIFY_ACCEPT_EVENT: EventType.UserVerifyAccept = EventType.UserVerifyAccept;
+export const XRPL_VERIFIED_EVENT: EventType.UserVerified = EventType.UserVerified;
+
+const NFT_TRUST_TAG = "nft_metadata";
+const XRPL_IDENTITY_ACCOUNT_DATA_TYPE = "io.textrp.xrpl.identity_nft";
+
+const DEFAULT_XRPL_NETWORK = "testnet";
+const DEFAULT_XRPL_TESTNET_WS = "wss://s.altnet.rippletest.net:51233";
+const DEFAULT_XRPL_MAINNET_WS = "wss://s1.ripple.com";
+
+export interface XrplVerificationConfig {
+    matrixClient: Pick<BriijClient, "sendEvent" | "getUserId" | "getAccessToken"> & { baseUrl: string };
+    xamanWallet: XamanWalletAdapter;
+    verificationRoomId?: string;
+    resolveVerificationRoomId?: (counterpartyXrplAddress: string) => Promise<string> | string;
+    pinJsonToIpfs?: (payload: Record<string, unknown>) => Promise<string>;
+    pinataJwt?: string;
+    websocketUrl?: string;
+    network?: "mainnet" | "testnet";
+}
+
+export interface XrplVerificationTxResult {
+    txHash: string;
+    credentialTypeHex: string;
+}
+
+let verificationConfig: Partial<XrplVerificationConfig> = {};
+
+export function configureXrplVerification(config: Partial<XrplVerificationConfig>): void {
+    verificationConfig = {
+        ...verificationConfig,
+        ...config,
+    };
+}
+
+export async function requestVerification(targetXrplAddress: string): Promise<XrplVerificationTxResult> {
+    const { matrixClient, xamanWallet } = verificationConfig;
+    if (!matrixClient || !xamanWallet) {
+        throw new Error("XRPL verification is not configured with matrixClient and xamanWallet");
+    }
+
+    const issuerXrplAddress = await xamanWallet.getAddress();
+    const roomId = await getVerificationRoomId(targetXrplAddress);
+    await matrixClient.sendEvent(roomId, XRPL_VERIFY_REQUEST_EVENT, {
+        tx_hash: "",
+        issuer_xrpl_address: issuerXrplAddress,
+        target_xrpl_address: targetXrplAddress,
+        trust_model: NFT_TRUST_TAG,
+    });
+
+    return {
+        txHash: "",
+        credentialTypeHex: NFT_TRUST_TAG,
+    };
+}
+
+export async function acceptVerification(issuerXrplAddress: string): Promise<XrplVerificationTxResult> {
+    const { matrixClient, xamanWallet } = verificationConfig;
+    if (!matrixClient || !xamanWallet) {
+        throw new Error("XRPL verification is not configured with matrixClient and xamanWallet");
+    }
+
+    const signerAddress = await xamanWallet.getAddress();
+    const identity = await getIdentityAccountData(matrixClient);
+    const metadata = await loadTrustMetadata(identity.ipfsUri);
+    const currentVerifiers = new Set(
+        Array.isArray(metadata.verifiers)
+            ? metadata.verifiers
+                  .filter((value): value is string => typeof value === "string" && Boolean(value.trim()))
+                  .map((value) => value.trim())
+            : [],
+    );
+    currentVerifiers.add(issuerXrplAddress);
+    const updatedUri = await pinTrustMetadata({
+        ...metadata,
+        verifiers: Array.from(currentVerifiers),
+    });
+
+    const roomId = await getVerificationRoomId(issuerXrplAddress);
+    const txHash = await signAndValidateOnXrpl(
+        {
+            TransactionType: "NFTokenModify",
+            Account: signerAddress,
+            NFTokenID: identity.nftTokenId,
+            URI: toHex(updatedUri),
+        },
+        async (xrplClient) => {
+            await assertAccountOwnsToken(xrplClient, signerAddress, identity.nftTokenId);
+        },
+    );
+
+    await matrixClient.sendEvent(roomId, XRPL_VERIFY_ACCEPT_EVENT, {
+        tx_hash: txHash,
+        issuer_xrpl_address: signerAddress,
+        accepter_xrpl_address: issuerXrplAddress,
+        nft_token_id: identity.nftTokenId,
+        ipfs_uri: updatedUri,
+        trust_model: NFT_TRUST_TAG,
+    });
+
+    return {
+        txHash,
+        credentialTypeHex: NFT_TRUST_TAG,
+    };
+}
+
+async function signAndValidateOnXrpl(
+    transaction: Record<string, unknown>,
+    preflight?: (xrplClient: XrplClient) => Promise<void>,
+): Promise<string> {
+    const { xamanWallet } = verificationConfig;
+    if (!xamanWallet) {
+        throw new Error("Missing Xaman wallet adapter");
+    }
+
+    const xrplClient = new XrplClient(resolveXrplWebSocketUrl());
+    await xrplClient.connect();
+
+    try {
+        if (preflight) {
+            await preflight(xrplClient);
+        }
+        const autofilled = await xrplClient.autofill(transaction as unknown as SubmittableTransaction);
+        const { hash: txHash } = await xamanWallet.signAndSubmit(autofilled as Record<string, unknown>);
+        await waitForValidation(xrplClient, txHash);
+        return txHash;
+    } finally {
+        await xrplClient.disconnect().catch(() => undefined);
+    }
+}
+
+async function waitForValidation(xrplClient: XrplClient, txHash: string): Promise<void> {
+    for (let attempt = 0; attempt < 15; attempt += 1) {
+        const response = await xrplClient.request({
+            command: "tx",
+            transaction: txHash,
+        });
+
+        if (response.result?.validated === true) return;
+        await sleep(1000);
+    }
+
+    throw new Error(`Timed out waiting for XRPL tx validation: ${txHash}`);
+}
+
+async function getVerificationRoomId(counterpartyXrplAddress: string): Promise<string> {
+    if (verificationConfig.verificationRoomId) {
+        return verificationConfig.verificationRoomId;
+    }
+    if (verificationConfig.resolveVerificationRoomId) {
+        return await verificationConfig.resolveVerificationRoomId(counterpartyXrplAddress);
+    }
+    throw new Error("No verification room configured");
+}
+
+function resolveXrplWebSocketUrl(): string {
+    if (verificationConfig.websocketUrl) return verificationConfig.websocketUrl;
+    const network = verificationConfig.network ?? DEFAULT_XRPL_NETWORK;
+    return network === "mainnet" ? DEFAULT_XRPL_MAINNET_WS : DEFAULT_XRPL_TESTNET_WS;
+}
+
+function toHex(input: string | Uint8Array): string {
+    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    return Array.from(bytes)
+        .map((value) => value.toString(16).padStart(2, "0"))
+        .join("")
+        .toUpperCase();
+}
+
+async function getIdentityAccountData(
+    matrixClient: Pick<BriijClient, "getUserId" | "getAccessToken"> & { baseUrl: string },
+): Promise<XrplIdentityAccountData> {
+    const userId = matrixClient.getUserId();
+    const accessToken = matrixClient.getAccessToken();
+    if (!userId || !accessToken) {
+        throw new Error("Missing Matrix session for XRPL verification");
+    }
+
+    const accountDataUrl =
+        `${matrixClient.baseUrl.replace(/\/+$/, "")}` +
+        `/_matrix/client/v3/user/${encodeURIComponent(userId)}/account_data/${encodeURIComponent(XRPL_IDENTITY_ACCOUNT_DATA_TYPE)}`;
+    const response = await fetch(accountDataUrl, {
+        method: "GET",
+        headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Unable to fetch identity NFT account_data: HTTP ${response.status}`);
+    }
+    return (await response.json()) as XrplIdentityAccountData;
+}
+
+async function assertAccountOwnsToken(xrplClient: XrplClient, account: string, tokenId: string): Promise<void> {
+    const response = await xrplClient.request({
+        command: "account_nfts",
+        account,
+    });
+    const found = response.result?.account_nfts?.some((entry: { NFTokenID?: string }) => entry.NFTokenID === tokenId);
+    if (!found) {
+        throw new Error(`Identity NFT ${tokenId} not found on account ${account}`);
+    }
+}
+
+async function loadTrustMetadata(uri: string): Promise<Record<string, unknown>> {
+    if (!uri) return {};
+    if (uri.startsWith("{")) {
+        return JSON.parse(uri) as Record<string, unknown>;
+    }
+
+    if (uri.startsWith("data:application/json,")) {
+        const payload = decodeURIComponent(uri.split(",", 2)[1] ?? "{}");
+        return JSON.parse(payload) as Record<string, unknown>;
+    }
+
+    if (uri.startsWith("ipfs://")) {
+        const cidPath = uri.replace("ipfs://", "");
+        const response = await fetch(`https://ipfs.io/ipfs/${cidPath}`);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch IPFS metadata: HTTP ${response.status}`);
+        }
+        return (await response.json()) as Record<string, unknown>;
+    }
+
+    return {};
+}
+
+async function pinTrustMetadata(payload: Record<string, unknown>): Promise<string> {
+    if (verificationConfig.pinJsonToIpfs) {
+        return await verificationConfig.pinJsonToIpfs(payload);
+    }
+
+    const jwt = verificationConfig.pinataJwt;
+    if (!jwt) {
+        throw new Error("Set pinJsonToIpfs or pinataJwt before acceptVerification()");
+    }
+
+    const response = await fetch("https://api.pinata.cloud/pinning/pinJSONToIPFS", {
+        method: "POST",
+        headers: {
+            "Authorization": `Bearer ${jwt}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ pinataContent: payload }),
+    });
+    if (!response.ok) {
+        throw new Error(`Pinata pin failed: HTTP ${response.status}`);
+    }
+    const body = (await response.json()) as { IpfsHash?: string };
+    if (!body.IpfsHash) {
+        throw new Error("Pinata response missing IpfsHash");
+    }
+    return `ipfs://${body.IpfsHash}`;
+}
+
+async function sleep(ms: number): Promise<void> {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}