@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/keys.d.ts

@@ -0,0 +1,467 @@
+/**
+ * Key Derivation for UTXOpia (Baby Jubjub + Ed25519)
+ *
+ * Dual-curve architecture (Railgun-style):
+ * - Baby Jubjub spending key: SNARK-friendly, in-circuit verification via BabyPbk()
+ * - Ed25519 viewing key: Standard fast curve, off-chain ECDH only
+ *
+ * Key Architecture:
+ * ```
+ * Solana Wallet (Ed25519)
+ *         │
+ *         │ signs message: "UTXOpia key derivation v1"
+ *         ▼
+ *    Signature (64 bytes)
+ *         │
+ *         ├──► SHA256(sig || "spend") mod BJJ_ORDER ──► Baby Jubjub Spending Key
+ *         │
+ *         └──► SHA256(sig || "view") ──► Ed25519 Viewing Key
+ * ```
+ *
+ * Stealth Address Flow:
+ * ```
+ * Sender:
+ *   1. ephemeral = random Ed25519 keypair
+ *   2. sharedSecret = X25519(ephemeral.priv, viewingPubX25519)
+ *   3. stealthScalar = SHA256(sharedSecret || domain) mod BJJ_ORDER
+ *   4. stealthPub = spendingPub + stealthScalar × BASE8
+ *   5. commitment = Poseidon(stealthPub.x, amount)
+ *
+ * Recipient (viewing key - can detect):
+ *   1. sharedSecret = X25519(viewingPriv, ephemeralPub)
+ *   2. Decrypt amount, derive stealthPub, verify commitment
+ *
+ * Recipient (spending key - can claim):
+ *   1. stealthPriv = spendingPriv + stealthScalar
+ *   2. Circuit proves: BabyPbk(stealthPriv).x == pub_key_x
+ * ```
+ */
+import { type BabyJubPoint } from "./crypto";
+/**
+ * Complete UTXOpia key hierarchy derived from Solana wallet
+ *
+ * Uses Baby Jubjub for spending keys and Ed25519 for viewing keys.
+ */
+export interface UTXOpiaKeys {
+    /** Solana public key (32 bytes) - user identity */
+    solanaPublicKey: Uint8Array;
+    /** Baby Jubjub spending private key (scalar) - for stealthPriv and nullifier */
+    spendingPrivKey: bigint;
+    /** Baby Jubjub spending public key (point) - share publicly */
+    spendingPubKey: BabyJubPoint;
+    /** Nullifying key (BN254 scalar) - for JoinSplit nullifier computation */
+    nullifyingKey: bigint;
+    /** Ed25519 viewing private key (32 bytes) - for X25519 ECDH scanning */
+    viewingPrivKey: Uint8Array;
+    /** Ed25519 viewing public key (32 bytes) - share publicly */
+    viewingPubKey: Uint8Array;
+    /** Raw EdDSA seed bytes (32 bytes) - for circomlibjs EdDSA-Poseidon signing */
+    eddsaSeed: Uint8Array;
+}
+/**
+ * Stealth meta-address for receiving funds
+ *
+ * Total size: 96 bytes (32 BJJ compressed + 32 Ed25519 + 32 MPK)
+ */
+export interface StealthMetaAddress {
+    /** Baby Jubjub spending public key (32 bytes compressed) */
+    spendingPubKey: Uint8Array;
+    /** Ed25519 viewing public key (32 bytes) */
+    viewingPubKey: Uint8Array;
+    /** Master public key (32 bytes, Poseidon hash as BE bytes) */
+    mpk: Uint8Array;
+}
+/**
+ * Serialized stealth meta-address for display/sharing
+ */
+export interface SerializedStealthMetaAddress {
+    /** Hex-encoded spending public key */
+    spendingPubKey: string;
+    /** Hex-encoded viewing public key */
+    viewingPubKey: string;
+    /** Hex-encoded master public key (Poseidon hash) */
+    mpk: string;
+}
+export interface AuthSignatureKeyDerivationOptions {
+    /** Wallet address or app account label used as domain context. */
+    account?: string;
+    /** Chain label used for domain separation. */
+    chain?: string;
+    /** Network label used for domain separation. */
+    network?: string;
+}
+export interface AuthSignatureKeySetupResult {
+    keys: UTXOpiaKeys;
+    stealthMetaAddress: StealthMetaAddress;
+    encodedStealthAddress: string;
+    root: Uint8Array;
+}
+export declare const PASSKEY_CHAIN_SCOPE_DOMAIN = "utxopia-passkey-chain:v1";
+export type PasskeyChainScope = "sol";
+export interface ChainScopedPasskeyOptions {
+    chain: PasskeyChainScope;
+    network: string;
+}
+/**
+ * Scope a passkey seed to one app chain+network identity.
+ *
+ * This convention is intentionally centralized in the SDK so apps, tests, and
+ * dev tooling derive the same private address without duplicating string
+ * literals.
+ */
+export declare function deriveChainScopedPasskeySeed(seed: Uint8Array, options: ChainScopedPasskeyOptions): Uint8Array;
+export declare function passkeyStorageOwner(credentialId: string, options: ChainScopedPasskeyOptions): string;
+/**
+ * View permission flags for delegated viewing keys
+ */
+export declare enum ViewPermissions {
+    /** Can scan announcements and see amounts */
+    SCAN = 1,
+    /** Can see full transaction history */
+    HISTORY = 2,
+    /** Can see incoming transactions only */
+    INCOMING_ONLY = 4,
+    /** Full viewing access (scan + history) */
+    FULL = 3
+}
+/**
+ * Delegated viewing key for auditors/compliance
+ *
+ * Uses Ed25519 private key for viewing. Deposit verification additionally
+ * requires `spendingPubKeyCompressed` and `nullifyingKey` so the scanner
+ * can compute MPK; without them, only transfer-type announcements can be
+ * confidently matched.
+ */
+export interface DelegatedViewKey {
+    /** Ed25519 viewing private key (32 bytes) */
+    viewingPrivKey: Uint8Array;
+    /** Permission flags */
+    permissions: ViewPermissions;
+    /** Baby Jubjub spending pubkey, compressed (32 bytes). Needed for deposit verification. */
+    spendingPubKeyCompressed?: Uint8Array;
+    /** Nullifying key (BN254 scalar). Needed for deposit verification. */
+    nullifyingKey?: bigint;
+    /** Inclusive lower slot bound for audit scope (honor-system on auditor side). */
+    fromSlot?: number;
+    /** Inclusive upper slot bound for audit scope. */
+    toSlot?: number;
+    /** Optional expiration timestamp (Unix ms) */
+    expiresAt?: number;
+    /** Optional label for identification */
+    label?: string;
+    /** Unix ms when the delegation was created (set by createDelegatedViewKey). */
+    issuedAt?: number;
+    /** Stable opaque ID for tracking this delegation in the user's audit trail. */
+    delegationId?: string;
+}
+/**
+ * Public record of a delegation that the *user* keeps as their audit trail of
+ * keys they have handed out — never carries the viewing private key itself.
+ */
+export interface DelegationRecord {
+    delegationId: string;
+    fingerprint: string;
+    permissions: ViewPermissions;
+    fromSlot?: number;
+    toSlot?: number;
+    expiresAt?: number;
+    issuedAt: number;
+    label?: string;
+    /** Optional free-form note about who received the key (auditor name, firm, etc.). */
+    recipient?: string;
+}
+/** Message to sign for key derivation */
+export declare const SPENDING_KEY_DERIVATION_MESSAGE = "UTXOpia key derivation v1";
+/**
+ * Derive Baby Jubjub public key from raw seed using circomlibjs EdDSA.
+ *
+ * circomlibjs internally hashes the seed (like standard EdDSA key derivation),
+ * producing keys compatible with the EdDSAPoseidonVerifier circuit.
+ * This is NOT the same as `babyJubMul(scalarFromBytes(seed), BASE8)`.
+ */
+export declare function eddsaGetPubKey(seed: Uint8Array): Promise<BabyJubPoint>;
+/**
+ * Extract the internal EdDSA private scalar from a seed.
+ *
+ * circomlibjs does: BLAKE-512(seed) → pruneBuffer → fromRprLE(32 bytes) → shr(3)
+ * This scalar × BASE8 = the public key from `eddsaGetPubKey(seed)`.
+ *
+ * We intercept circomlibjs's `pruneBuffer` call during `prv2pub` to capture
+ * the intermediate buffer, then replicate the LE→bigint→shr(3) conversion.
+ * This avoids directly importing ffjavascript/blake-hash which aren't bundled by webpack.
+ */
+export declare function eddsaGetPrivScalar(seed: Uint8Array): Promise<bigint>;
+/**
+ * Sign a message hash with EdDSA-Poseidon (circomlibjs).
+ *
+ * Returns [R8.x, R8.y, S] compatible with the EdDSAPoseidonVerifier circuit.
+ */
+export declare function eddsaPoseidonSign(seed: Uint8Array, msgHash: bigint): Promise<[bigint, bigint, bigint]>;
+/**
+ * Sign a message hash with EdDSA-Poseidon using a given private scalar directly.
+ *
+ * Unlike `eddsaPoseidonSign` which derives the scalar internally via circomlibjs's
+ * BLAKE-512 derivation, this function uses the provided scalar as-is.
+ * This is needed when the public key was derived via `scalarFromBytes` (sync)
+ * rather than circomlibjs's internal derivation.
+ *
+ * Returns [R8.x, R8.y, S] compatible with the EdDSAPoseidonVerifier circuit.
+ */
+export declare function eddsaPoseidonSignWithScalar(privScalar: bigint, pubKey: BabyJubPoint, msgHash: bigint): [bigint, bigint, bigint];
+/**
+ * Minimal wallet adapter interface for signing
+ * Compatible with @solana/wallet-adapter-base
+ */
+export interface WalletSignerAdapter {
+    publicKey: {
+        toBytes(): Uint8Array;
+    } | null;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Derive UTXOpia keys from Solana wallet signature.
+ *
+ * Uses circomlibjs EdDSA for spendingPubKey derivation so keys are
+ * compatible with the EdDSAPoseidonVerifier circuit.
+ */
+export declare function deriveKeysFromWallet(wallet: WalletSignerAdapter): Promise<UTXOpiaKeys>;
+/**
+ * Derive UTXOpia keys from a signature
+ *
+ * Spending key: SHA256(sig || "spend") → reduce mod BJJ_ORDER → babyJubMul(scalar, BASE8)
+ * Viewing key: SHA256(sig || "view") → Ed25519 private key → ed25519.getPublicKey()
+ */
+export declare function deriveKeysFromSignature(signature: Uint8Array, solanaPublicKey: Uint8Array): UTXOpiaKeys;
+/**
+ * Generate a random 65-byte signature-shaped seed for dev/test auth flows.
+ *
+ * Mirrors Fluidkey's "signature as deterministic key source" shape without
+ * requiring a wallet or zkLogin proof during local testing.
+ */
+export declare function generateRandomAuthSignature(): Uint8Array;
+/**
+ * Derive UTXOpia keys from a wallet/zkLogin signature-shaped secret.
+ *
+ * User-facing model is two keys:
+ * - spending seed/key
+ * - viewing seed/key
+ *
+ * The protocol nullifying key is internal and derived from the spending seed,
+ * so delegated viewing keys do not automatically carry nullifier authority.
+ */
+export declare function deriveKeysFromAuthSignature(signature: Uint8Array, options?: AuthSignatureKeyDerivationOptions): Promise<UTXOpiaKeys>;
+export declare function setupKeysFromAuthSignature(signature: Uint8Array, options?: AuthSignatureKeyDerivationOptions): Promise<AuthSignatureKeySetupResult>;
+/**
+ * Derive keys from a seed phrase (sync — for scanning/non-circuit use)
+ */
+export declare function deriveKeysFromSeed(seed: Uint8Array): UTXOpiaKeys;
+/**
+ * Derive keys from a seed phrase with circomlibjs-compatible spending keys.
+ *
+ * Must be used when the keys will be used for circuit proofs (EdDSA signing).
+ * The sync `deriveKeysFromSeed` uses a different scalar derivation that doesn't
+ * match circomlibjs's internal BLAKE-512 derivation used by `eddsaPoseidonSign`.
+ */
+export declare function deriveKeysFromSeedCircuit(seed: Uint8Array): Promise<UTXOpiaKeys>;
+/**
+ * Create a stealth meta-address from UTXOpia keys
+ *
+ * Size: 96 bytes (32 BJJ compressed + 32 Ed25519 + 32 MPK)
+ */
+export declare function createStealthMetaAddress(keys: UTXOpiaKeys): StealthMetaAddress;
+/**
+ * Serialize a stealth meta-address for display/sharing
+ */
+export declare function serializeStealthMetaAddress(meta: StealthMetaAddress): SerializedStealthMetaAddress;
+/**
+ * Deserialize a stealth meta-address from string representation
+ */
+export declare function deserializeStealthMetaAddress(serialized: SerializedStealthMetaAddress): StealthMetaAddress;
+/**
+ * Parse a stealth meta-address and extract public keys
+ *
+ * Returns Baby Jubjub spending pubkey and Ed25519 viewing pubkey.
+ */
+export declare function parseStealthMetaAddress(meta: StealthMetaAddress): {
+    spendingPubKey: BabyJubPoint;
+    viewingPubKey: Uint8Array;
+};
+/**
+ * Encode stealth meta-address as a single string with utxo: prefix
+ * Format: "utxo:" + hex(spendingPubKey (32) || viewingPubKey (32) || mpk (32))
+ */
+export declare function encodeStealthMetaAddress(meta: StealthMetaAddress): string;
+/**
+ * Decode stealth meta-address from a string (with or without utxo: prefix)
+ */
+export declare function decodeStealthMetaAddress(encoded: string): StealthMetaAddress;
+/**
+ * Create a delegated viewing key for auditors/compliance
+ *
+ * The returned key carries everything an auditor needs to scan announcements
+ * within the configured slot range, including the spending pubkey and
+ * nullifying key (required for deposit verification — `Poseidon(npk, token, amount)`
+ * must match on-chain commitment). A fresh `delegationId` and `issuedAt` are
+ * generated so the user can keep an [[auditable-disclosure-status]] trail of
+ * who they handed keys to.
+ */
+export declare function createDelegatedViewKey(keys: UTXOpiaKeys, permissions?: ViewPermissions, options?: {
+    fromSlot?: number;
+    toSlot?: number;
+    expiresAt?: number;
+    label?: string;
+}): DelegatedViewKey;
+/**
+ * Build a public-only record of a delegated viewing key for the issuer's
+ * audit trail. Strips the secret material; only carries identifiers + scope.
+ */
+export declare function makeDelegationRecord(key: DelegatedViewKey, options?: {
+    recipient?: string;
+}): DelegationRecord;
+/**
+ * Compute a stable fingerprint for a delegated viewing key.
+ *
+ * `sha256(viewingPrivKey)[..16]` rendered as hex — short enough to display,
+ * long enough to make collisions astronomically unlikely. Identical viewing
+ * keys produce identical fingerprints, so the user can detect duplicate
+ * delegations across export sessions.
+ */
+export declare function fingerprintDelegatedKey(key: DelegatedViewKey): string;
+/**
+ * Decide whether a slot falls within the delegated key's permitted range.
+ * No range bound on a side ⇒ unbounded on that side.
+ */
+export declare function isSlotInDelegatedRange(key: DelegatedViewKey, slot: number | undefined): boolean;
+/**
+ * Serialize a delegated viewing key for export (ENCRYPTED)
+ */
+export declare function serializeDelegatedViewKey(key: DelegatedViewKey, password?: string): Promise<string>;
+/**
+ * Deserialize a delegated viewing key from JSON.
+ *
+ * v1 keys are refused at parse time by default (they lack
+ * `spendingPubKeyCompressed`/`nullifyingKey`, so `auditScan` would error out
+ * downstream anyway — failing early gives callers a clearer message and
+ * avoids partial setup). Set `acceptV1: true` to opt in for migration
+ * tools that need to crack open old blobs to re-issue them as v2.
+ */
+export declare function deserializeDelegatedViewKey(json: string, password?: string, options?: {
+    acceptV1?: boolean;
+}): Promise<DelegatedViewKey>;
+/**
+ * Check if a delegated viewing key is valid (not expired)
+ */
+export declare function isDelegatedKeyValid(key: DelegatedViewKey): boolean;
+/**
+ * Check if a delegated key has a specific permission
+ */
+export declare function hasPermission(key: DelegatedViewKey, permission: ViewPermissions): boolean;
+/**
+ * Safely compare two keys in constant time
+ */
+export declare function constantTimeCompare(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Securely clear sensitive key material from memory
+ */
+export declare function clearKey(key: Uint8Array): void;
+/**
+ * Securely clear all sensitive keys from an UTXOpiaKeys object
+ */
+export declare function clearUTXOpiaKeys(keys: UTXOpiaKeys): void;
+/**
+ * Securely clear a delegated viewing key
+ */
+export declare function clearDelegatedViewKey(key: DelegatedViewKey): void;
+/**
+ * Derive a view-only key bundle (no spending key)
+ * Safe to export/backup separately from spending key
+ */
+export declare function extractViewOnlyBundle(keys: UTXOpiaKeys): {
+    solanaPublicKey: Uint8Array;
+    spendingPubKey: Uint8Array;
+    viewingPrivKey: Uint8Array;
+    viewingPubKey: Uint8Array;
+};
+/**
+ * Serialized key storage format (all values are hex strings or string-encoded bigints).
+ */
+export interface SerializedKeysForStorage {
+    eddsaSeedHex: string;
+    spendingPrivKeyHex: string;
+    spendingPubKey: {
+        x: string;
+        y: string;
+    };
+    nullifyingKey: string;
+    viewingPrivKeyHex: string;
+    viewingPubKeyHex: string;
+}
+/**
+ * Serialize UTXOpiaKeys to a plain object with hex strings (for encrypted storage).
+ *
+ * The result is JSON-safe. Use `deserializeKeysFromStorage` to reconstruct.
+ */
+export declare function serializeKeysForStorage(keys: UTXOpiaKeys): SerializedKeysForStorage;
+/**
+ * Deserialize UTXOpiaKeys from a storage object (reverse of serializeKeysForStorage).
+ *
+ * Requires `solanaPublicKey` to be provided separately since it is not stored
+ * in the serialized format (it comes from the connected wallet).
+ */
+export declare function deserializeKeysFromStorage(data: SerializedKeysForStorage, solanaPublicKey: Uint8Array): UTXOpiaKeys;
+/**
+ * Result of a complete key setup operation (derivation + stealth address creation).
+ */
+export interface KeySetupResult {
+    keys: UTXOpiaKeys;
+    stealthAddress: StealthMetaAddress;
+    stealthAddressEncoded: string;
+}
+/**
+ * Derive keys from wallet signature and create stealth address in one step.
+ *
+ * Combines deriveKeysFromWallet + createStealthMetaAddress + encodeStealthMetaAddress.
+ */
+export declare function setupKeysFromWallet(wallet: WalletSignerAdapter): Promise<KeySetupResult>;
+/**
+ * Derive keys from seed (passkey PRF or secret phrase) and create stealth address in one step.
+ *
+ * Combines deriveKeysFromSeedCircuit + createStealthMetaAddress + encodeStealthMetaAddress.
+ */
+export declare function setupKeysFromSeed(seed: Uint8Array): Promise<KeySetupResult>;
+/**
+ * Recreate stealth address from existing keys (for hydration from storage).
+ *
+ * Use this when keys are already deserialized and you just need the stealth address.
+ */
+export declare function recreateStealthAddress(keys: UTXOpiaKeys): {
+    stealthAddress: StealthMetaAddress;
+    stealthAddressEncoded: string;
+};
+/**
+ * Generate a random Ed25519 auditor viewing keypair.
+ *
+ * Thin wrapper over `ed25519GenerateKeyPair`. The returned keys are suitable
+ * for use as the auditor viewing key pair in `encryptAuditorCiphertext` /
+ * `decryptAuditorCiphertext`.
+ *
+ * @returns 32-byte private key and 32-byte Ed25519 public key
+ */
+export declare function generateAuditorViewingKeypair(): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
+/**
+ * Derive a deterministic Ed25519 auditor viewing keypair from a 32-byte seed.
+ *
+ * Uses `ed25519DeriveKeyFromSeed` which SHA-256s the seed to produce the
+ * Ed25519 private key, then derives the matching public key. Same seed always
+ * yields the same keypair; different seeds yield different keypairs.
+ *
+ * @param seed - 32-byte seed (e.g. from a KDF or random source)
+ * @returns 32-byte private key and 32-byte Ed25519 public key
+ */
+export declare function deriveAuditorViewingKeypair(seed: Uint8Array): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};