Cr3dentials SDK

Enterprise-grade SDK for secure banking verification with CDP sandbox automation and verified proof generation.

Overview

The Cr3dentials SDK provides a secure way to verify banking transactions through browser automation. It uses Chrome DevTools Protocol (CDP) to control a browser session, capture banking API responses, and generate cryptographically signed proofs.

Key Features:

• Secure credential handling (credentials never leave the client)
• Automated login flows with steps fetched from backend
• Real-time banking API capture and transaction parsing
• Cryptographic proof generation with browser attestation
• Encrypted evidence for backend verification

Installation

npm install cr3dentials-sdk
# or
pnpm add cr3dentials-sdk

Requirements:

• Node.js 20.x or higher
• Chromium browser (installed automatically by Playwright)

Quick Start

import { Cr3dentialsSDK } from "cr3dentials-sdk";

const sdk = new Cr3dentialsSDK({
  apiKey: "your-api-key",
  headless: false, // Set true for production
  verbose: true,
});

try {
  // 1. Initialize browser
  await sdk.initBrowser();

  // 2. Execute login and capture transactions
  const result = await sdk.login({
    platform: "providus_bank",
    credentials: {
      username: "your-username",
      password: "your-password",
    },
    verificationCriteria: {
      amount: 100,
      recipient: "JOHN DOE",
      transactionType: "debit",
    },
  });

  if (result.success) {
    console.log(`Captured ${result.transactions?.length} transactions`);

    if (result.verification?.found) {
      console.log("Transaction verified!");
    }

    // 3. Generate and submit proof
    await sdk.initProofGenerator();
    const proof = await sdk.generateProof({
      username: "[email protected]",
      platform: "providus_bank",
    });

    const response = await sdk.submitProof(proof);
    console.log(`Proof ID: ${response.proofId}`);
  }
} finally {
  await sdk.close();
}

How It Works

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Cr3dentials SDK                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │  API Client  │  │ CDP Sandbox  │  │   Proof Generator     │ │
│  │              │  │              │  │                       │ │
│  │ • Auth       │  │ • Browser    │  │ • Attestation         │ │
│  │ • Login Flow │  │ • Network    │  │ • Encryption          │ │
│  │ • Proof API  │  │ • Capture    │  │ • Signing             │ │
│  └──────────────┘  └──────────────┘  └───────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                     Platform Strategies                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │Providus Bank │  │ Custom Bank  │  │      ...more         │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Flow

1. Initialize: SDK connects to Cr3dentials backend and launches browser
2. Login Flow: Backend provides login steps, SDK executes them locally
3. Capture: Network monitor captures banking API responses
4. Parse: Platform strategy extracts transactions from responses
5. Verify: SDK checks if target transaction exists
6. Prove: Generate cryptographic proof with attestation
7. Submit: Send encrypted proof to backend for verification

Configuration

interface Cr3dentialsSDKConfig {
  /** Required: API key for authentication */
  apiKey: string;

  /** Request timeout in ms (default: 30000) */
  timeout?: number;

  /** Number of retry attempts (default: 3) */
  retryAttempts?: number;

  /** Run browser in headless mode (default: false) */
  headless?: boolean;

  /** Enable verbose logging (default: false) */
  verbose?: boolean;

  /** Additional sandbox configuration */
  sandboxConfig?: Partial<SandboxConfig>;

  /** Custom logger instance */
  logger?: ILogger;
}

API Reference

Cr3dentialsSDK

Browser Methods

| Method | Description | |--------|-------------| | initBrowser() | Initialize CDP sandbox browser session | | getSandbox() | Get the underlying CDP sandbox instance | | getPage() | Get Playwright page object | | isBrowserInitialized() | Check if browser is active | | close() | Close browser and cleanup resources |

Login Methods

| Method | Description | |--------|-------------| | login(config) | Execute platform login flow | | getTransactions() | Get captured transactions | | getCapturedApiData() | Get all captured API responses | | clearCapturedData() | Clear captured data |

Proof Methods

| Method | Description | |--------|-------------| | initProofGenerator() | Initialize proof generator (fetches public key) | | generateProof(params) | Generate verified proof payload | | submitProof(proof) | Submit proof to backend | | generateAndSubmitProof(params) | Generate and submit in one call |

LoginConfig

interface LoginConfig {
  /** Platform identifier (e.g., "providus_bank") */
  platform: string;

  /** Login credentials */
  credentials: {
    username?: string;
    email?: string;
    password: string;
    [key: string]: string | undefined;
  };

  /** Override login URL */
  url?: string;

  /** Transaction verification criteria */
  verificationCriteria?: TransactionVerification;

  /** Custom timeout for this login */
  timeout?: number;
}

TransactionVerification

interface TransactionVerification {
  /** Transaction amount to match */
  amount?: number | string;

  /** Recipient name (partial match, case-insensitive) */
  recipient?: string;

  /** Order reference (partial match) */
  orderRef?: string;

  /** Filter by transaction type */
  transactionType?: "debit" | "credit";

  /** Date range filter */
  dateRange?: {
    from?: string;  // Format: DD/MM/YYYY or ISO
    to?: string;
  };
}

VerifiedProofResponse

interface VerifiedProofResponse {
  success: boolean;
  proofId: string;
  backendVerified: boolean;
  verificationMatch: boolean;
  attestationScore: number;
  fraudAnalysis: {
    riskScore: number;
    riskLevel: string;
    recommendation: string;
  };
}

Platform Strategies

Each supported bank has a platform strategy that defines login flow handling and transaction parsing.

Built-in Strategies

| Platform ID | Bank | Country | |------------|------|---------| | providus_bank | Providus Bank | Nigeria |

Creating Custom Strategies

import {
  BasePlatformStrategy,
  PlatformStrategyFactory,
  type Transaction
} from "cr3dentials-sdk";

class MyBankStrategy extends BasePlatformStrategy {
  readonly platformId = "my_bank";
  readonly displayName = "My Bank";
  readonly defaultTimeout = 45000;

  getLoginUrl(): string {
    return "https://my-bank.com/login";
  }

  getBankingApiPatterns(): RegExp[] {
    return [
      /\/api\/v1\/transactions/i,
      /\/api\/v1\/accounts/i,
    ];
  }

  parseTransactions(responseBody: any, url: string): Transaction[] {
    if (Array.isArray(responseBody?.data)) {
      return responseBody.data.map((tx: any) => ({
        traDate: tx.date,
        desc: tx.description,
        debitAmnt: tx.type === "debit" ? tx.amount : "",
        creditAmnt: tx.type === "credit" ? tx.amount : "",
      }));
    }
    return [];
  }
}

// Register the strategy
PlatformStrategyFactory.register(new MyBankStrategy());

Error Handling

import {
  Cr3dentialsError,
  ApiError,
  AuthenticationError,
  ProofError,
  ProofSubmissionError
} from "cr3dentials-sdk";

try {
  await sdk.login({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // API key invalid or expired
    console.error("Auth failed:", error.message);
  } else if (error instanceof ApiError) {
    // HTTP error from backend
    console.error(`API Error ${error.statusCode}:`, error.message);
  } else if (error instanceof ProofSubmissionError) {
    // Proof submission failed
    console.error("Proof error:", error.message);
  } else if (error instanceof Cr3dentialsError) {
    // General SDK error
    console.error("SDK error:", error.message);
  }
}

Module Exports

The SDK provides multiple entry points for different use cases:

// Main SDK (recommended)
import { Cr3dentialsSDK } from "cr3dentials-sdk";

// Direct API client access
import { PartnerApiClient } from "cr3dentials-sdk/api";

// CDP Sandbox only
import { CDPSandbox, createCDPSandbox } from "cr3dentials-sdk/sandbox";

// Platform strategies
import {
  BasePlatformStrategy,
  PlatformStrategyFactory
} from "cr3dentials-sdk/strategies";

// Proof system
import {
  VerifiedProofGenerator,
  AttestationCollector,
  EvidenceEncryptor
} from "cr3dentials-sdk/proof";

// Types only
import type {
  Transaction,
  TransactionVerification,
  VerifiedProofPayload
} from "cr3dentials-sdk/types";

// Errors
import { ApiError, ProofError } from "cr3dentials-sdk/errors";

Environment Variables

# Required
CR3DENTIALS_API_KEY=your-api-key

# For testing/examples
BANK_USERNAME=your-bank-username
BANK_PASSWORD=your-bank-password

Examples

See the examples folder for complete usage examples:

• basic-usage.ts - Complete flow demonstration

Run the example:

pnpm example

Security

• Credentials stay local: Login credentials are never sent to Cr3dentials servers
• Encrypted evidence: Banking data is encrypted with backend public key before transmission
• Browser attestation: Proofs include TLS, timing, screenshot, and DOM attestation
• HMAC signatures: All proof payloads are cryptographically signed

License

MIT

Support

• GitHub Issues
• Documentation