KeepSake: Tokenized KYC Verifier SDK

This package is the official Verifier SDK for the KeepSake framework. It provides both a Node.js library and a powerful CLI to verify the authenticity and validity of a Tokenized KYC Credential (VC-JWT).

It works by checking a token's signature against the public key of its Issuer, which is retrieved from the decentralized Trust Layer. It embarks on the KeepSake infrastructure.

The Big Picture (Verification Flow)

+------------------+     +--------------------------+     +---------------------+
|                  |     |                          |     |                     |
|  Verifier's App  |     |   [KYC Verifier SDK]     |     |       Trust Layer   |
| (e.g. Mutual Fund)|     | (This Package)           |     | (Deployed on Render)|
|                  |     |                          |     |                     |
+------------------+     +--------------------------+     +---------------------+
         |                           |                           |
         |  1. User presents token   |                           |
         |-------------------------->|                           |
         |                           |  2. Check if revoked?     |
         |                           |-------------------------->|
         |                           |                           |  3. Return status
         |                           |<--------------------------|
         |                           |                           |
         |                           |  4. Get Issuer public key |
         |                           |-------------------------->|
         |                           |                           |  5. Return key
         |                           |<--------------------------|
         |                           |                           |
         |                           |  6. Verify signature (local)
         |                           |                           |
         |  7. Return "VERIFIED"     |                           |
         |<--------------------------|                           |
         |                           |                           |

Features

• Programmatic SDK: A simple KycVerifier class for use in your Node.js backend.
• Powerful CLI: Verify tokens or run a full demo right from your terminal.
• Strongly Typed: Full TypeScript support for all methods and objects.
• Trust Agnostic: Connects to any compatible Trust Layer (currently our keepsake-mock-trust-layer.onrender.com prototype).

Installation

npm install keepsake-verifier-sdk

User Guide: Programmatic (SDK)

Use the KycVerifier class in your backend service to verify tokens received from a user.

import { KycVerifier, VerificationResult } from 'keepsake-verifier-sdk';

// 1. Initialize the verifier with the URL of the Trust Layer
const verifier = new KycVerifier({
  trustLayerUrl: 'https://keepsake-mock-trust-layer.onrender.com'
});

// 2. Get the token from the user (e.g., in an API request)
const userToken = "eyJhbGciOiJFUzI1...IiwicGFuIjoiQUJDR...XJw";

// 3. Verify the token
async function verifyUser() {
  const result: VerificationResult = await verifier.verifyVcJwt(userToken);

  if (result.isValid) {
    console.log("✅ Verification Successful!");
    // The trusted, verified data is in the payload
    const kycData = result.payload.vc.credentialSubject;
    console.log("User's PAN:", kycData.pan);
    console.log("User's Name:", kycData.nameAsPerPan);
  } else {
    console.error("❌ Verification Failed:", result.error);
    // e.g., "Token is expired" or "Credential has been revoked"
  }
}

verifyUser();

User Guide: Command Line (CLI)

This package provides the kyc-verify command.

1. verify command

Verify a specific token string.

# You must pass the token string as an argument
npx keepsake-verifier-sdk verify "eyJhbGciOiJFUzI1...IiwicGFuIjoiQUJDR...XJw"

# You can optionally specify a different Trust Layer
npx keepsake-verifier-sdk verify <token> --trust-layer "http://localhost:3001"

Success Output:

$ npx keepsake-verifier-sdk verify ...
Verifying token using Trust Layer at: https://keepsake-mock-trust-layer.onrender.com...

✅ VERIFICATION SUCCESSFUL
-----------------------------
{
  "id": "did:example:cli-demo-user",
  "type": "PanVerification",
  "pan": "ABCDE1234F",
  "nameAsPerPan": "Rohan Kumar",
  "verificationSource": "InternalBankDB-NSDL-Simulated"
}

Failure Output:

$ npx keepsake-verifier-sdk verify ...
Verifying token using Trust Layer at: https://keepsake-mock-trust-layer.onrender.com...

❌ VERIFICATION FAILED
-------------------------
Credential has been revoked

2. demo command

This is the best way to test the live system. It runs a full, end-to-end loop:

1. Calls the Issuer Service to mint a new PAN token.
2. Takes that new token and immediately sends it to the Trust Layer for verification.

# Just run 'demo' to test the deployed cloud services
npx keepsake-verifier-sdk demo

# You can also point it at your local services
npx keepsake-verifier-sdk demo \
  --issuer-url "http://localhost:3002" \
  --trust-layer "http://localhost:3001"

Demo Output:

$ npx keepsake-verifier-sdk demo
🚀 Starting KYC End-to-End Demo...

[1/3] Ensuring Issuer is registered at: https://keepsake-issuer-service.onrender.com...
Issuer is already registered. Proceeding.

[2/3] Minting a new PAN token from: https://keepsake-issuer-service.onrender.com...
Successfully minted new token!
Token: eyJhbGciOiJFUzI1NiIsInR5cCI6In...

[3/3] Verifying the new token against: https://keepsake-mock-trust-layer.onrender.com...
Verifying token using Trust Layer at: https://keepsake-mock-trust-layer.onrender.com...

✅ VERIFICATION SUCCESSFUL
-----------------------------
{
  "id": "did:example:cli-demo-user",
  "type": "PanVerification",
  "pan": "ABCDE1234F",
  "nameAsPerPan": "Rohan Kumar",
  "verificationSource": "InternalBankDB-NSDL-Simulated"
}

Future Scope

This prototype is the foundation for a full production system. Future improvements will include:

• NBF Integration: Replacing the Mock Trust Layer with a client for India's National Blockchain Framework (NBF).
• ZKP Support: Adding methods to verify Zero-Knowledge Proofs (e.g., verifyAgeProof()) for privacy-preserving verification.
• Schema Validation: The SDK will automatically validate the credentialSubject against the official JSON schemas.
• Advanced Caching: A local caching layer for Issuer public keys to reduce latency.

License

MIT License - see LICENSE file for details.

Contributing

write email to [email protected]