@cedros/login-sidecar 0.0.1

package/dist/services/privacy-cash.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Privacy Cash SDK wrapper service
+ *
+ * This service wraps the Privacy Cash SDK for SSS embedded wallets only.
+ *
+ * Architecture:
+ * - User deposits to THEIR OWN Privacy Cash account (user's pubkey)
+ * - Server holds Share A + temporarily stores Share B during privacy period
+ * - Server can reconstruct keypair to withdraw to company wallet
+ * - On-chain: User deposit and Company withdrawal are unlinkable
+ *
+ * Requirements:
+ * - SSS wallets only (no external wallets like Phantom)
+ * - No-recovery option required (user has only Share B, no Share C)
+ * - Server stores Share B during "privacy period" until withdrawal completes
+ */
+import { Keypair } from '@solana/web3.js';
+import { Config } from '../config.js';
+import { SolanaService } from './solana.js';
+export interface ExecuteDepositResult {
+    success: boolean;
+    txSignature: string;
+}
+export interface WithdrawResult {
+    success: boolean;
+    txSignature: string;
+    feeLamports: number;
+    /** Actual amount withdrawn (after fees) - may be less than requested if partial */
+    amountLamports: number;
+    /** True if the full requested amount couldn't be withdrawn (insufficient balance) */
+    isPartial: boolean;
+}
+export declare class PrivacyCashService {
+    private solana;
+    private connection;
+    private companyWalletAddress;
+    private storage;
+    private lightWasm;
+    private keyBasePath;
+    private sdkInitialized;
+    constructor(config: Config, solanaService: SolanaService);
+    /**
+     * Initialize SDK components (lazy loading)
+     */
+    private ensureInitialized;
+    /**
+     * Create an encryption service for a specific user keypair
+     */
+    private createEncryptionService;
+    /**
+     * Execute a deposit for an SSS embedded wallet
+     *
+     * Deposits to the USER's Privacy Cash account (user's pubkey is the owner).
+     * The user signs the transaction.
+     *
+     * @param userKeypair - The user's reconstructed keypair (from Share A + Share B)
+     * @param amountLamports - Amount to deposit in lamports
+     */
+    executeDeposit(userKeypair: Keypair, amountLamports: number): Promise<ExecuteDepositResult>;
+    /**
+     * Withdraw funds from a user's Privacy Cash account to the company wallet
+     *
+     * This is called server-side after the "privacy period" has elapsed.
+     * Requires the user's keypair (reconstructed from stored shares).
+     *
+     * @param userKeypair - The user's reconstructed keypair (from Share A + Share B)
+     * @param amountLamports - Amount to withdraw in lamports
+     */
+    withdrawFromUser(userKeypair: Keypair, amountLamports: number): Promise<WithdrawResult>;
+    /**
+     * Get a user's private balance in Privacy Cash
+     *
+     * @param userKeypair - The user's reconstructed keypair
+     */
+    getUserPrivateBalance(userKeypair: Keypair): Promise<number>;
+    /**
+     * Check if the SDK is properly loaded
+     */
+    isLoaded(): Promise<boolean>;
+    /**
+     * Parse a base58-encoded private key into a Keypair
+     */
+    static parseKeypair(privateKeyBase58: string): Keypair;
+}

package/dist/services/privacy-cash.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Privacy Cash SDK wrapper service
+ *
+ * This service wraps the Privacy Cash SDK for SSS embedded wallets only.
+ *
+ * Architecture:
+ * - User deposits to THEIR OWN Privacy Cash account (user's pubkey)
+ * - Server holds Share A + temporarily stores Share B during privacy period
+ * - Server can reconstruct keypair to withdraw to company wallet
+ * - On-chain: User deposit and Company withdrawal are unlinkable
+ *
+ * Requirements:
+ * - SSS wallets only (no external wallets like Phantom)
+ * - No-recovery option required (user has only Share B, no Share C)
+ * - Server stores Share B during "privacy period" until withdrawal completes
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrivacyCashService = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const hasher_rs_1 = require("@lightprotocol/hasher.rs");
+const node_localstorage_1 = require("node-localstorage");
+const bs58_1 = __importDefault(require("bs58"));
+const node_path_1 = __importDefault(require("node:path"));
+// SDK module cache
+let sdkModule = null;
+async function loadSdk() {
+    if (!sdkModule) {
+        // Dynamic import of SDK (using any to bypass type checking for untyped package)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const exportUtils = await import('privacycash');
+        sdkModule = {
+            deposit: exportUtils.deposit,
+            withdraw: exportUtils.withdraw,
+            EncryptionService: exportUtils.EncryptionService,
+            getUtxos: exportUtils.getUtxos,
+            getBalanceFromUtxos: exportUtils.getBalanceFromUtxos,
+        };
+    }
+    return sdkModule;
+}
+class PrivacyCashService {
+    solana;
+    connection;
+    companyWalletAddress;
+    storage;
+    lightWasm = null;
+    keyBasePath;
+    sdkInitialized = false;
+    constructor(config, solanaService) {
+        this.solana = solanaService;
+        this.connection = solanaService.getConnection();
+        // Company wallet is the recipient for withdrawals (no private key needed here)
+        this.companyWalletAddress = new web3_js_1.PublicKey(config.companyWalletAddress);
+        // Initialize storage for UTXO caching
+        this.storage = new node_localstorage_1.LocalStorage(node_path_1.default.join(process.cwd(), 'privacy-cache'));
+        // Path to circuit files (bundled with SDK)
+        this.keyBasePath = '';
+        console.log(`[PrivacyCash] Initialized with company wallet: ${this.companyWalletAddress.toBase58()}`);
+    }
+    /**
+     * Initialize SDK components (lazy loading)
+     */
+    async ensureInitialized() {
+        const sdk = await loadSdk();
+        if (!this.lightWasm) {
+            this.lightWasm = await hasher_rs_1.WasmFactory.getInstance();
+        }
+        // Set keyBasePath if not already set
+        if (!this.keyBasePath) {
+            this.keyBasePath = node_path_1.default.join(process.cwd(), 'node_modules', 'privacycash', 'circuit2', 'transaction2');
+        }
+        this.sdkInitialized = true;
+        return sdk;
+    }
+    /**
+     * Create an encryption service for a specific user keypair
+     */
+    async createEncryptionService(sdk, keypair) {
+        const encryptionService = new sdk.EncryptionService();
+        encryptionService.deriveEncryptionKeyFromWallet(keypair);
+        return encryptionService;
+    }
+    /**
+     * Execute a deposit for an SSS embedded wallet
+     *
+     * Deposits to the USER's Privacy Cash account (user's pubkey is the owner).
+     * The user signs the transaction.
+     *
+     * @param userKeypair - The user's reconstructed keypair (from Share A + Share B)
+     * @param amountLamports - Amount to deposit in lamports
+     */
+    async executeDeposit(userKeypair, amountLamports) {
+        const sdk = await this.ensureInitialized();
+        const encryptionService = await this.createEncryptionService(sdk, userKeypair);
+        // Deposit to USER's Privacy Cash account (user owns the private balance)
+        const result = await sdk.deposit({
+            lightWasm: this.lightWasm,
+            amount_in_lamports: amountLamports,
+            connection: this.connection,
+            encryptionService,
+            publicKey: userKeypair.publicKey, // User owns the Privacy Cash account
+            transactionSigner: async (tx) => {
+                tx.sign([userKeypair]);
+                return tx;
+            },
+            keyBasePath: this.keyBasePath,
+            storage: this.storage,
+        });
+        return {
+            success: true,
+            txSignature: result.tx,
+        };
+    }
+    /**
+     * Withdraw funds from a user's Privacy Cash account to the company wallet
+     *
+     * This is called server-side after the "privacy period" has elapsed.
+     * Requires the user's keypair (reconstructed from stored shares).
+     *
+     * @param userKeypair - The user's reconstructed keypair (from Share A + Share B)
+     * @param amountLamports - Amount to withdraw in lamports
+     */
+    async withdrawFromUser(userKeypair, amountLamports) {
+        const sdk = await this.ensureInitialized();
+        const encryptionService = await this.createEncryptionService(sdk, userKeypair);
+        const result = await sdk.withdraw({
+            lightWasm: this.lightWasm,
+            amount_in_lamports: amountLamports,
+            connection: this.connection,
+            encryptionService,
+            publicKey: userKeypair.publicKey, // User's Privacy Cash account
+            recipient: this.companyWalletAddress, // Withdraw to company wallet
+            keyBasePath: this.keyBasePath,
+            storage: this.storage,
+        });
+        return {
+            success: true,
+            txSignature: result.tx,
+            feeLamports: result.fee_in_lamports,
+            amountLamports: result.amount_in_lamports,
+            isPartial: result.isPartial,
+        };
+    }
+    /**
+     * Get a user's private balance in Privacy Cash
+     *
+     * @param userKeypair - The user's reconstructed keypair
+     */
+    async getUserPrivateBalance(userKeypair) {
+        const sdk = await this.ensureInitialized();
+        const encryptionService = await this.createEncryptionService(sdk, userKeypair);
+        const utxos = await sdk.getUtxos({
+            connection: this.connection,
+            encryptionService,
+            publicKey: userKeypair.publicKey,
+            storage: this.storage,
+        });
+        const { lamports } = sdk.getBalanceFromUtxos(utxos);
+        return lamports;
+    }
+    /**
+     * Check if the SDK is properly loaded
+     */
+    async isLoaded() {
+        try {
+            await this.ensureInitialized();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Parse a base58-encoded private key into a Keypair
+     */
+    static parseKeypair(privateKeyBase58) {
+        const privateKeyBytes = bs58_1.default.decode(privateKeyBase58);
+        return web3_js_1.Keypair.fromSecretKey(privateKeyBytes);
+    }
+}
+exports.PrivacyCashService = PrivacyCashService;

package/dist/services/solana.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Solana RPC connection service
+ */
+import { Connection, PublicKey } from '@solana/web3.js';
+import { Config } from '../config.js';
+export declare class SolanaService {
+    private connection;
+    private networkName;
+    constructor(config: Config);
+    /**
+     * Get the Solana connection
+     */
+    getConnection(): Connection;
+    /**
+     * Get the network name
+     */
+    getNetwork(): string;
+    /**
+     * Check if RPC is connected by fetching the latest blockhash
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Get the latest blockhash with expiry info
+     */
+    getLatestBlockhash(): Promise<{
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+    /**
+     * Get balance for a public key
+     */
+    getBalance(publicKey: PublicKey): Promise<number>;
+    /**
+     * Send a signed transaction and confirm it
+     */
+    sendAndConfirmTransaction(signedTx: Buffer, options?: {
+        skipPreflight?: boolean;
+    }): Promise<string>;
+}

package/dist/services/solana.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Solana RPC connection service
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolanaService = void 0;
+const web3_js_1 = require("@solana/web3.js");
+class SolanaService {
+    connection;
+    networkName;
+    constructor(config) {
+        this.connection = new web3_js_1.Connection(config.solanaRpcUrl, {
+            commitment: 'confirmed',
+        });
+        this.networkName = config.solanaNetwork;
+    }
+    /**
+     * Get the Solana connection
+     */
+    getConnection() {
+        return this.connection;
+    }
+    /**
+     * Get the network name
+     */
+    getNetwork() {
+        return this.networkName;
+    }
+    /**
+     * Check if RPC is connected by fetching the latest blockhash
+     */
+    async isConnected() {
+        try {
+            await this.connection.getLatestBlockhash();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the latest blockhash with expiry info
+     */
+    async getLatestBlockhash() {
+        return this.connection.getLatestBlockhash('confirmed');
+    }
+    /**
+     * Get balance for a public key
+     */
+    async getBalance(publicKey) {
+        return this.connection.getBalance(publicKey);
+    }
+    /**
+     * Send a signed transaction and confirm it
+     */
+    async sendAndConfirmTransaction(signedTx, options) {
+        const signature = await this.connection.sendRawTransaction(signedTx, {
+            skipPreflight: options?.skipPreflight ?? false,
+            preflightCommitment: 'confirmed',
+        });
+        // Wait for confirmation
+        const latestBlockhash = await this.connection.getLatestBlockhash('confirmed');
+        await this.connection.confirmTransaction({
+            signature,
+            blockhash: latestBlockhash.blockhash,
+            lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+        }, 'confirmed');
+        return signature;
+    }
+}
+exports.SolanaService = SolanaService;

package/dist/utils/fetchWithTimeout.d.ts

@@ -0,0 +1,2 @@
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export declare function fetchWithTimeout(fetchFn: FetchLike, input: string, init: RequestInit | undefined, timeoutMs: number): Promise<Response>;

package/dist/utils/fetchWithTimeout.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithTimeout = fetchWithTimeout;
+async function fetchWithTimeout(fetchFn, input, init, timeoutMs) {
+    const controller = new AbortController();
+    const signal = controller.signal;
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const mergedInit = { ...init, signal };
+        return await fetchFn(input, mergedInit);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/utils/redactRpcUrl.d.ts

@@ -0,0 +1 @@
+export declare function redactRpcUrl(url: string): string;

package/dist/utils/redactRpcUrl.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactRpcUrl = redactRpcUrl;
+function redactRpcUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.host;
+    }
+    catch {
+        return '<invalid-url>';
+    }
+}

package/dist/utils/verifySolTransfer.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedTransactionWithMeta } from '@solana/web3.js';
+export type VerifySolTransferParams = {
+    signature: string;
+    expectedSource?: string;
+    expectedDestination: string;
+    minLamports?: number;
+};
+export type VerifySolTransferResult = {
+    signature: string;
+    observedLamports: number;
+    source: string;
+    destination: string;
+};
+/**
+ * Verify a finalized SOL transfer using a parsed Solana transaction.
+ *
+ * This is used to prove a claimed tx signature:
+ * - exists and succeeded
+ * - includes a SystemProgram transfer
+ * - moves lamports from expected source (optional) to expected destination
+ */
+export declare function verifySolTransferFromParsedTransaction(tx: ParsedTransactionWithMeta | null, params: VerifySolTransferParams): VerifySolTransferResult;

package/dist/utils/verifySolTransfer.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySolTransferFromParsedTransaction = verifySolTransferFromParsedTransaction;
+function isRecord(value) {
+    return !!value && typeof value === 'object';
+}
+function isSystemTransferInstruction(ix) {
+    if (!isRecord(ix))
+        return false;
+    if (ix.program !== 'system')
+        return false;
+    const parsed = ix.parsed;
+    if (!isRecord(parsed))
+        return false;
+    if (parsed.type !== 'transfer')
+        return false;
+    const info = parsed.info;
+    if (!isRecord(info))
+        return false;
+    if (typeof info.source !== 'string')
+        return false;
+    if (typeof info.destination !== 'string')
+        return false;
+    const lamports = info.lamports;
+    if (!(typeof lamports === 'number' || typeof lamports === 'string'))
+        return false;
+    return true;
+}
+function toLamports(value) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error('Invalid lamports value');
+    }
+    return Math.floor(n);
+}
+/**
+ * Verify a finalized SOL transfer using a parsed Solana transaction.
+ *
+ * This is used to prove a claimed tx signature:
+ * - exists and succeeded
+ * - includes a SystemProgram transfer
+ * - moves lamports from expected source (optional) to expected destination
+ */
+function verifySolTransferFromParsedTransaction(tx, params) {
+    if (!tx) {
+        throw new Error('Transaction not found');
+    }
+    if (tx.meta?.err) {
+        throw new Error('Transaction failed');
+    }
+    const { signature, expectedDestination, expectedSource, minLamports } = params;
+    const instructions = tx.transaction.message.instructions;
+    let observedLamports = 0;
+    let matchedSource = '';
+    for (const ix of instructions) {
+        if (!isSystemTransferInstruction(ix))
+            continue;
+        const source = ix.parsed.info.source;
+        const destination = ix.parsed.info.destination;
+        if (destination !== expectedDestination)
+            continue;
+        if (expectedSource && source !== expectedSource)
+            continue;
+        observedLamports += toLamports(ix.parsed.info.lamports);
+        if (!matchedSource)
+            matchedSource = source;
+    }
+    if (observedLamports <= 0) {
+        throw new Error('No matching SOL transfer found');
+    }
+    if (minLamports !== undefined && observedLamports < minLamports) {
+        throw new Error('Transfer amount below minimum');
+    }
+    return {
+        signature,
+        observedLamports,
+        source: expectedSource ?? matchedSource,
+        destination: expectedDestination,
+    };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@cedros/login-sidecar",
+  "version": "0.0.1",
+  "description": "Cedros Login sidecar service (Privacy Cash + Solana utilities)",
+  "main": "dist/index.js",
+  "scripts": {
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.98.0",
+    "@types/node-localstorage": "^1.3.3",
+    "bs58": "^6.0.0",
+    "express": "^4.21.2",
+    "node-localstorage": "^3.0.5",
+    "privacycash": "^1.1.11"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}