{"_id":"@awth/pq-jwt","_rev":"4-cecccb7a7193235a502096c6fc390855","name":"@awth/pq-jwt","dist-tags":{"latest":"0.1.4"},"versions":{"0.0.1":{"name":"@awth/pq-jwt","version":"0.0.1","keywords":["jwt","post-quantum","cryptography","security","pqc","quantum-resistant"],"author":"","license":"MIT","_id":"@awth/pq-jwt@0.0.1","maintainers":[{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"}],"dist":{"shasum":"6657eb71a2be646978dee887cc329b90dd405d33","tarball":"https://registry.npmjs.org/@awth/pq-jwt/-/pq-jwt-0.0.1.tgz","fileCount":3,"integrity":"sha512-Sa297JJbq5Ymz76EnuXjiXBD5OH4tEJvlBI7uj66pPkF6bst7ujfXuNABefykHOIrRxILR/hCOBw/Rr8p7o08Q==","signatures":[{"sig":"MEUCIHfPXXnb3/ZxfE7Mra5QHza6+mGqovyXCHmrFZSxM+tXAiEA2sWrIPfDQEaqXgM1laHRFx+OY5Sv/eLaDLtGHB2ICK8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2052},"main":"./src/index.ts","type":"module","module":"./src/index.ts","exports":{".":{"import":"./src/index.ts","require":"./src/index.ts"}},"gitHead":"3f327d097c5ff31b3cc929d482defbd91379fad0","scripts":{"dev":"bun run ./src/index.ts"},"_npmUser":{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"},"repository":{"url":"","type":"git"},"_npmVersion":"11.6.1","description":"Post-Quantum JWT implementation - Placeholder package","directories":{},"_nodeVersion":"24.10.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pq-jwt_0.0.1_1762595467380_0.38017174056410497","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@awth/pq-jwt","version":"0.1.0","keywords":["jwt","post-quantum","cryptography","security","pqc","quantum-resistant","ml-dsa","fips-204","dilithium","lattice","nist","typescript","bun"],"author":{"url":"https://x.com/MKSingh_Dev","name":"MKSingh"},"license":"MIT","_id":"@awth/pq-jwt@0.1.0","maintainers":[{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"}],"homepage":"https://github.com/MKSinghDev/pq-jwt-ts#readme","bugs":{"url":"https://github.com/MKSinghDev/pq-jwt-ts/issues"},"dist":{"shasum":"ad2c428161cd73d1613a3f80c6c5013a13120b66","tarball":"https://registry.npmjs.org/@awth/pq-jwt/-/pq-jwt-0.1.0.tgz","fileCount":9,"integrity":"sha512-c7366rUZXyDp6zndNnqLbctNZc4mcmXP6CtqRjVcs3pE1FCEnoH3aNUoqXHvEw7c7nRpgiZ+Sg2RZidZoGGp8A==","signatures":[{"sig":"MEUCIQCzIb8EVuhyqWwXWTVt/eIcSQOUUzqEottMvPSTY2LL8AIgAWXGWwNxBRZEKX0vm+zJkL8oGYfdw38qXZb9z2/L778=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45792},"main":"./src/index.ts","type":"module","types":"./src/index.ts","module":"./src/index.ts","engines":{"bun":">=1.0","node":">=18"},"exports":{".":{"types":"./src/index.ts","import":"./src/index.ts","require":"./src/index.ts"}},"gitHead":"b001ef025744d8dda53a6ef2f40c32f57e22884a","scripts":{"dev":"bun run ./src/index.ts","test":"bun test"},"_npmUser":{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"},"repository":{"url":"git+https://github.com/MKSinghDev/pq-jwt-ts.git","type":"git"},"_npmVersion":"11.6.1","description":"Post-Quantum JWT implementation using ML-DSA (FIPS 204) signatures for TypeScript/JavaScript","directories":{},"_nodeVersion":"24.10.0","dependencies":{"uuid":"^13.0.0","@noble/post-quantum":"^0.5.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pq-jwt_0.1.0_1762607739335_0.402883103105627","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@awth/pq-jwt","version":"0.1.3","keywords":["jwt","post-quantum","cryptography","security","pqc","quantum-resistant","ml-dsa","fips-204","dilithium","lattice","nist","typescript","bun"],"author":{"url":"https://x.com/MKSingh_Dev","name":"MKSingh"},"license":"MIT","_id":"@awth/pq-jwt@0.1.3","maintainers":[{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"}],"homepage":"https://github.com/MKSinghDev/pq-jwt-ts#readme","bugs":{"url":"https://github.com/MKSinghDev/pq-jwt-ts/issues"},"dist":{"shasum":"f9287ce79c0774b6a67bbfc372c86dbf44bfba6f","tarball":"https://registry.npmjs.org/@awth/pq-jwt/-/pq-jwt-0.1.3.tgz","fileCount":20,"integrity":"sha512-C/3y22vggCVcfJx/Nb53lMwZHyXLY/qEFyDb0dnvIpUY0N+Z63xh+rwyiems3K7I3hBkPtieIWNsmnFBhfYodQ==","signatures":[{"sig":"MEQCIA8jTcUYZKXHdXnlzUARrtmFqceOX5iBf7RCpOHHzKkVAiBP9dRlz/aY+nmX23i9rJAxggFiSyx6OMIQvWssYR5BUg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49727},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"bun":">=1.0","node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"317e7d6851cff0e6b8786f86d383381da8635d92","scripts":{"dev":"bun run ./src/index.ts","test":"bun test","build":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"},"repository":{"url":"git+https://github.com/MKSinghDev/pq-jwt-ts.git","type":"git"},"_npmVersion":"11.6.1","description":"Post-Quantum JWT implementation using ML-DSA (FIPS 204) signatures for TypeScript/JavaScript","directories":{},"_nodeVersion":"24.10.0","dependencies":{"uuid":"^13.0.0","@noble/post-quantum":"^0.5.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pq-jwt_0.1.3_1762611614412_0.8186155352639277","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@awth/pq-jwt","version":"0.1.4","description":"Post-Quantum JWT implementation using ML-DSA (FIPS 204) signatures for TypeScript/JavaScript","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build","test":"bun test","dev":"bun run ./src/index.ts"},"keywords":["jwt","post-quantum","cryptography","security","pqc","quantum-resistant","ml-dsa","fips-204","dilithium","lattice","nist","typescript","bun"],"author":{"name":"MKSingh","url":"https://x.com/MKSingh_Dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/MKSinghDev/pq-jwt-ts.git"},"dependencies":{"@noble/post-quantum":"^0.5.2","uuid":"^13.0.0"},"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"engines":{"node":">=18","bun":">=1.0"},"gitHead":"800d8f308738154bb59c91b97e1a697dd1d8ea1e","_id":"@awth/pq-jwt@0.1.4","bugs":{"url":"https://github.com/MKSinghDev/pq-jwt-ts/issues"},"homepage":"https://github.com/MKSinghDev/pq-jwt-ts#readme","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-RsGgnn4M4MEGa72h3UWxh1fTbk8P3OxIVv0RX6pqp3uNZ268+DcDsSc9Snmi2H2EBnRm7qwv5nOT3htaqfLm3Q==","shasum":"8244eb938c791dbfcfa98031fea440d3e16a311b","tarball":"https://registry.npmjs.org/@awth/pq-jwt/-/pq-jwt-0.1.4.tgz","fileCount":20,"unpackedSize":49787,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH4gjprY4gB6CitapZdSCSNKqRsG30TC/H7Yg69xET7zAiA2XJOuMKOIkTawtz67CphMpABwK2kWscEOQVIECwcNdA=="}]},"_npmUser":{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"},"directories":{},"maintainers":[{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pq-jwt_0.1.4_1762612005884_0.6696238302707609"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-08T09:51:07.171Z","modified":"2025-11-08T14:26:46.279Z","0.0.1":"2025-11-08T09:51:07.576Z","0.1.0":"2025-11-08T13:15:39.536Z","0.1.3":"2025-11-08T14:20:14.618Z","0.1.4":"2025-11-08T14:26:46.063Z"},"bugs":{"url":"https://github.com/MKSinghDev/pq-jwt-ts/issues"},"author":{"name":"MKSingh","url":"https://x.com/MKSingh_Dev"},"license":"MIT","homepage":"https://github.com/MKSinghDev/pq-jwt-ts#readme","keywords":["jwt","post-quantum","cryptography","security","pqc","quantum-resistant","ml-dsa","fips-204","dilithium","lattice","nist","typescript","bun"],"repository":{"type":"git","url":"git+https://github.com/MKSinghDev/pq-jwt-ts.git"},"description":"Post-Quantum JWT implementation using ML-DSA (FIPS 204) signatures for TypeScript/JavaScript","maintainers":[{"name":"badgerbloke","email":"CAMukeshKumarSingh@gmail.com"}],"readme":"# 🔐 @awth/pq-jwt\n\n**Post-Quantum JWT** - A quantum-resistant JWT implementation using ML-DSA (Module-Lattice Digital Signature Algorithm) signatures for TypeScript/JavaScript.\n\n> 🛡️ **Future-proof your authentication** - Protect your JWTs against quantum computer attacks with NIST-standardized post-quantum cryptography.\n\n## 🌟 Features\n\n- ✅ **Quantum-Resistant** - Uses ML-DSA (FIPS 204) signatures that remain secure even against quantum attacks\n- ✅ **Multiple Security Levels** - Choose from ML-DSA-44, ML-DSA-65, or ML-DSA-87 based on your needs\n- ✅ **Standards Compliant** - JWT format following RFC 7519\n- ✅ **TypeScript-First** - Full TypeScript support with comprehensive type definitions\n- ✅ **Flexible API** - Simple functions and advanced Builder patterns\n- ✅ **Mandatory JTI** - Built-in UUID v7 for session management with large JWTs\n- ✅ **Zero Config** - Works out of the box with Bun, Node.js, and browsers\n- ✅ **Well Tested** - Comprehensive test coverage\n- ✅ **Lightweight** - Minimal dependencies (@noble/post-quantum + uuid)\n\n## 📦 Installation\n\n```bash\n# Using Bun (recommended)\nbun add @awth/pq-jwt\n\n# Using npm\nnpm install @awth/pq-jwt\n\n# Using yarn\nyarn add @awth/pq-jwt\n\n# Using pnpm\npnpm add @awth/pq-jwt\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { generateKeypair, sign, verify, MlDsaAlgo } from \"@awth/pq-jwt\";\n\n// 1. Generate a keypair\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\n\n// 2. Create and sign a JWT\nconst now = Math.floor(Date.now() / 1000);\nconst { jwt, publicKey: pubKey, jti } = await sign(\n  MlDsaAlgo.Dsa65,\n  \"https://myapp.com\",      // Issuer\n  now + 3600,                // Expires in 1 hour\n  privateKey\n);\n\nconsole.log(\"JWT:\", jwt);\nconsole.log(\"JWT ID (jti):\", jti);\n\n// 3. Verify the JWT\nconst payload = await verify(jwt, publicKey, \"https://myapp.com\");\nconsole.log(\"Verified payload:\", payload);\n\nconsole.log(\"✓ JWT verified successfully!\");\n```\n\n## 📚 Usage Examples\n\n### Basic Authentication Token\n\n```typescript\nimport { generateKeypair, sign, verify, MlDsaAlgo } from \"@awth/pq-jwt\";\n\n// Generate long-term keypair (store securely!)\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\n\n// Create user session token\nconst now = Math.floor(Date.now() / 1000);\nconst { jwt, publicKey: pubKey, jti } = await sign(\n  MlDsaAlgo.Dsa65,\n  \"https://myapp.com\",\n  now + 3600,\n  privateKey\n);\n\n// Later: verify the token\nconst payload = await verify(jwt, publicKey, \"https://myapp.com\");\nconsole.log(\"Authenticated user:\", payload);\n```\n\n### Advanced Authentication Token (Builder API with Custom Claims)\n\n```typescript\nimport { SignerBuilder, MlDsaAlgo, generateKeypair } from \"@awth/pq-jwt\";\n\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\nconst now = Math.floor(Date.now() / 1000);\n\n// Create signer with all standard claims and custom data\nconst { jwt, publicKey: pubKey, jti } = await new SignerBuilder()\n  .algorithm(MlDsaAlgo.Dsa65)\n  .setPrivateKey(privateKey)\n  .setIssuer(\"https://myapp.com\")\n  .setExpiration(now + 3600)\n  .setSubject(\"user123\")\n  .setAudience(\"https://api.myapp.com\")\n  .addCustomClaims({\n    name: \"Alice\",\n    role: \"admin\",\n    permissions: [\"read\", \"write\", \"delete\"],\n  })\n  .build();\n\nconsole.log(\"Token payload:\", JSON.parse(await verify(jwt, publicKey, \"https://myapp.com\")));\n```\n\n### Verifier with Audience and Subject Validation\n\n```typescript\nimport { SignerBuilder, VerifierBuilder, MlDsaAlgo, generateKeypair } from \"@awth/pq-jwt\";\n\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\nconst now = Math.floor(Date.now() / 1000);\n\n// Create JWT\nconst { jwt } = await new SignerBuilder()\n  .algorithm(MlDsaAlgo.Dsa65)\n  .setPrivateKey(privateKey)\n  .setIssuer(\"https://test.com\")\n  .setExpiration(now + 3600)\n  .setAudience(\"https://api.test.com\")\n  .setSubject(\"user@example.com\")\n  .build();\n\n// Verify with audience and subject validation\nconst verifier = new VerifierBuilder()\n  .setPublicKey(publicKey)\n  .setIssuer(\"https://test.com\")\n  .setAudience(\"https://api.test.com\")\n  .setSubject(\"user@example.com\")\n  .setLeeway(60) // 60 seconds leeway for clock skew\n  .build();\n\nconst payload = verifier.verify(jwt);\nconsole.log(\"Verified:\", payload);\n```\n\n## 🔑 Security Levels\n\nChoose the right security level for your use case:\n\n| Variant | NIST Level | Signature Size | Key Gen | Sign | Verify | Use Case |\n|---------|-----------|----------------|---------|------|--------|----------|\n| **ML-DSA-44** | Category 2 | ~2.4 KB | ~200 µs | ~460 µs | ~140 µs | IoT devices, low-power systems |\n| **ML-DSA-65** | Category 3 | ~3.3 KB | ~350 µs | ~930 µs | ~220 µs | **Recommended for most applications** |\n| **ML-DSA-87** | Category 5 | ~4.6 KB | ~440 µs | ~550 µs | ~315 µs | High-security requirements, long-term secrets |\n\n### Security Level Comparison\n\n- **NIST Category 2** ≈ AES-128 security\n- **NIST Category 3** ≈ AES-192 security (Recommended)\n- **NIST Category 5** ≈ AES-256 security\n\n### Choosing an Algorithm\n\n```typescript\nimport { MlDsaAlgo } from \"@awth/pq-jwt\";\n\n// For most web applications (recommended)\nconst algo = MlDsaAlgo.Dsa65;\n\n// For IoT or bandwidth-constrained environments\nconst algo = MlDsaAlgo.Dsa44;\n\n// For maximum security (government, financial)\nconst algo = MlDsaAlgo.Dsa87;\n```\n\n## 🍪 Session Management for Large JWTs\n\nPost-quantum JWTs are significantly larger (3-6 KB) than classical JWTs (~300 bytes), making them impractical to store in cookies due to browser size limits (~4 KB per cookie). Here's the recommended pattern:\n\n### Cookie + Server-Side Storage Pattern\n\nInstead of storing the entire JWT in a cookie, store only the `jti` (JWT ID) and keep the full JWT server-side:\n\n```typescript\nimport { generateKeypair, sign, verify, MlDsaAlgo } from \"@awth/pq-jwt\";\n\n// 1. Generate and sign JWT\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\nconst now = Math.floor(Date.now() / 1000);\n\nconst { jwt, publicKey: pubKey, jti } = await sign(\n  MlDsaAlgo.Dsa65,\n  \"https://myapp.com\",\n  now + 3600,  // 1 hour expiration\n  privateKey\n);\n\n// 2. Store JWT server-side (Redis, database, etc.)\nawait redis.setex(jti, 3600, jwt);\n// OR\n// await db.insert({ jti, jwt, expires_at: now + 3600 });\n\n// 3. Store only the jti in cookie (36 bytes as UUID)\n// Set-Cookie: session_id={jti}; HttpOnly; Secure; SameSite=Strict\n\n// 4. On subsequent requests, retrieve JWT using jti\nconst storedJwt = await redis.get(sessionId);\nconst payload = await verify(storedJwt, publicKey, \"https://myapp.com\");\n```\n\n### Why UUID v7 for JTI?\n\nThis library uses UUID v7 (time-ordered) for `jti`, which provides several benefits:\n\n- **Sortable**: UUIDs are time-ordered, making them efficient for database indexing\n- **K-sorted**: Improves database performance by reducing index fragmentation\n- **Timestamp component**: Can extract creation time from the UUID\n- **Collision-resistant**: Cryptographically random with timestamp prefix\n\n### Size Comparison: Cookie Storage\n\n| Approach | Cookie Size | Storage Location |\n|----------|-------------|------------------|\n| **Classical JWT in cookie** | ~300 bytes | Client |\n| **PQ JWT in cookie** | ~4.5 KB ❌ (exceeds limits) | Client |\n| **JTI in cookie** | 36 bytes ✅ | Client (jti) + Server (JWT) |\n\n### Example: Full Web Application Flow with Bun\n\n```typescript\n// login.ts\nimport { Bun } from \"bun\";\nimport { generateKeypair, sign, MlDsaAlgo } from \"@awth/pq-jwt\";\n\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\n\nBun.serve({\n  async fetch(req) {\n    const url = new URL(req.url);\n\n    if (url.pathname === \"/login\" && req.method === \"POST\") {\n      // Authenticate user...\n\n      const now = Math.floor(Date.now() / 1000);\n      const { jwt, publicKey: pubKey, jti } = await sign(\n        MlDsaAlgo.Dsa65,\n        \"https://myapp.com\",\n        now + 3600,\n        privateKey\n      );\n\n      // Store in Redis with TTL\n      await redis.setex(jti, 3600, jwt);\n\n      // Return cookie with jti only (36 bytes vs 4.5 KB)\n      return new Response(\"Logged in\", {\n        headers: {\n          \"Set-Cookie\": `session_id=${jti}; HttpOnly; Secure; SameSite=Strict; Max-Age=3600`,\n        },\n      });\n    }\n\n    if (url.pathname === \"/protected\") {\n      // Get session_id from cookie\n      const cookies = req.headers.get(\"Cookie\") || \"\";\n      const sessionId = cookies.split(\"session_id=\")[1]?.split(\";\")[0];\n\n      if (!sessionId) {\n        return new Response(\"Unauthorized\", { status: 401 });\n      }\n\n      // Lookup full JWT from Redis\n      const jwt = await redis.get(sessionId);\n      if (!jwt) {\n        return new Response(\"Session not found\", { status: 401 });\n      }\n\n      // Verify JWT\n      try {\n        const payload = await verify(jwt, publicKey, \"https://myapp.com\");\n        return new Response(`Protected data: ${payload}`);\n      } catch (error) {\n        return new Response(\"Invalid token\", { status: 401 });\n      }\n    }\n\n    return new Response(\"Not found\", { status: 404 });\n  },\n  port: 3000,\n});\n```\n\n## 🛠️ API Reference\n\n### Simple API (Convenience Functions)\n\n#### `generateKeypair(algo: MlDsaAlgo): Keypair`\n\nGenerates a new keypair for the specified algorithm.\n\n**Returns**: `{ privateKey: string, publicKey: string }`\n\n```typescript\nimport { generateKeypair, MlDsaAlgo } from \"@awth/pq-jwt\";\n\nconst { privateKey, publicKey } = generateKeypair(MlDsaAlgo.Dsa65);\n```\n\n#### `sign(algo: MlDsaAlgo, iss: string, exp: number, privateKeyHex: string): Promise<SignResult>`\n\nSigns JWT claims and returns a JWT with the public key and JWT ID.\n\n**Parameters**:\n- `algo` - ML-DSA algorithm variant\n- `iss` - Issuer (REQUIRED)\n- `exp` - Expiration time as Unix timestamp in seconds (REQUIRED)\n- `privateKeyHex` - Hex-encoded private key\n\n**Returns**: `Promise<{ jwt: string, publicKey: string, jti: string }>`\n- `jwt` - The signed JWT string\n- `publicKey` - Hex-encoded public key (for verification)\n- `jti` - JWT ID (UUID v7 format) - useful for session management\n\n```typescript\nimport { sign, MlDsaAlgo } from \"@awth/pq-jwt\";\n\nconst now = Math.floor(Date.now() / 1000);\nconst { jwt, publicKey, jti } = await sign(\n  MlDsaAlgo.Dsa65,\n  \"https://myapp.com\",\n  now + 3600,\n  privateKey\n);\nconsole.log(\"JWT ID for session tracking:\", jti);\n```\n\n#### `verify(jwt: string, publicKeyHex: string, expectedIssuer: string): Promise<string>`\n\nVerifies a JWT and returns the decoded payload.\n\n**Parameters**:\n- `jwt` - The JWT string to verify\n- `publicKeyHex` - Hex-encoded public key\n- `expectedIssuer` - Expected issuer that must match the JWT's `iss` claim\n\n**Returns**: `Promise<string>` - payload if valid, throws error otherwise\n\n```typescript\nimport { verify } from \"@awth/pq-jwt\";\n\nconst payload = await verify(jwt, publicKey, \"https://myapp.com\");\nconst claims = JSON.parse(payload);\n```\n\n### Builder API (Advanced)\n\n#### `SignerBuilder`\n\n**Configuration Methods:**\n- `.algorithm(algo: MlDsaAlgo)` - Set the algorithm variant (REQUIRED)\n- `.setPrivateKey(privateKey: string)` - Set the private key (REQUIRED)\n- `.setIssuer(iss: string)` - Set `iss` claim (REQUIRED)\n- `.setExpiration(exp: number)` - Set `exp` claim as Unix timestamp (REQUIRED)\n- `.setSubject(sub: string)` - Set `sub` claim (optional)\n- `.setAudience(aud: string)` - Set `aud` claim (optional)\n- `.setIssuedAt(iat: number)` - Set `iat` claim, defaults to signing time if not set (optional)\n- `.setNotBefore(nbf: number)` - Set `nbf` claim as Unix timestamp (optional)\n- `.setJwtId(jti: string)` - Override the auto-generated `jti` claim (UUID v7 by default)\n- `.addCustomClaims(claims: Record<string, unknown>)` - Add custom claims (optional)\n- `.skipIssuedAt()` - Skip the `iat` claim entirely\n\n**Build Method:**\n- `.build()` - Build and sign the JWT, returns `Promise<SignResult>`\n\n```typescript\nimport { SignerBuilder, MlDsaAlgo } from \"@awth/pq-jwt\";\n\nconst now = Math.floor(Date.now() / 1000);\n\nconst { jwt, publicKey, jti } = await new SignerBuilder()\n  .algorithm(MlDsaAlgo.Dsa65)\n  .setPrivateKey(privateKey)\n  .setIssuer(\"https://myapp.com\")\n  .setExpiration(now + 3600)\n  .setSubject(\"user@example.com\")\n  .addCustomClaims({ role: \"admin\" })\n  .build();\n```\n\n#### `VerifierBuilder`\n\n**Required Configuration:**\n- `.setPublicKey(publicKey: string)` - Set the public key (REQUIRED)\n- `.setIssuer(issuer: string)` - Set expected issuer for validation (REQUIRED)\n\n**Optional Claim Validations:**\n- `.setAudience(audience: string)` - Set expected audience for validation\n- `.setSubject(subject: string)` - Set expected subject for validation\n- `.setLeeway(leeway: number)` - Set time leeway in seconds for clock skew (default: 0)\n\n**Build Method:**\n- `.build()` - Build Verifier instance, returns `Verifier`\n\n**Verifier Methods:**\n- `.verify(jwt: string)` - Verify JWT and return payload, returns `string`\n\n```typescript\nimport { VerifierBuilder } from \"@awth/pq-jwt\";\n\nconst verifier = new VerifierBuilder()\n  .setPublicKey(publicKey)\n  .setIssuer(\"https://myapp.com\")\n  .setAudience(\"https://api.myapp.com\")\n  .setLeeway(60)\n  .build();\n\nconst payload = verifier.verify(jwt);\n```\n\n## 🤔 Why Post-Quantum?\n\n### The Quantum Threat\n\nQuantum computers, when fully developed, will break current cryptographic systems:\n\n- **RSA** - Vulnerable to Shor's algorithm\n- **ECDSA** - Vulnerable to Shor's algorithm\n- **Diffie-Hellman** - Vulnerable to quantum attacks\n\n### Timeline\n\n- **2024**: NIST releases FIPS 204 (ML-DSA standard)\n- **2025-2030**: Quantum computers may break RSA-2048\n- **2030+**: All systems must use post-quantum crypto\n\n### \"Harvest Now, Decrypt Later\"\n\nAttackers can:\n1. Intercept and store encrypted data today\n2. Wait for quantum computers to become available\n3. Decrypt the data retroactively\n\n**Solution**: Start using post-quantum crypto NOW to protect long-term secrets.\n\n## 📄 License\n\nMIT\n\n## 👨‍💻 Author\n\n**MKSingh** ([@MKSingh_Dev](https://x.com/MKSingh_Dev))\n\n---\n\n**Made with ❤️ for a quantum-safe future**\n","readmeFilename":"README.md"}