title	SDK Reference
sidebar_label	SDK Reference
sidebar_position	3

@praman-network/sdk

PramanAuth is a decentralized Identity-as-a-Service (IaaS) SDK providing privacy-preserving, Zero-Knowledge (ZK) biometric authentication for Web3 applications. Powered by a hybrid Web2.5 architecture, PramanAuth secures client-to-backend communication via API Key authentication and Origin Whitelisting, enabling gasless biometric verification for end-users.

---

Why PramanAuth?

Modern authentication solutions force a trade-off between user convenience and security. PramanAuth bridges this gap by combining decentralized biometrics with zero-knowledge proofs.

🌟 What's New in Version 2.0

• Web2.5 Hybrid Auth (Email OTP + Embedded Wallets): Fully integrated with @privy-io/react-auth. Users can now onboard seamlessly using just an Email address. An embedded non-custodial wallet is automatically provisioned behind the scenes—no seed phrases, no MetaMask required to get started.
• Progressive Web3 Account Linking: A dedicated Security Dashboard allows users to start as Web2 natives (Email) and later link their existing Web3 hardware wallets or MetaMask accounts to the same biometric identity.
• Strict Sybil Resistance: Decreased face vector variance bounds to enforce a strict 1-User = 1-Account mapping, effectively blocking multi-account Sybil exploits on-chain regardless of whether the user logs in via Email or MetaMask.
• Dynamic Face Alignment UX: Implemented real-time visual feedback (Red/Green frame tracking) ensuring perfect facial alignment before Groth16 ZK-Proof processing begins.
• In-App Identity Recovery: A native, on-platform support dashboard for resolving KYC/identity loss due to lost hardware access or facial alterations (accidents/surgery).
• Cyberpunk Cyan Theme: A fully overhauled visual identity matching the Praman brand, replacing the legacy purple gradients with a vibrant neon Cyan/Teal aesthetic.

Core Architecture & The Web2.5 Flow

PramanAuth bridges the Web2 user experience with Web3 cryptography:

1. Frictionless Entry (Privy): User requests an OTP to their email. Upon verification, an embedded EVM wallet is generated invisibly.
2. Biometric Anchoring (Praman ZK): The user scans their face. The face descriptor is mapped uniquely to the embedded wallet.
3. Zero Biometric Leakage: No raw biometric data (images, videos, or raw face descriptors) is ever sent to or stored on any centralized server. Biometric templates are quantized, hashed, and encrypted client-side using wallet signatures before being archived on IPFS.
4. Browser-Side ZK Verification: Biometric comparisons are computed locally in the user's browser using client-side Groth16 ZK-SNARK Proving (via SnarkJS). Raw biometrics remain completely private, and only the ZK proof is dispatched for verification.
5. Gasless User Experience: All blockchain writes, gas sponsorship, and IPFS pinning are managed securely by the Backend Relayer. Users get a fast, signature-based sign-in experience with zero transaction costs.

---

Installation & Prerequisites

To prevent compilation and runtime helpers resolution issues in bundlers, tslib is required as a peer dependency of @praman-network/sdk. Install both packages using npm:

npm install @praman-network/sdk tslib

Polyfill Setup for Bundlers (Vite)

Web3 libraries depend on Node.js built-ins. If you are using Vite, install Node polyfills to avoid Buffer is not defined or global is not defined runtime errors:

1. Install the polyfill plugin:

npm install vite-plugin-node-polyfills --save-dev

2. Update vite.config.ts or vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    react(),
    // Ye plugin global, Buffer, process sabko browser me available kar dega
    nodePolyfills({
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
  optimizeDeps: {
    include: ['@praman-network/sdk', '@lit-protocol/lit-node-client', 'tslib']
  },
  build: {
    commonjsOptions: {
      transformMixedEsModules: true
    }
  }
})

---

SDK Initialization

The SDK client must be initialized once at the entry point of your frontend application. The client stores the configured API key and backend service endpoint securely within the SDK instance state for subsequent API calls.

Initialize using one of the following methods:

Method 1: Simple Initialization (Default Production)

Suitable for standard production applications. Initializes the client pointing to the global Praman production relayer gateway (https://api.praman.network):

import { initPraman } from '@praman-network/sdk';

// Initializes with production relayer defaults
const praman = initPraman("pm_live_your_api_key");

Method 2: Custom Configuration (Local/Custom Backend)

Required when testing integrations locally against an Express microservice backend (e.g., http://localhost:5050) or using a customized deployment configuration:

import { initPraman } from '@praman-network/sdk';

const praman = initPraman({
  apiKey: "pm_dev_your_api_key",
  network: "polygon-amoy",
  backendUrl: "http://localhost:5050", // Custom/Local relayer endpoint
  livenessLevel: "standard"            // 'strict' | 'standard' | 'off'
});

---

Framework Support

The @praman-network/sdk is designed to be framework-agnostic.

1. Next.js (App Router)

Since Next.js App Router renders pages server-side by default, SDK components and hooks must be constrained to the client boundary using the 'use client' directive.

Create a wrapper client component or add the directive to the top of your layout/page:

'use client';

import React, { useEffect } from 'react';
import { initPraman } from '@praman-network/sdk';

// Initialize the SDK inside client components
const praman = initPraman(
  process.env.NEXT_PUBLIC_PRAMAN_API_KEY || '',
  process.env.NEXT_PUBLIC_PRAMAN_BACKEND_URL // Will fall back to production if undefined
);

export default function AuthPage() {
  // Client-side authentication logic
  return (
    <div>
      <button onClick={() => praman.loginWithPopup()}>Sign In</button>
    </div>
  );
}

2. Vanilla JS / Single Page Applications (SPAs)

For custom scripts or simple frontend integrations, import from the compiled CommonJS or ES build module:

import { initPraman, verifyZKProof } from '@praman-network/sdk';

// Initialize client
initPraman("pm_dev_key", "http://localhost:5050");

// Dispatch proof verification
async function authenticateUser(address, proof, signals) {
  try {
    const result = await verifyZKProof(address, proof, signals);
    if (result.success) {
      console.log("Authenticated successfully!");
    }
  } catch (error) {
    console.error("Verification failed:", error.message);
  }
}

---

Security Architecture

To protect the verification relay against Sybil attacks and credential leaks, communication is locked down via two mechanisms configured in your Developer Dashboard:

1. API Key Validation (x-api-key): The SDK automatically transmits your configured API key in the request headers on all verification API calls.
2. Origin Whitelisting: The security relayer checks incoming request headers (origin and referer). Requests from non-whitelisted domains are strictly rejected by the backend to prevent API key usage outside authorized apps.

sequenceDiagram
    autonumber
    participant App as Developer App (Browser)
    participant SDK as Praman Client SDK
    participant Relayer as Security Relayer (apps/auth)
    participant Contract as FaceRegistry (Polygon)

    App->>SDK: initPraman(apiKey, [backendUrl])
    App->>SDK: verifyZKProof(userAddress, proof, publicSignals)
    Note over SDK: Retrieve stored apiKey & backendUrl
    SDK->>Relayer: POST /api/v1/verify-zk<br/>Headers: { x-api-key, origin }
    Note over Relayer: verifyApiKey & verifyOrigin Middleware<br/>Validate API Key & Origin whitelist
    Relayer->>Contract: Validate ZK signals & state
    Contract-->>Relayer: On-chain Registry Status
    Relayer-->>SDK: Return JSON Result (success: true)
    SDK-->>App: Resolve verification response

Loading

---

Verification & Production Hardening

Environment Guard

The SDK contains an automated Environment Guard that monitors execution modes.

Warning

Environment Strict Mode: In production builds (process.env.NODE_ENV === 'production' or import.meta.env.MODE === 'production'), the SDK enforces a strict, hard-fail security policy. If ZK proof generation fails due to browser memory limits, asset delivery problems, or system timeouts, authentication fails immediately. Mock proofs are strictly rejected in production.

Backend Token Filtering

When integrating PramanAuth within your own server backend, always inspect and filter claims:

Important

Mock Token Filter: Always check the is_mock flag in the decoded JWT payload on your backend. If is_mock: true is detected in a production build, your backend must reject the authentication session immediately to prevent mock-bypass exploits.

import { getPramanClient } from '@praman-network/sdk';

const praman = getPramanClient();
const result = praman.verifyToken(receivedToken);

if (!result.valid) {
  throw new Error("Invalid cryptographic session token");
}

if (result.payload.is_mock && process.env.NODE_ENV === 'production') {
  throw new Error("Unauthorized: Mock tokens are restricted in production environments");
}

---

Troubleshooting

1. Why does my registration fail with "Biometric face identity already registered"?

The Polygon Amoy smart contract registry enforces Sybil resistance by hashing face descriptors. If a user's biometric baseline matches an already registered identity, the contract rejects the transaction. For development, use mock flags or register with a unique face baseline.

2. CORS Errors connecting to Backend Relayer

Verify that your origin domain (e.g. http://localhost:5173) is listed in the allowed origins configuration of your Express backend relayer or your Developer Dashboard settings.

3. ZK Proof Generation crashes or times out

Ensure that WebAssembly support is enabled in the target browser environment. WebAssembly is required to execute the client-side snarkjs prover efficiently.

---

Changelog

• v2.0.0 (Major Update)
  • Added Strict Sybil Resistance (1 decimal quantization) in getStableVector.
  • Introduced Dynamic Face Alignment UX during webcam capture.
  • Released the Security Dashboard for Web2 to Web3 Progressive Account Linking.
  • Added the integrated Support Dashboard for biometric identity recovery.
  • Overhauled global UI/UX to the Praman Cyan/Teal theme.
• v0.1.10
  • Added support for direct API key verification headers and custom backend relay routing.
  • Implemented standalone verifyZKProof and loginWithPraman exports.
  • Moved tslib to peerDependencies.
• v0.1.2
  • Implemented getStableVector biometric stabilization layer.
• v0.1.0
  • Initial release with Lit Protocol encryption, IPFS enclaves, and basic face scanning.