@gvnrdao/dh-lit-actions 0.0.61 → 0.0.68

package/pkg-dist/src/modules/authorization.module.js

@@ -0,0 +1,317 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthorizationModule = void 0;
+const quantum_time_module_1 = require("./quantum-time.module");
+/**
+ * Authorization Module
+ *
+ * Validates that LIT Action callers are authorized to perform operations.
+ *
+ * RESTORED PRODUCTION-GRADE DESIGN (from b2794c9):
+ * - Quantum timestamp prevents replay across different quantums
+ * - Waits for safe quantum moment before validation
+ * - Validates timestamp is within current quantum window
+ * - Signature proves caller identity
+ * - Contract verification proves ownership
+ *
+ * Authorization Flow:
+ * 1. Wait for safe quantum moment (if in dead zone)
+ * 2. Verify timestamp is within valid quantum window
+ * 3. Build message hash from parameters (positionId, timestamp, chainId, amount, action)
+ * 4. Recover signer address from signature (EIP-191 standard)
+ * 5. Verify recovered signer === position owner (from contract)
+ *
+ * Security Properties:
+ * - Quantum timing enforces 100-second windows with dead zone protection
+ * - Smart contract only accepts one operation per quantum per position
+ * - Signature proves caller owns the signing address
+ * - Contract verification proves signer is position owner
+ * - chainId prevents cross-chain replay attacks
+ * - Mode controls whether dev environments (hardhat/regtest) are allowed
+ *
+ * Example: mintUCD
+ * - Message: keccak256(positionId, timestamp, chainId, amount, actionHash)
+ * - User signs with wallet (EIP-191)
+ * - LIT Action WAITS for safe quantum moment
+ * - LIT Action VALIDATES quantum timestamp
+ * - LIT Action recovers signer address
+ * - LIT Action verifies signer is position owner (via contract)
+ */
+/**
+ * Authorization Module
+ *
+ * Provides methods to verify caller authorization for LIT Actions
+ */
+class AuthorizationModule {
+    /**
+     * Verify auth structure for amount/position/action operations
+     *
+     * Validates that all required fields are present and have correct types:
+     * - positionId (string, required)
+     * - chainId (number, required)
+     * - timestamp (number, required)
+     * - amount (required, any type that can convert to bigint)
+     * - action (string, required)
+     * - signature (string, required)
+     * - mode ("dev" or "prod", required)
+     *
+     * @param auth - Authorization object to validate (untyped)
+     * @returns Typed OwnerAmountActionAuthorization object after validation
+     * @throws Error if any validation fails
+     */
+    static verifyAmountPositionActionAuthorizationStructure(auth) {
+        if (!auth || typeof auth !== "object") {
+            throw new Error('Missing or invalid "auth" parameter - must be an object');
+        }
+        // Validate all required auth fields
+        if (!auth.positionId) {
+            throw new Error("auth.positionId is required");
+        }
+        if (typeof auth.chainId !== "number") {
+            throw new Error("auth.chainId must be a number");
+        }
+        if (typeof auth.timestamp !== "number") {
+            throw new Error("auth.timestamp must be a number");
+        }
+        if (typeof auth.amount === "undefined" || auth.amount === null) {
+            throw new Error("auth.amount is required");
+        }
+        if (!auth.action) {
+            throw new Error("auth.action is required");
+        }
+        if (!auth.signature) {
+            throw new Error("auth.signature is required");
+        }
+        if (!auth.mode) {
+            throw new Error("auth.mode is required");
+        }
+        if (auth.mode !== "dev" && auth.mode !== "prod") {
+            throw new Error(`auth.mode must be "dev" or "prod", got: ${auth.mode}`);
+        }
+        // Return typed object after validation
+        return auth;
+    }
+    /**
+     * Recover signer address from signature
+     *
+     * Uses EIP-191 standard (Ethereum Signed Message)
+     *
+     * @param messageHash - Keccak256 hash of the message
+     * @param signature - Signature to verify
+     * @returns Recovered signer address
+     */
+    static async recoverSigner(messageHash, signature) {
+        try {
+            // Convert message hash to bytes for EIP-191 prefixing
+            const messageHashBytes = ethers.utils.arrayify(messageHash);
+            // Apply EIP-191 prefix: "\x19Ethereum Signed Message:\n" + len(message) + message
+            const prefixedHash = ethers.utils.hashMessage(messageHashBytes);
+            // Recover address from signature
+            const recoveredAddress = ethers.utils.recoverAddress(prefixedHash, signature);
+            return recoveredAddress;
+        }
+        catch (error) {
+            console.error("[Authorization] Signature recovery failed:", error);
+            throw new Error(`Failed to recover signer: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Agnostic authorization verification
+     *
+     * Verifies authorization for any action by:
+     * 1. Waiting for safe quantum moment
+     * 2. Validating quantum timestamp
+     * 3. Building message hash using provided buildMessage function
+     * 4. Recovering signer from signature
+     * 5. Checking authorization using provided isAuthorized function
+     *
+     * @param auth - Authorization parameters (timestamp, signature, mode)
+     * @param buildMessage - Function to build message hash (caller has context/closure)
+     * @param isAuthorized - Function to check if recovered address is authorized (caller has context/closure)
+     * @returns True if authorized
+     */
+    static async verifyActionAuthorization(auth, buildMessage, isAuthorized) {
+        // STEP 1: Wait for safe quantum moment (if needed)
+        await (0, quantum_time_module_1.waitForSafeQuantumMoment)();
+        // STEP 2: Verify timestamp is within quantum window
+        try {
+            (0, quantum_time_module_1.validateQuantumTimestamp)(auth.timestamp);
+        }
+        catch (error) {
+            console.error("[Authorization] Quantum timestamp validation failed:", error);
+            return false;
+        }
+        // Validate mode field
+        if (!auth.mode) {
+            console.error("[Authorization] Missing mode field");
+            return false;
+        }
+        if (auth.mode !== "dev" && auth.mode !== "prod") {
+            console.error(`[Authorization] Invalid mode: ${auth.mode}, must be "dev" or "prod"`);
+            return false;
+        }
+        // Production mode not yet supported
+        if (auth.mode === "prod") {
+            console.error('[Authorization] Production mode not yet supported - use mode="dev"');
+            return false;
+        }
+        // STEP 3: Build message hash using provided function
+        const messageHash = buildMessage();
+        console.log("[Authorization] Message hash:", messageHash);
+        // STEP 4: Recover signer from signature
+        console.log("[Authorization] Recovering signer from signature...");
+        console.log("  signature:", auth.signature);
+        const recoveredAddress = await this.recoverSigner(messageHash, auth.signature);
+        console.log("  recoveredAddress:", recoveredAddress);
+        // STEP 5: Check authorization using provided function
+        console.log("[Authorization] Checking authorization:");
+        console.log("  recoveredAddress:", recoveredAddress);
+        console.log("  recoveredAddress (lowercase):", recoveredAddress.toLowerCase());
+        const authorized = isAuthorized(recoveredAddress);
+        console.log("  match:", authorized ? "✅ YES" : "❌ NO");
+        if (!authorized) {
+            console.error(`[Authorization] Not authorized:`, `\n  Recovered: ${recoveredAddress}`);
+        }
+        return authorized;
+    }
+    /**
+     * Verify position owner authorization for any amount-based position action
+     *
+     * AGNOSTIC BASE FUNCTION - verifies authorization without checking action string
+     * Specific action verification functions should validate action string before calling this.
+     *
+     * RESTORED PRODUCTION-GRADE QUANTUM VALIDATION:
+     * - STEP 1: Waits for safe quantum moment (avoids dead zone)
+     * - STEP 2: Validates timestamp is within current quantum window
+     * - STEP 3: Builds message hash from parameters
+     * - STEP 4: Recovers signer from signature
+     * - STEP 5: Verifies signer matches position owner
+     *
+     * Message contains: positionId, timestamp, chainId, amount, action
+     * NO callerAddress in message (recovered from signature via ecrecover)
+     *
+     * @param auth - Authorization parameters (positionId, timestamp, chainId, amount, action, signature, mode)
+     * @param positionOwner - Position owner address from contract
+     * @returns True if authorized
+     */
+    static async verifyAmountPositionActionAuthorization(auth, positionOwner) {
+        // Build message hash function specific to mint action
+        // Caller has closure over auth parameters
+        const buildMessage = () => {
+            const actionHash = ethers.utils.keccak256(ethers.utils.toUtf8Bytes(auth.action));
+            const amountBigInt = typeof auth.amount === "string" ? BigInt(auth.amount) : auth.amount;
+            // Debug logging for message hash construction
+            console.log("[Authorization] Building message hash:");
+            console.log("  positionId:", auth.positionId);
+            console.log("  timestamp:", auth.timestamp);
+            console.log("  chainId:", auth.chainId);
+            console.log("  amount (string):", auth.amount);
+            console.log("  amount (BigInt):", amountBigInt.toString());
+            console.log("  action:", auth.action);
+            console.log("  actionHash:", actionHash);
+            const types = [
+                "bytes32", // positionId
+                "uint256", // timestamp
+                "uint256", // chainId
+                "uint256", // amount
+                "bytes32", // actionHash
+            ];
+            const values = [
+                auth.positionId,
+                auth.timestamp,
+                auth.chainId,
+                amountBigInt.toString(),
+                actionHash,
+            ];
+            const messageHash = ethers.utils.solidityKeccak256(types, values);
+            console.log("  messageHash (solidityKeccak256):", messageHash);
+            return messageHash;
+        };
+        // Authorization check function
+        // Caller has closure over positionOwner
+        const isAuthorized = (recovered) => {
+            return recovered.toLowerCase() === positionOwner.toLowerCase();
+        };
+        // Use agnostic verification
+        return this.verifyActionAuthorization(auth, buildMessage, isAuthorized);
+    }
+    /**
+     * Verify position owner authorization for mintUCD action
+     *
+     * Validates action string is "mint-ucd" then delegates to base function.
+     *
+     * @param auth - Authorization parameters (positionId, timestamp, chainId, amount, action, signature, mode)
+     * @param positionOwner - Position owner address from contract
+     * @returns True if authorized
+     */
+    static async verifyMintAuthorization(auth, positionOwner) {
+        // Validate action string matches expected value
+        if (auth.action !== "mint-ucd") {
+            console.error(`[Authorization] Invalid action for mint: expected "mint-ucd", got "${auth.action}"`);
+            return false;
+        }
+        // Delegate to base authorization function
+        return this.verifyAmountPositionActionAuthorization(auth, positionOwner);
+    }
+    /**
+     * Verify position owner authorization for withdrawBTC action
+     *
+     * Validates action string is "withdraw-btc" and includes destinationAddress in message.
+     * Unlike mint/repay, withdrawal requires destination address to prevent unauthorized redirection.
+     *
+     * Message contains: positionId, timestamp, chainId, amount, destinationAddress, action
+     *
+     * @param auth - Authorization parameters (positionId, timestamp, chainId, amount, destinationAddress, action, signature, mode)
+     * @param positionOwner - Position owner address from contract
+     * @returns True if authorized
+     */
+    static async verifyWithdrawAuthorization(auth, positionOwner) {
+        // Validate action string matches expected value
+        if (auth.action !== "withdraw-btc") {
+            console.error(`[Authorization] Invalid action for withdrawal: expected "withdraw-btc", got "${auth.action}"`);
+            return false;
+        }
+        // Build message hash function specific to withdraw action (includes destinationAddress)
+        const buildMessage = () => {
+            const actionHash = ethers.utils.keccak256(ethers.utils.toUtf8Bytes(auth.action));
+            const amountBigInt = typeof auth.amount === "string" ? BigInt(auth.amount) : auth.amount;
+            // Debug logging for message hash construction
+            console.log("[Authorization] Building withdrawal message hash:");
+            console.log("  positionId:", auth.positionId);
+            console.log("  timestamp:", auth.timestamp);
+            console.log("  chainId:", auth.chainId);
+            console.log("  amount (string):", auth.amount);
+            console.log("  amount (BigInt):", amountBigInt.toString());
+            console.log("  destinationAddress:", auth.destinationAddress);
+            console.log("  action:", auth.action);
+            console.log("  actionHash:", actionHash);
+            const types = [
+                "bytes32", // positionId
+                "uint256", // timestamp
+                "uint256", // chainId
+                "uint256", // amount (total deduction from vault)
+                "string", // destinationAddress (Bitcoin address)
+                "bytes32", // actionHash
+            ];
+            const values = [
+                auth.positionId,
+                auth.timestamp,
+                auth.chainId,
+                amountBigInt.toString(),
+                auth.destinationAddress,
+                actionHash,
+            ];
+            const messageHash = ethers.utils.solidityKeccak256(types, values);
+            console.log("  messageHash (solidityKeccak256):", messageHash);
+            return messageHash;
+        };
+        // Authorization check function
+        const isAuthorized = (recovered) => {
+            return recovered.toLowerCase() === positionOwner.toLowerCase();
+        };
+        // Use agnostic verification
+        return this.verifyActionAuthorization(auth, buildMessage, isAuthorized);
+    }
+}
+exports.AuthorizationModule = AuthorizationModule;
+//# sourceMappingURL=authorization.module.js.map

package/pkg-dist/src/modules/authorization.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.module.js","sourceRoot":"","sources":["../../../src/modules/authorization.module.ts"],"names":[],"mappings":"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"}

package/pkg-dist/src/modules/bitcoin-data-provider.module.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Bitcoin Data Provider Module
+ *
+ * Provides Bitcoin network data with support for future consensus mechanisms.
+ * Current implementation: Single provider with fallback support
+ * Future implementation: 2-of-3 provider consensus
+ *
+ * This module centralizes all Bitcoin data queries to maintain a consistent
+ * interface that won't break when upgrading to multi-provider consensus.
+ */
+import { BitcoinDataProviderConfig, UTXO, UTXOSet } from "../interfaces/chunks/vault-balance.i";
+import { IBitcoinDataProvider } from "../interfaces/chunks/bitcoin-data-provider.i";
+/**
+ * Bitcoin Data Provider
+ *
+ * Fetches UTXO data from Bitcoin network.
+ * Interface designed to remain stable when adding multi-provider consensus.
+ */
+export declare class BitcoinDataProvider implements IBitcoinDataProvider {
+    private config;
+    private timeout;
+    constructor(config: BitcoinDataProviderConfig);
+    /**
+     * Fetch all UTXOs for a Bitcoin address
+     *
+     * @param address - Bitcoin address (legacy, segwit, or taproot)
+     * @returns Array of UTXOs
+     */
+    getUTXOs(address: string): Promise<UTXO[]>;
+    /**
+     * Strip network prefix from Bitcoin address
+     *
+     * Addresses may be stored with network prefix (e.g., "REGTEST_address")
+     * but APIs expect clean addresses without prefix.
+     *
+     * @param address - Address with optional prefix
+     * @returns Clean address without prefix
+     */
+    private stripNetworkPrefix;
+    /**
+     * Fetch UTXOs using Bitcoin RPC (for regtest/testing)
+     */
+    private fetchUTXOsFromRPC;
+    /**
+     * Parse Esplora/Blockstream/Mempool.space UTXO response
+     *
+     * Expected format: Array of {txid, vout, value, confirmations}
+     *
+     * @param data Raw response from provider API
+     * @returns Array of normalized UTXOs
+     */
+    private parseBlockstreamUTXOs;
+    /**
+     * Internal method to fetch UTXOs from a specific provider
+     *
+     * Supports standard Esplora API format:
+     * - Standard format: {providerUrl}/address/{address}/utxos
+     * - providerUrl must include full base path (e.g., "http://localhost:3002/api/esplora")
+     */
+    private fetchUTXOsFromProvider;
+    /**
+     * Get complete UTXO set with balance summary
+     *
+     * This is the SINGLE method that vault-balance module should call.
+     * Returns everything needed to know about Bitcoin network state for an address.
+     *
+     * @param address - Bitcoin address
+     * @param minConfirmations - Minimum confirmations for "confirmed" status (REQUIRED - caller must specify)
+     * @returns Complete UTXO set with balance breakdown
+     */
+    getUTXOSet(address: string, minConfirmations: number): Promise<UTXOSet>;
+    /**
+     * Get transaction with confirmation count
+     *
+     * Checks if transaction exists on Bitcoin network and returns confirmation count.
+     * Used to validate authorized spends have been broadcasted.
+     *
+     * @param txid - Transaction ID to check
+     * @returns Transaction with confirmation count, or null if not found
+     */
+    getTransaction(txid: string): Promise<{
+        txid: string;
+        confirmations: number;
+    } | null>;
+}
+/**
+ * Factory function for creating Bitcoin Data Provider
+ * Useful for dependency injection and testing
+ */
+export declare function createBitcoinDataProvider(config: BitcoinDataProviderConfig): BitcoinDataProvider;
+//# sourceMappingURL=bitcoin-data-provider.module.d.ts.map

package/pkg-dist/src/modules/bitcoin-data-provider.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitcoin-data-provider.module.d.ts","sourceRoot":"","sources":["../../../src/modules/bitcoin-data-provider.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,yBAAyB,EACzB,IAAI,EACJ,OAAO,EACR,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAEpF;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,yBAAyB;IAK7C;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAqDhD;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;OAEG;YACW,iBAAiB;IAqB/B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;;;;;OAMG;YACW,sBAAsB;IAkDpC;;;;;;;;;OASG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC;IAkBnB;;;;;;;;OAQG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA+E3D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,yBAAyB,GAChC,mBAAmB,CAErB"}