@opaquecash/stellar 0.1.0

package/dist/crypto/index.d.ts

@@ -0,0 +1,345 @@
+import { Keypair } from '@stellar/stellar-sdk';
+export { B as BN254_R, D as DerivedDeposit, a as POOL_TREE_DEPTH, P as PoolNote, d as deriveDeposit, g as getPoseidon, h as hashFields, n as newNoteSecrets, r as randomFieldElement, u as unspentTotal } from '../notes-CTR_oi8Y.js';
+
+/**
+ * Byte and hex helpers shared across the crypto layer.
+ *
+ * These are intentionally dependency-free and isomorphic (Node + browser).
+ */
+/** Parse a hex string (with or without `0x`) into bytes. */
+declare function hexToBytes(hex: string): Uint8Array;
+/** Encode bytes as a lowercase hex string (no `0x` prefix). */
+declare function bytesToHex(b: Uint8Array): string;
+/** Interpret bytes as a big-endian unsigned integer. */
+declare function bytesToBigInt(b: Uint8Array): bigint;
+/** Encode a bigint as a fixed 32-byte big-endian array. */
+declare function bigIntToBytes32(value: bigint): Uint8Array;
+/** bigint -> 0x-prefixed 32-byte big-endian hex. */
+declare function toHex32(v: bigint): string;
+/** Concatenate byte arrays into one. */
+declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
+
+/**
+ * String-based decimal parsing for XLM amounts to avoid floating-point precision
+ * issues. XLM uses 7 decimal places (1 XLM = 10^7 stroops).
+ */
+/**
+ * Parse an XLM string into stroops. Enforces at most 7 decimal places and
+ * rejects malformed input.
+ *
+ * @throws if the input is empty, non-numeric, or has more than 7 decimals.
+ */
+declare function parseXlmToStroops(xlmString: string): bigint;
+/**
+ * Parse a Horizon balance string into stroops. Returns 0 for empty or malformed
+ * input (defensive against unexpected API responses).
+ */
+declare function parseHorizonBalanceToStroops(balanceString: string | undefined): bigint;
+/** Format stroops as an XLM string with trailing zeros removed. */
+declare function formatStroopsToXlm(stroops: bigint): string;
+/** Alias for {@link formatStroopsToXlm}. */
+declare const formatXlm: typeof formatStroopsToXlm;
+
+/**
+ * Dual-Key Stealth Address Protocol (DKSAP) — client-side crypto.
+ *
+ * Senders derive a one-time stealth address from a recipient's meta-address
+ * (viewing + spending public keys). Recipients use their viewing key to detect
+ * incoming transfers (view-tag prefilter) and their spending key to reconstruct
+ * the one-time private key and sweep.
+ *
+ * Uses @noble/curves secp256k1 and is byte-compatible with the Rust WASM scanner.
+ *
+ * Stellar adaptation: scanning matches on the 20-byte Keccak "stealth id"; funds
+ * are held on a deterministic Ed25519 Stellar account derived from the stealth
+ * secp256k1 point.
+ */
+
+/** 0x-prefixed hex string. */
+type Hex = `0x${string}`;
+type DomainSeparationOpts = {
+    origin: string;
+    networkPassphrase: string;
+    walletPublicKey: string;
+    purpose: string;
+};
+/**
+ * Build the human-readable, domain-separated message a wallet signs to derive
+ * its Opaque stealth keys. Signing it is not a transaction and moves no funds.
+ */
+declare function buildDomainSeparatedMessage(opts: DomainSeparationOpts): string;
+declare const LEGACY_SETUP_MESSAGE = "Sign this message to derive your Opaque Cash stealth keys on Stellar. This is not a transaction and does not move funds.";
+/**
+ * Derive viewing key (v) and spending key (s) from a wallet signature used as
+ * entropy. Expands the signature into 64 bytes via HKDF-SHA256, then splits into
+ * two 32-byte private keys. Domain string is "opaque-cash-v1".
+ */
+declare function deriveKeysFromSignature(signatureHex: Hex | string): {
+    viewingKey: Uint8Array;
+    spendingKey: Uint8Array;
+};
+/**
+ * Build the stealth meta-address from viewing and spending private keys.
+ * Meta-address = compressed(V) || compressed(S) (66 bytes).
+ */
+declare function keysToStealthMetaAddress(viewingKey: Uint8Array, spendingKey: Uint8Array): {
+    V: Uint8Array;
+    S: Uint8Array;
+    metaAddress: Uint8Array;
+};
+/** Encode the 66-byte stealth meta-address as 0x-prefixed hex. */
+declare function stealthMetaAddressToHex(metaAddress: Uint8Array): Hex;
+/**
+ * Parse a recipient stealth meta-address into viewing and spending public keys.
+ * Format: first 33 bytes = compressed viewing key V, next 33 = compressed S.
+ */
+declare function parseStealthMetaAddress(metaHex: Hex | string): {
+    viewPubKey: Uint8Array;
+    spendPubKey: Uint8Array;
+};
+/**
+ * Sender-side: compute a one-time stealth address and view tag for a recipient
+ * meta-address. Generates a fresh ephemeral key per call.
+ */
+declare function computeStealthAddressAndViewTag(recipientMetaAddressHex: Hex | string): {
+    ephemeralPriv: Uint8Array;
+    ephemeralPubKey: Uint8Array;
+    stealthAddress: string;
+    stealthStellarAddress: string;
+    viewTag: number;
+    metadata: Uint8Array;
+};
+/**
+ * Rebuild announce() parameters for a manual ghost receive using a stored
+ * ephemeral private key (deterministic re-derivation of a prior send).
+ */
+declare function buildGhostAnnouncementPayload(recipientMetaAddressHex: Hex | string, ephemeralPrivKeyHex: Hex | string): {
+    stealthAddress: string;
+    ephemeralPubKey: Uint8Array;
+    metadata: Uint8Array;
+    viewTag: number;
+};
+/**
+ * Recipient-side: recompute the DKSAP shared-secret hash and view tag from the
+ * sender's ephemeral public key and the recipient's viewing key. Mirrors the
+ * sender computation via ECDH symmetry (viewPriv·EphPub == ephPriv·ViewPub).
+ */
+declare function recipientSharedSecretHash(viewingKey: Uint8Array, ephemeralPubKey: Uint8Array): {
+    sH: Uint8Array;
+    viewTag: number;
+};
+/**
+ * Cheap recipient-side prefilter: does this announcement's view tag match?
+ * Lets a recipient skip the expensive point math for non-matching transfers.
+ */
+declare function checkViewTagMatch(opts: {
+    viewingKey: Uint8Array;
+    ephemeralPubKey: Uint8Array;
+    viewTag: number;
+}): boolean;
+/**
+ * Recipient-side: reconstruct the one-time stealth private key for a transfer.
+ * stealthPriv = (spendingKey + sH) mod n, where sH = keccak(viewPriv·EphPub).
+ * The returned key controls the same secp256k1 point the sender derived, hence
+ * the same deterministic Stellar account.
+ */
+declare function reconstructStealthPrivateKey(opts: {
+    viewingKey: Uint8Array;
+    spendingKey: Uint8Array;
+    ephemeralPubKey: Uint8Array;
+}): Uint8Array;
+/** Deterministic ephemeral scalar for the "Announcer" stealth signer. */
+declare function deriveAnnouncerEphemeralKey(metaAddressHex: Hex | string): Uint8Array;
+/** Derive the deterministic Ed25519 Stellar keypair from a stealth secp256k1 point. */
+declare function deriveStealthStellarKeypair(stealthPubKeyUncompressed: Uint8Array): Keypair;
+/** Derive the deterministic Stellar G-address from a stealth secp256k1 point. */
+declare function deriveStealthStellarAddress(stealthPubKeyUncompressed: Uint8Array): string;
+/**
+ * Recompute the 20-byte EVM-style stealth id (`0x` + 40 hex) from a stealth
+ * private key. Used to confirm a view-tag match against an announcement.
+ */
+declare function stealthIdFromPrivateKey(stealthPrivKey: Uint8Array): string;
+/** Derive the deterministic Stellar G-address from a stealth private key. */
+declare function deriveStealthStellarAddressFromStealthPrivKey(stealthPrivKey: Uint8Array): string;
+/** Derive the deterministic Stellar keypair from a stealth private key. */
+declare function deriveStealthStellarKeypairFromStealthPrivKey(stealthPrivKey: Uint8Array): Keypair;
+
+interface StealthAnnouncement {
+    /** 20-byte EVM-style stealth id (`0x` + 40 hex). */
+    stealthAddress: string;
+    /** Sender's compressed ephemeral public key (33 bytes). */
+    ephemeralPubKey: Uint8Array;
+    /** View tag byte from the announcement metadata. */
+    viewTag: number;
+}
+interface ScanMatch {
+    announcement: StealthAnnouncement;
+    /** Reconstructed one-time stealth private key (32 bytes). */
+    stealthPrivKey: Uint8Array;
+    /** Deterministic Stellar account holding the funds. */
+    stealthStellarAddress: string;
+}
+/**
+ * Scan announcements for transfers to the recipient. Each candidate is
+ * view-tag prefiltered, then confirmed by reconstructing the one-time key and
+ * checking its stealth id equals the announced one (so a coincidental tag match
+ * is rejected).
+ */
+declare function scanAnnouncements(opts: {
+    announcements: StealthAnnouncement[];
+    viewingKey: Uint8Array;
+    spendingKey: Uint8Array;
+}): ScanMatch[];
+
+/**
+ * Schema field primitives shared by the schema codec and the schema service.
+ */
+type FieldType = "bool" | "u8" | "u16" | "u32" | "u64" | "string" | "pubkey";
+interface FieldDef {
+    /** Stable ordinal id (index in declaration order). */
+    id: string;
+    name: string;
+    type: FieldType;
+}
+
+/**
+ * Canonical schema / attestation encoding. Mirrors the `opaque-schema-core`
+ * crate and the Soroban schema/attestation contracts byte-for-byte.
+ */
+
+declare const MAX_FIELDS = 16;
+declare const MAX_FIELD_NAME_LEN = 32;
+declare const MAX_STRING_VALUE_LEN = 128;
+declare const MAX_ATTESTATION_DATA_LEN = 512;
+declare class SchemaParseError extends Error {
+    constructor(message: string);
+}
+declare class AttestationDataError extends Error {
+    constructor(message: string);
+}
+/** Parse and validate `"type name"` comma-separated field definitions. */
+declare function parseFieldDefinitions(fieldDefs: string): FieldDef[];
+declare function fieldDefsToCanonicalString(fields: FieldDef[]): string;
+declare function encodeCanonicalFieldDefs(fields: FieldDef[]): Uint8Array;
+declare function addressToAuthorityBytes(address: string): Uint8Array;
+/** Compute a schema id (SHA-256 of authority || name || version || canonical defs). */
+declare function computeSchemaIdFromBytes(authorityBytes: Uint8Array, name: string, fieldDefinitions: string, version?: number): Promise<Uint8Array>;
+declare function computeSchemaId(authority: string, name: string, fieldDefinitions: string, version?: number): Promise<Uint8Array>;
+/** Encode attestation payload bytes in schema field order. */
+declare function encodeAttestationData(fieldValues: Record<string, string>, fieldDefs: FieldDef[]): Uint8Array;
+/** Decode canonical attestation bytes into a field-value map. */
+declare function decodeAttestationData(data: Uint8Array, fieldDefs: FieldDef[]): Record<string, string>;
+
+/**
+ * Encrypted backup of stealth ephemeral private keys ("ghost entries").
+ * PBKDF2-SHA256 key derivation + AES-256-GCM, using the Web Crypto API
+ * (available in browsers and Node 18+).
+ *
+ * Threat model: protects key material at rest against read-only exfiltration of
+ * stored backups. It does NOT protect against capture of the password at entry
+ * time, runtime memory inspection while decrypted, or a fully compromised host.
+ */
+type GhostEntryLike = {
+    cluster: string;
+    stealthAddress: string;
+    ephemeralPrivKeyHex?: string;
+    createdAt: number;
+};
+type EncryptedGhostPayload = {
+    version: 1;
+    salt: string;
+    entries: Array<{
+        cluster: string;
+        stealthAddress: string;
+        ephemeralPrivKeyEncrypted?: string;
+        createdAt: number;
+    }>;
+};
+/**
+ * Encrypt ghost entries. Only `ephemeralPrivKeyHex` is encrypted; metadata
+ * (cluster, stealth address, timestamp) stays readable.
+ */
+declare function encryptGhostEntries(entries: GhostEntryLike[], password: string): Promise<EncryptedGhostPayload>;
+/** Decrypt ghost entries produced by {@link encryptGhostEntries}. */
+declare function decryptGhostEntries(payload: EncryptedGhostPayload, password: string): Promise<GhostEntryLike[]>;
+/** Export ghost entries as an encrypted JSON string. */
+declare function exportEncryptedBackup(entries: GhostEntryLike[], password: string): Promise<string>;
+/** Import ghost entries from an encrypted backup string. */
+declare function importEncryptedBackup(backupJson: string, password: string): Promise<GhostEntryLike[]>;
+
+/**
+ * Opaque payment-link format: `opaque://v{version}/{network}/{metaAddress}?{params}`
+ * with versioning, network binding, and optional SEP-compatible parameters.
+ */
+type Network = "testnet" | "mainnet" | "futurenet" | "local";
+interface PaymentLinkParams {
+    amount?: string;
+    asset?: string;
+    issuer?: string;
+    memo?: string;
+    sep?: string;
+    callback?: string;
+    label?: string;
+    expires?: string;
+}
+interface PaymentLink {
+    version: number;
+    network: Network;
+    metaAddress: string;
+    params: PaymentLinkParams;
+}
+interface PaymentLinkError {
+    type: "INVALID_FORMAT" | "UNSUPPORTED_VERSION" | "NETWORK_MISMATCH" | "INVALID_META_ADDRESS" | "INVALID_PARAMETER";
+    message: string;
+    details?: unknown;
+}
+/** Validate a DKSAP meta-address: `0x` + 132 hex chars (66 bytes). */
+declare function isValidMetaAddress(metaAddress: string): boolean;
+declare function isValidNetwork(network: string): network is Network;
+/** Validate a Stellar public key (G..., 56 chars, base32). */
+declare function isValidStellarPublicKey(publicKey: string): boolean;
+declare function isValidAssetCode(assetCode: string): boolean;
+declare function isValidAmount(amount: string): boolean;
+declare function isValidIso8601(timestamp: string): boolean;
+declare function isValidUrl(url: string): boolean;
+/** Encode a payment link from components. Throws on invalid input. */
+declare function encodePaymentLink(link: PaymentLink): string;
+/** Decode a payment-link string into components, or a structured error. */
+declare function decodePaymentLink(linkString: string, configuredNetwork?: Network): {
+    link: PaymentLink;
+} | {
+    error: PaymentLinkError;
+};
+/** Create a v1 payment link from a meta-address and network. */
+declare function createPaymentLink(metaAddress: string, network: Network, params?: PaymentLinkParams): string;
+/** True when the string parses as a valid opaque payment link. */
+declare function isOpaquePaymentLink(linkString: string): boolean;
+/** Convert a legacy `https://host/pay/{metaAddress}` link into opaque format. */
+declare function convertLegacyLink(legacyLink: string, network: Network, params?: PaymentLinkParams): string | null;
+
+/**
+ * Destination memo risk + validation.
+ *
+ * Many Stellar custodians share one deposit address across users and rely on the
+ * transaction memo to disambiguate. Sending to such an address without a memo can
+ * lose funds. This module exposes a small allowlist of well-known custodial
+ * addresses and validators that match the Stellar memo spec.
+ */
+type MemoType = "none" | "text" | "id" | "hash" | "return";
+interface MemoRisk {
+    isKnownCustodian: boolean;
+    custodianName?: string;
+    recommendedMemoType?: MemoType;
+}
+/** Look up the memo risk for a destination. Safe for any input. */
+declare function memoRiskFor(destination: string | undefined | null): MemoRisk;
+interface MemoValidationResult {
+    ok: boolean;
+    error?: string;
+}
+/** Validate a memo value against the Stellar memo spec for the given type. */
+declare function validateMemo(memoType: MemoType, memo: string | undefined): MemoValidationResult;
+/** Warning copy for the inline banner, or null when no warning is needed. */
+declare function memoWarningCopy(risk: MemoRisk, memo: string | undefined): string | null;
+
+export { AttestationDataError, type DomainSeparationOpts, type EncryptedGhostPayload, type FieldDef, type FieldType, type GhostEntryLike, type Hex, LEGACY_SETUP_MESSAGE, MAX_ATTESTATION_DATA_LEN, MAX_FIELDS, MAX_FIELD_NAME_LEN, MAX_STRING_VALUE_LEN, type MemoRisk, type MemoType, type MemoValidationResult, type Network, type PaymentLink, type PaymentLinkError, type PaymentLinkParams, type ScanMatch, SchemaParseError, type StealthAnnouncement, addressToAuthorityBytes, bigIntToBytes32, buildDomainSeparatedMessage, buildGhostAnnouncementPayload, bytesToBigInt, bytesToHex, checkViewTagMatch, computeSchemaId, computeSchemaIdFromBytes, computeStealthAddressAndViewTag, concatBytes, convertLegacyLink, createPaymentLink, decodeAttestationData, decodePaymentLink, decryptGhostEntries, deriveAnnouncerEphemeralKey, deriveKeysFromSignature, deriveStealthStellarAddress, deriveStealthStellarAddressFromStealthPrivKey, deriveStealthStellarKeypair, deriveStealthStellarKeypairFromStealthPrivKey, encodeAttestationData, encodeCanonicalFieldDefs, encodePaymentLink, encryptGhostEntries, exportEncryptedBackup, fieldDefsToCanonicalString, formatStroopsToXlm, formatXlm, hexToBytes, importEncryptedBackup, isOpaquePaymentLink, isValidAmount, isValidAssetCode, isValidIso8601, isValidMetaAddress, isValidNetwork, isValidStellarPublicKey, isValidUrl, keysToStealthMetaAddress, memoRiskFor, memoWarningCopy, parseFieldDefinitions, parseHorizonBalanceToStroops, parseStealthMetaAddress, parseXlmToStroops, recipientSharedSecretHash, reconstructStealthPrivateKey, scanAnnouncements, stealthIdFromPrivateKey, stealthMetaAddressToHex, toHex32, validateMemo };