@yallet/rwa-sdk 0.2.0

package/src/credential-nft-server.ts

@@ -0,0 +1,201 @@
+/**
+ * Yault credential NFT — server-side mint flow.
+ *
+ * Encrypts credential payload locally with recipient's xidentity, then POSTs
+ * to upload-and-mint API. No registry, signer, or client-side mint needed.
+ */
+
+import { AssetType } from './types.js';
+import { ECIESEncryptor } from './encryption.js';
+import { encryptAsset } from './encryption.js';
+
+/** Payload shape agreed with Yault webapp */
+export interface CredentialNftPayload {
+  user_cred: string;
+  mnemonic?: string | null;
+  index: number;
+  label: string;
+  /** Optional memo (e.g. "letter to future heirs") — encrypted together with credential, delivered when release triggers. */
+  memo?: string | null;
+}
+
+/** Result shape expected by Yault */
+export interface CredentialMintResult {
+  success: boolean;
+  txId?: string;
+  error?: string;
+}
+
+/** Options for server-side mint */
+export interface MintCredentialNftViaServerOptions {
+  /** Recipient's xidentity (base64). Required. */
+  xidentity: string;
+  /** Upload-and-mint API URL. If omitted, uses built-in prod/dev endpoint. */
+  uploadAndMintApiUrl?: string;
+  /** When true, uses built-in dev endpoint (if uploadAndMintApiUrl not set). */
+  dev?: boolean;
+  /** Optional: custom headers (e.g. Authorization) for the API request */
+  headers?: Record<string, string>;
+  /** Network for mint (mainnet | devnet). Default: mainnet */
+  network?: 'mainnet' | 'devnet';
+}
+
+/** Options for preparing payload only (no POST). Same as MintCredentialNftViaServerOptions minus upload/headers. */
+export interface PrepareCredentialNftPayloadOptions {
+  /** Recipient's xidentity (base64). Required. */
+  xidentity: string;
+  /** Network for mint (mainnet | devnet). Default: mainnet */
+  network?: 'mainnet' | 'devnet';
+}
+
+/** Result of prepareCredentialNftPayload: the exact body to POST to upload-and-mint later. */
+export interface PreparedCredentialNftPayload {
+  /** Request body to POST to upload-and-mint API (data, contentType, tags, leafOwner, name, description, network). */
+  body: Record<string, unknown>;
+  /** Recipient Solana address (leafOwner). */
+  recipientSolanaAddress: string;
+}
+
+/** Built-in endpoints for upload-and-mint API */
+export const RWA_UPLOAD_AND_MINT_ENDPOINTS = {
+  prod: 'https://api.yallet.xyz/api/v1/storage/rwa/upload-and-mint',
+  dev: 'https://api.yallet.xyz/api/v1/storage/rwa/upload-and-mint',
+} as const;
+
+const NOTE_TITLE = 'Yault Release Credentials';
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Build the same upload-and-mint request body as mintCredentialNftViaServer, without sending.
+ * Used to store the encrypted note server-side (e.g. Oracle binding) and send only after attestation.
+ *
+ * @param recipientSolanaAddress - Recipient's Solana address (leafOwner)
+ * @param payload - { user_cred, mnemonic?, index, label }
+ * @param options - { xidentity, network? }
+ * @returns { body, recipientSolanaAddress } — body is the exact JSON to POST to upload-and-mint later
+ */
+export async function prepareCredentialNftPayload(
+  recipientSolanaAddress: string,
+  payload: CredentialNftPayload,
+  options: PrepareCredentialNftPayloadOptions
+): Promise<PreparedCredentialNftPayload> {
+  const { xidentity, network = 'mainnet' } = options;
+
+  if (!xidentity || !xidentity.trim()) {
+    throw new Error('xidentity is required');
+  }
+
+  const note = {
+    title: NOTE_TITLE,
+    content: JSON.stringify(payload),
+    metadata: { createdAt: new Date().toISOString() },
+  };
+
+  const name = `${NOTE_TITLE} — ${payload.label}`;
+  const description = `Path index ${payload.index}. Decrypt in Yallet to view credentials.`;
+
+  const encryptor = new ECIESEncryptor();
+  const encrypted = await encryptAsset(note, AssetType.NOTE, xidentity.trim(), encryptor);
+
+  const payloadForStorage = {
+    encrypted: {
+      ephemeral_pub: encrypted.ephemeral_pub,
+      encrypted_aes_key: encrypted.encrypted_aes_key,
+      iv: encrypted.iv,
+      encrypted_data: encrypted.encrypted_data,
+    },
+    metadata: {
+      assetType: AssetType.NOTE,
+      direction: 'received' as const,
+      network,
+      version: encrypted.version,
+      uuid: encrypted.uuid,
+      timestamp: encrypted.timestamp,
+      dataSize: encrypted.dataSize,
+      uploadedAt: Date.now(),
+    },
+  };
+
+  const jsonString = JSON.stringify(payloadForStorage);
+  const dataBase64 = bytesToBase64(new TextEncoder().encode(jsonString));
+
+  const body: Record<string, unknown> = {
+    data: dataBase64,
+    contentType: 'application/json',
+    tags: { 'Yallet-Type': 'encrypted-asset', 'Asset-Type': AssetType.NOTE, 'Direction': 'received' },
+    leafOwner: recipientSolanaAddress,
+    name,
+    description,
+    network,
+  };
+
+  return { body, recipientSolanaAddress };
+}
+
+/**
+ * Mint credential payload via server (upload-and-mint API).
+ *
+ * Caller provides xidentity from recipient-addresses. No registry or signer.
+ *
+ * @param recipientSolanaAddress - Recipient's Solana address (leafOwner)
+ * @param payload - { user_cred, mnemonic?, index, label }
+ * @param options - { xidentity, uploadAndMintApiUrl?, dev?, headers?, network? }
+ * @returns { success, txId?, error? }
+ */
+export async function mintCredentialNftViaServer(
+  recipientSolanaAddress: string,
+  payload: CredentialNftPayload,
+  options: MintCredentialNftViaServerOptions
+): Promise<CredentialMintResult> {
+  const { xidentity, uploadAndMintApiUrl, dev = false, headers = {}, network = 'mainnet' } = options;
+
+  if (!xidentity || !xidentity.trim()) {
+    return { success: false, error: 'xidentity is required' };
+  }
+
+  const apiUrl =
+    uploadAndMintApiUrl ||
+    (dev ? RWA_UPLOAD_AND_MINT_ENDPOINTS.dev : RWA_UPLOAD_AND_MINT_ENDPOINTS.prod);
+
+  const { body } = await prepareCredentialNftPayload(recipientSolanaAddress, payload, { xidentity, network });
+
+  try {
+    const response = await fetch(apiUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+
+    const result = (await response.json().catch(() => ({}))) as {
+      success?: boolean;
+      mint?: { signature?: string };
+      error?: string;
+    };
+
+    if (!response.ok) {
+      return {
+        success: false,
+        error: result?.error || response.statusText || 'Upload-and-mint failed',
+      };
+    }
+
+    const signature = result?.mint?.signature;
+    return {
+      success: true,
+      txId: signature,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, error: message };
+  }
+}

package/src/credential-nft.ts

@@ -0,0 +1,64 @@
+/**
+ * Yault credential NFT — mint release credentials (user_cred + optional mnemonic)
+ * as an encrypted message cNFT to the recipient.
+ *
+ * Used by Yault webapp after Plan submit: custody WASM generates credentials,
+ * this function mints them to the recipient's Solana address via RWA SDK mintMessage.
+ */
+
+import type { YalletRWASDK } from './sdk.js';
+import type { MintResult } from './types.js';
+
+/** Payload shape agreed with Yault webapp (mnemonic optional until path design includes it). */
+export interface CredentialNftPayload {
+  user_cred: string;
+  mnemonic?: string | null;
+  index: number;
+  label: string;
+}
+
+/** Result shape expected by Yault: success, txId (assetId or signature), error. */
+export interface CredentialMintResult {
+  success: boolean;
+  txId?: string;
+  error?: string;
+}
+
+const NOTE_TITLE = 'Yault Release Credentials';
+
+/**
+ * Mint credential payload as an encrypted note cNFT to the recipient.
+ *
+ * @param sdk - Initialized YalletRWASDK (config, signer, registry set)
+ * @param recipientSolanaAddress - Recipient's Solana address (must be registered in SDK registry with xidentity)
+ * @param payload - { user_cred, mnemonic?, index, label }
+ * @returns { success, txId?, error? } for Yault UI
+ */
+export async function mintCredentialNft(
+  sdk: YalletRWASDK,
+  recipientSolanaAddress: string,
+  payload: CredentialNftPayload
+): Promise<CredentialMintResult> {
+  const note = {
+    title: NOTE_TITLE,
+    content: JSON.stringify(payload),
+    metadata: { createdAt: new Date().toISOString() },
+  };
+
+  const result: MintResult = await sdk.mintMessage(note, recipientSolanaAddress, {
+    name: `${NOTE_TITLE} — ${payload.label}`,
+    description: `Path index ${payload.index}. Decrypt in Yallet to view credentials.`,
+  });
+
+  if (result.success) {
+    return {
+      success: true,
+      txId: result.assetId ?? result.signature ?? undefined,
+    };
+  }
+
+  return {
+    success: false,
+    error: result.error ?? 'Mint failed',
+  };
+}

package/src/encryption.ts

@@ -0,0 +1,308 @@
+/**
+ * Yallet RWA SDK - Encryption Module
+ *
+ * Provides ECIES encryption for RWA assets using xidentity public keys.
+ * Compatible with the Yallet WASM encryption module.
+ */
+
+import type {
+  AssetType,
+  AssetEnvelope,
+  EncryptedPayload,
+  EncryptFunction,
+} from './types.js';
+
+// ======================================
+//  Pure JavaScript ECIES Implementation
+// ======================================
+
+/**
+ * ECIES encryption using Web Crypto API.
+ * Must match dev.yallet.chrome-extension (acegf WASM) so the extension can decrypt:
+ *   dh_key = SHA256(shared_secret), encrypted_aes_key = AES-GCM(dh_key).encrypt(iv, aes_key), encrypted_data = AES-GCM(aes_key).encrypt(iv, plaintext).
+ */
+export class ECIESEncryptor {
+  /**
+   * Encrypt data for a recipient's xidentity public key.
+   * Scheme (same as acegf encrypt): ECDH → SHA256(dh) = master_key → AES-GCM(master_key).encrypt(iv, random_aes_key) → AES-GCM(aes_key).encrypt(iv, plaintext).
+   *
+   * @param recipientXidentityB64 - Recipient's X25519 public key (base64)
+   * @param plaintext - Data to encrypt
+   * @returns Encrypted payload
+   */
+  async encrypt(
+    recipientXidentityB64: string,
+    plaintext: Uint8Array
+  ): Promise<EncryptedPayload> {
+    const recipientPubKey = base64ToBytes(recipientXidentityB64);
+
+    const ephemeralKeyPair = (await crypto.subtle.generateKey(
+      { name: 'X25519' },
+      true,
+      ['deriveBits']
+    )) as CryptoKeyPair;
+
+    const ephemeralPubKeyRaw = await crypto.subtle.exportKey(
+      'raw',
+      ephemeralKeyPair.publicKey
+    );
+    const ephemeralPubKey = new Uint8Array(ephemeralPubKeyRaw);
+
+    const recipientKey = await crypto.subtle.importKey(
+      'raw',
+      recipientPubKey as BufferSource,
+      { name: 'X25519' },
+      false,
+      []
+    );
+
+    const sharedSecretRaw = await crypto.subtle.deriveBits(
+      { name: 'X25519', public: recipientKey },
+      ephemeralKeyPair.privateKey,
+      256
+    );
+    const sharedSecret = new Uint8Array(sharedSecretRaw);
+
+    // Match extension WASM: dh_key = SHA256(shared_secret), then AES-GCM(dh_key) encrypts the random AES key
+    const dhKeyHash = await crypto.subtle.digest('SHA-256', sharedSecret);
+    const dhKey = new Uint8Array(dhKeyHash);
+
+    const masterKey = await crypto.subtle.importKey(
+      'raw',
+      dhKey,
+      { name: 'AES-GCM' },
+      false,
+      ['encrypt']
+    );
+
+    const aesKeyBytes = crypto.getRandomValues(new Uint8Array(32));
+    const aesKey = await crypto.subtle.importKey(
+      'raw',
+      aesKeyBytes,
+      { name: 'AES-GCM' },
+      false,
+      ['encrypt']
+    );
+
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+
+    const encryptedAesKeyRaw = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      masterKey,
+      aesKeyBytes
+    );
+    const encryptedAesKey = new Uint8Array(encryptedAesKeyRaw);
+
+    const encryptedDataRaw = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      aesKey,
+      plaintext as BufferSource
+    );
+    const encryptedData = new Uint8Array(encryptedDataRaw);
+
+    return {
+      ephemeral_pub: bytesToBase64(ephemeralPubKey),
+      encrypted_aes_key: bytesToBase64(encryptedAesKey),
+      iv: bytesToBase64(iv),
+      encrypted_data: bytesToBase64(encryptedData),
+    };
+  }
+}
+
+// ======================================
+//  WASM-Compatible Encryption Wrapper
+// ======================================
+
+/**
+ * Wrapper for WASM encrypt function
+ *
+ * Use this when you have access to the Yallet WASM module
+ */
+export function createWasmEncryptor(wasmEncryptFn: EncryptFunction) {
+  return {
+    encrypt(
+      recipientXidentityB64: string,
+      plaintext: Uint8Array
+    ): EncryptedPayload {
+      const result = wasmEncryptFn(recipientXidentityB64, plaintext);
+
+      if (result.startsWith('error:')) {
+        throw new Error(`Encryption failed: ${result.substring(6)}`);
+      }
+
+      return JSON.parse(result) as EncryptedPayload;
+    },
+  };
+}
+
+/**
+ * Initialize acegf WASM and return the encrypt function for createRWASDK.
+ * Pass the default export of acegf.js (init) and optionally the wasm path/buffer.
+ *
+ * @example
+ * ```ts
+ * import init from './wasm/acegf.js';
+ * import { createAcegfEncryptor, createRWASDK } from '@yallet/rwa-sdk';
+ * const wasmEncryptFn = await createAcegfEncryptor(init, '/path/to/acegf_bg.wasm');
+ * const sdk = createRWASDK(config, { wasmEncryptFn });
+ * ```
+ */
+export async function createAcegfEncryptor(
+  initFn: (
+    moduleOrPath?: string | URL | ArrayBuffer | object
+  ) => Promise<{ acegf_encrypt_for_xidentity: EncryptFunction }>,
+  wasmModuleOrPath?: string | URL | ArrayBuffer | object
+): Promise<EncryptFunction> {
+  const acegf = await initFn(wasmModuleOrPath);
+  return acegf.acegf_encrypt_for_xidentity;
+}
+
+// ======================================
+//  Asset Preparation
+// ======================================
+
+/**
+ * Generate a UUID v4
+ */
+function generateUUID(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  // Fallback for environments without crypto.randomUUID
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Options for preparing asset data
+ */
+export interface PrepareAssetOptions {
+  /** Custom UUID (auto-generated if not provided) */
+  uuid?: string;
+  /** Custom timestamp (current time if not provided) */
+  timestamp?: number;
+  /** Schema identifier */
+  schema?: string;
+  /** Previous token for version chain */
+  previousToken?: string;
+}
+
+/**
+ * Prepare asset data for encryption
+ *
+ * @param asset - Asset data object
+ * @param assetType - Type of asset
+ * @param options - Optional configuration
+ * @returns Object containing serialized data and metadata
+ */
+export function prepareAssetData(
+  asset: unknown,
+  assetType: AssetType,
+  options: PrepareAssetOptions = {}
+): { data: Uint8Array; uuid: string; timestamp: number } {
+  const uuid = options.uuid || generateUUID();
+  const timestamp = options.timestamp || Date.now();
+
+  const envelope: AssetEnvelope = {
+    version: 1,
+    type: assetType,
+    timestamp,
+    uuid,
+    schema: options.schema,
+    previousToken: options.previousToken,
+    data: asset,
+  };
+
+  const jsonString = JSON.stringify(envelope);
+  return {
+    data: new TextEncoder().encode(jsonString),
+    uuid,
+    timestamp,
+  };
+}
+
+/**
+ * Options for encrypting an asset
+ */
+export interface EncryptAssetOptions {
+  /** Custom UUID (auto-generated if not provided) */
+  uuid?: string;
+  /** Custom timestamp (current time if not provided) */
+  timestamp?: number;
+  /** Schema identifier */
+  schema?: string;
+  /** Previous token for version chain */
+  previousToken?: string;
+}
+
+/**
+ * Result of encrypting an asset
+ */
+export interface EncryptedAssetResult extends EncryptedPayload {
+  assetType: AssetType;
+  version: number;
+  uuid: string;
+  timestamp: number;
+  dataSize: number;
+}
+
+/**
+ * Encrypt an asset for a recipient
+ *
+ * @param asset - Asset data
+ * @param assetType - Type of asset
+ * @param recipientXidentity - Recipient's xidentity (base64)
+ * @param encryptor - Encryptor instance (WASM or JS)
+ * @param options - Optional configuration
+ * @returns Encrypted payload with metadata
+ */
+export async function encryptAsset(
+  asset: unknown,
+  assetType: AssetType,
+  recipientXidentity: string,
+  encryptor: ECIESEncryptor | ReturnType<typeof createWasmEncryptor>,
+  options: EncryptAssetOptions = {}
+): Promise<EncryptedAssetResult> {
+  const prepared = prepareAssetData(asset, assetType, options);
+
+  let encrypted: EncryptedPayload;
+
+  if (encryptor instanceof ECIESEncryptor) {
+    encrypted = await encryptor.encrypt(recipientXidentity, prepared.data);
+  } else {
+    encrypted = encryptor.encrypt(recipientXidentity, prepared.data);
+  }
+
+  return {
+    ...encrypted,
+    assetType,
+    version: 1,
+    uuid: prepared.uuid,
+    timestamp: prepared.timestamp,
+    dataSize: prepared.data.length,
+  };
+}
+
+// ======================================
+//  Utility Functions
+// ======================================
+
+function base64ToBytes(base64: string): Uint8Array {
+  const binaryString = atob(base64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binaryString = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binaryString += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binaryString);
+}