Nagad SDK Monorepo

Zero-runtime-dependency, open-source Nagad Payment Gateway SDK for Node.js, Web, and Mobile.

---

Disclaimer

This repository is an unofficial, community-driven open-source project. It is not affiliated with, endorsed by, or sponsored by Nagad or Third Wave Technologies Limited.

---

Packages

Package	Description	Version	Links
nagad-server	Server SDK with zero runtime dependencies, atomic SessionStores, and framework adapters	0.1.0
nagad-client	Headless client SDK for React, React Native, Vue, Svelte, Angular, and Vanilla JS	0.1.0
nagad-simulator	Offline mock Nagad server with throwaway test RSA keys for deterministic CI	0.1.0	Internal test package (private)

---

Feature status

Feature	Status	Evidence
Session Initialization (/check-out/initialize)	Experimental	automated tests against the local simulator; NOT TESTED against the live gateway (sandbox access needs onboarding credentials)
Order Placement & Complete (/check-out/complete)	Experimental	automated tests against the local simulator; NOT TESTED against the live gateway
Payment Verification (/verify/payment)	Experimental	automated tests against the local simulator incl. tampered amount, order id and merchant id; NOT TESTED against the live gateway
Payment Status Check	Experimental	automated tests against the local simulator
Native Node.js Crypto Provider (OpenSSL 3)	Beta	golden-vector tests; passes on Node 22 and 24; on Node 18.20 and 20.20 (OpenSSL 3.0) node:crypto rejects RSA PKCS#1 v1.5 decryption, so those tests are skipped there
Legacy SHA1withRSA Signature Support	Experimental	unit tests only; not validated with a real SHA-1 account
Pure-JS PKCS#1 v1.5 decryption (automatic fallback)	Beta	tests on Node 20 (full suite) and a full create+verify smoke run on Node 18.20.8; compared with node:crypto ciphertexts; NOT TESTED against the live gateway
Edge / Serverless Runtimes (Cloudflare Workers, Vercel Edge)	Planned	Not supported: WebCrypto has no RSAES-PKCS1-v1_5
Memory Session Store (Dev-Only)	Beta	automated tests against the local simulator (race and replay tests)
Redis Session Store (Distributed Lua CAS)	Beta	automated tests against the local simulator with a real Redis service in CI
Upstash / Generic KV Session Store	Experimental	unit tests with a fake KV
Express Adapter	Beta	tests inside real Express (with and without a body parser) through create and verify
Next.js App Router Adapter	Beta	tests: route handler answers create; web-standard Request/Response
Hono Adapter	Beta	tests inside real Hono (node-server) through create and verify
React Hook (useNagadCheckout)	Beta	behaviour tests: verify-before-success contract

Quickstart

1. Server (nagad-server)

npm install nagad-server

import { createNagad } from "nagad-server";

export const nagad = createNagad({
  merchantId: process.env.NAGAD_MERCHANT_ID!,
  merchantPrivateKey: process.env.NAGAD_PRIVATE_KEY!,
  pgPublicKey: process.env.NAGAD_PG_PUBLIC_KEY!,
  baseUrl: process.env.NAGAD_BASE_URL!,
});

2. Client (nagad-client)

npm install nagad-client

import { useNagadCheckout } from "nagad-client/react";

function Checkout() {
  const { initiate, isLoading } = useNagadCheckout();
  // ...
}

---

Documentation & Architecture

• Technical Architecture & Design (DESIGN.md): Deep dive into the cryptographic protocol, RSA PKCS#1 v1.5 handling, CVE-2023-46809 mitigation, and distributed state machines.
• Security Policy & Threat Model (SECURITY.md): Threat vectors, verification rules, and vulnerability reporting.
• Release Checklist & Hardening Gate (RELEASE_CHECKLIST.md): Production go/no-go audit, dogfood rollout plan, and publication commands.
• Interactive Documentation Website: Guides, tokenized palettes, and compatibility matrices.

---

Security & Verification

• Full History Gitleaks Clean: Scanned across all commits; zero secrets, real keys, or confidential IPs exist in git.
• Marvin / Bleichenbacher Mitigation: NodeCryptoProvider.checkCapability() validates host runtime OpenSSL implicit rejection at boot.
• Types Resolution Modes: 100% green on @arethetypeswrong/cli for node10, node16, nodenext, and bundler.
• Deterministic Cryptographic Tests: RSA signing and encryption are covered by golden-vector tests against the bundled local simulator. Not yet validated against the live gateway.

---

License

MIT © Md Tanvir Ahamed Shanto

---

Developed by TA Shanto · npm · GitHub