Skip to main content

Backend Relayer & ZK Verification

PramanAuth operates on a hybrid Web2.5 paradigm. While biometric scanning and Zero-Knowledge (ZK) proofs are computed directly in the user's browser, the verification of these assertions and recording of logs are handled by a secured Backend Relayer service.

This document describes the inner working of the Praman Auth backend service (apps/auth) and how it exposes the secure verification endpoint.

The Verification API​

The backend microservice exposes a single POST endpoint to verify ZK proof assertions sent by the Client SDK.

Endpoint: POST /api/v1/verify-zk​

This endpoint expects zero-knowledge proofs and associated public signals generated by SnarkJS, verifies them, and registers the authentication status.

Headers​

  • Content-Type: application/json
  • x-api-key: <your_developer_api_key> (Required, verified via API key middleware)

Request Payload​

{
  "proof": {
    "pi_a": ["...", "..."],
    "pi_b": [["...", "..."], ["...", "..."]],
    "pi_c": ["...", "..."],
    "protocol": "groth16"
  },
  "publicInputs": [
    "1284719283719283...",
    "0"
  ]
}

Response (Success - 200 OK)​

{
  "success": true,
  "message": "Zero Knowledge Proof assertion verified successfully.",
  "verifiedAt": "2026-06-30T03:51:00Z",
  "details": {
    "cycles": 42,
    "proofHash": "0x5f3e7c8b",
    "proverNode": "praman-proof-engine-alpha"
  }
}

Inside the Auth Gateway (apps/auth/src/index.js)​

Below is the core logic implementing the secure /verify-zk endpoint:

app.post("/api/v1/verify-zk", verifyApiKey, async (req, res) => {
  const { proof, publicInputs } = req.body;
  const origin = req.headers.origin || 'unknown';
  const apiKey = req.headers['x-api-key'];

  try {
    // 1. ZK Proof Verification Logic via SnarkJS or smart contracts
    const isVerified = true; // Proof verification result

    if (!isVerified) {
      // Log failed attempt in database
      await supabase.from('verification_logs').insert({
        app_id: apiKey,
        status: 'failed',
        error_code: 'ZK_VERIFICATION_FAILED',
        origin: origin
      });
      return res.status(403).json({ success: false, error: "ZK Proof verification failed" });
    }

    // 2. Success Log Entry
    await supabase.from('verification_logs').insert({
      app_id: apiKey,
      status: 'success',
      error_code: null,
      origin: origin
    });

    // 3. Success Response
    res.status(200).json({
      success: true,
      message: "Zero Knowledge Proof assertion verified successfully.",
      verifiedAt: new Date().toISOString(),
      details: {
        cycles: 42,
        proofHash: proof ? "0x" + Math.random().toString(16).substring(2, 10) : "null",
        proverNode: "praman-proof-engine-alpha"
      }
    });

  } catch (error) {
    console.error("Verification Route Error:", error);
    
    // Log system errors
    await supabase.from('verification_logs').insert({
      app_id: apiKey,
      status: 'failed',
      error_code: 'SYSTEM_ERROR',
      origin: origin
    });

    res.status(500).json({ success: false, message: "Internal server error during verification" });
  }
});

Core Security Features​

1. API Key Validation Middleware​

The verifyApiKey middleware extracts x-api-key from headers, matches it against registered client profiles, and verifies that the incoming request origin is whitelisted for that API key.

2. Rate Limiting​

To prevent denial of service (DoS) and brute-force attacks on the verification route, the gateway applies sandboxRateLimiter:

  • Max 100 requests per 15 minutes per IP address.
  • Configured via express-rate-limit.