@sourceregistry/node-jwt 1.0.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# 🔐 node-jwt
+# 🔐 @sourceregistry/node-jwt
 
 [![npm version](https://img.shields.io/npm/v/@sourceregistry/node-jwt?logo=npm)](https://www.npmjs.com/package/@sourceregistry/node-jwt)
 [![License](https://img.shields.io/npm/l/@sourceregistry/node-jwt)](LICENSE)
@@ -9,11 +9,12 @@ A **minimal**, **secure**, and **production-ready** JWT (JSON Web Token) library
 
 > ✨ **Why another JWT library?**  
 > Most JWT libraries are bloated, have security pitfalls, or lack proper TypeScript support. This library is:
-> - **Tiny**
+> - **Tiny** (~150 LOC core)
 > - **Secure by default** (correct ECDSA/RSA encoding, time validation)
 > - **TypeScript-first** with full JSDoc
 > - **No external dependencies**
 > - **100% test coverage**
+> - **Dual API**: Sync and Promise-based
 
 ---
 
@@ -29,35 +30,50 @@ npm install @sourceregistry/node-jwt
 
 ## 🚀 Quick Start
 
-### Sign a token
+### Sync API (default)
 ```ts
-import { sign } from '@sourceregistry/node-jwt';
+import { sign, verify, decode } from '@sourceregistry/node-jwt';
 
+// Sign
 const token = sign(
   { sub: '1234567890', name: 'John Doe', iat: Math.floor(Date.now() / 1000) },
   'your-secret-key',
   { alg: 'HS256' }
 );
-```
-
-### Verify a token
-```ts
-import { verify } from '@sourceregistry/node-jwt';
 
+// Verify
 const result = verify(token, 'your-secret-key');
-
 if (result.valid) {
   console.log('Payload:', result.payload);
 } else {
   console.error('JWT Error:', result.error.code, result.error.reason);
 }
+
+// Decode (unsafe)
+const { header, payload, signature } = decode(token);
 ```
 
-### Decode (unsafe — no verification)
+### Promise API (`/promises`)
 ```ts
-import { decode } from '@sourceregistry/node-jwt';
+import { sign, verify, decode } from '@sourceregistry/node-jwt/promises';
 
-const { header, payload, signature } = decode(token);
+// Sign
+const token = await sign(
+  { sub: '1234567890', name: 'John Doe', iat: Math.floor(Date.now() / 1000) },
+  'your-secret-key',
+  { alg: 'HS256' }
+);
+
+// Verify
+try {
+  const { payload, header, signature } = await verify(token, 'your-secret-key');
+  console.log('Payload:', payload);
+} catch (error) {
+  console.error('JWT Error:', error.code, error.reason);
+}
+
+// Decode (unsafe)
+const { header, payload, signature } = await decode(token);
 ```
 
 ---
@@ -92,6 +108,16 @@ const { header, payload, signature } = decode(token);
 
 ## 📚 API Reference
 
+### Sync vs Promise API
+
+| Operation | Sync Return | Promise Behavior |
+|----------|-------------|------------------|
+| `sign()` | `string` | Resolves to `string` |
+| `decode()` | `{ header, payload, signature }` | Resolves to same object |
+| `verify()` | `{ valid: true, ... } \| { valid: false, error }` | **Resolves** on success<br>**Rejects** with `{ reason, code }` on failure |
+
+---
+
 ### `sign(payload, secret, options?)`
 Sign a JWT.
 
@@ -102,7 +128,7 @@ Sign a JWT.
     - `kid`: Key ID
     - `typ`: Token type (default: `'JWT'`)
 
-Returns: `string` (JWT)
+**Returns**: `string` (JWT)
 
 ---
 
@@ -115,10 +141,24 @@ Verify and validate a JWT.
     - `ignoreExpiration`: Skip `exp` check (default: `false`)
     - `clockSkew`: Tolerance in seconds for time validation (default: `0`)
 
-Returns:
+#### Sync Usage:
 ```ts
-| { valid: true; header: JWTHeader; payload: JWTPayload; signature: string }
-| { valid: false; error: { reason: string; code: string } }
+const result = verify(token, secret);
+if (result.valid) {
+  // success
+} else {
+  // handle error: result.error
+}
+```
+
+#### Promise Usage:
+```ts
+try {
+  const { header, payload, signature } = await verify(token, secret);
+  // success
+} catch (error) {
+  // handle error: error.reason, error.code
+}
 ```
 
 **Error Codes**:
@@ -137,9 +177,8 @@ Decode a JWT without verification (use with caution!).
 
 - `token`: JWT string
 
-Returns: `{ header, payload, signature }`
-
-Throws on malformed tokens.
+**Returns**: `{ header, payload, signature }`  
+**Throws** on malformed tokens (sync) / **Rejects** (promise)
 
 ---
 
@@ -158,6 +197,20 @@ Tests include:
 - Malformed token handling
 - Signature verification
 - Custom claims
+- **Both sync and promise APIs**
+
+---
+
+## 📦 Exports
+
+This package provides **two entrypoints**:
+
+| Import | Description |
+|-------|-------------|
+| `@sourceregistry/node-jwt` | **Sync API** (default) |
+| `@sourceregistry/node-jwt/promises` | **Promise-based API** |
+
+Both include full TypeScript types and JSDoc.
 
 ---
 
@@ -169,3 +222,8 @@ PRs welcome! Please:
 3. Follow existing code style
 
 Found a security issue? [Report it responsibly](mailto:a.p.a.slaa@projectsource.nl).
+
+---
+
+> 🔗 **GitHub**: [github.com/SourceRegistry/node-jwt](https://github.com/SourceRegistry/node-jwt)  
+> 📦 **npm**: [@sourceregistry/node-jwt](https://www.npmjs.com/package/@sourceregistry/node-jwt)

package/dist/promises.cjs.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index.cjs.js"),s=r=>Promise.resolve().then(()=>e.decode(r)),n=(r,o,t={})=>Promise.resolve().then(()=>e.sign(r,o,t)),g=(r,o,t={})=>Promise.resolve().then(()=>{const i=e.verify(r,o,t);if(!i.valid)throw i.error;const{header:l,payload:d,signature:c}=i;return{header:l,payload:d,signature:c}}),u={sign:n,verify:g,decode:s,algorithms:e.SignatureAlgorithm};exports.SignatureAlgorithm=e.SignatureAlgorithm;exports.SupportedAlgorithms=e.SupportedAlgorithms;exports.JWT=u;exports.decode=s;exports.sign=n;exports.verify=g;
+//# sourceMappingURL=promises.cjs.js.map

package/dist/promises.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promises.cjs.js","sources":["../src/promises.ts"],"sourcesContent":["import type { KeyLike } from 'crypto';\nimport {\n    type JWT as JSONWebToken,\n    decode as decodeSync,\n    sign as signSync,\n    verify as verifySync,\n    JWTPayload,\n    type SupportedAlgorithm,\n    JWTHeader,\n    SignatureAlgorithm\n} from './index.js';\n\nexport { type SupportedAlgorithm, SupportedAlgorithms, SignatureAlgorithm, type JWTHeader, type JWTPayload } from './index.js';\n\n/**\n * Decode a JWT string into its parts (without verification)\n */\nexport const decode = (token: string): Promise<JSONWebToken> =>\n    Promise.resolve().then(() => decodeSync(token));\n\n/**\n * Sign a JWT\n */\nexport const sign = (\n    payload: JWTPayload,\n    secret: KeyLike,\n    options: {\n        alg?: SupportedAlgorithm;\n        kid?: string;\n        typ?: string;\n    } = {}\n): Promise<string> =>\n    Promise.resolve().then(() => signSync(payload, secret, options));\n\n/**\n * Verify and validate a JWT\n *\n * @throws { { reason: string; code: string } } if invalid\n */\nexport const verify = (\n    token: string,\n    secret: KeyLike,\n    options: {\n        ignoreExpiration?: boolean;\n        clockSkew?: number;\n    } = {}\n): Promise<{ header: JWTHeader; payload: JWTPayload; signature: string }> =>\n    Promise.resolve().then(() => {\n        const result = verifySync(token, secret, options);\n        if (!result.valid) {\n            throw result.error;\n        }\n        const { header, payload, signature } = result;\n        return { header, payload, signature };\n    });\n\nexport type JWT = JSONWebToken;\n\nexport const JWT = {\n    sign,\n    verify,\n    decode,\n    algorithms: SignatureAlgorithm\n};\n"],"names":["decode","token","decodeSync","sign","payload","secret","options","signSync","verify","result","verifySync","header","signature","JWT","SignatureAlgorithm"],"mappings":"kHAiBaA,EAAUC,GACnB,QAAQ,QAAA,EAAU,KAAK,IAAMC,EAAAA,OAAWD,CAAK,CAAC,EAKrCE,EAAO,CAChBC,EACAC,EACAC,EAII,CAAA,IAEJ,QAAQ,QAAA,EAAU,KAAK,IAAMC,EAAAA,KAASH,EAASC,EAAQC,CAAO,CAAC,EAOtDE,EAAS,CAClBP,EACAI,EACAC,EAGI,CAAA,IAEJ,QAAQ,UAAU,KAAK,IAAM,CACzB,MAAMG,EAASC,EAAAA,OAAWT,EAAOI,EAAQC,CAAO,EAChD,GAAI,CAACG,EAAO,MACR,MAAMA,EAAO,MAEjB,KAAM,CAAE,OAAAE,EAAQ,QAAAP,EAAS,UAAAQ,CAAA,EAAcH,EACvC,MAAO,CAAE,OAAAE,EAAQ,QAAAP,EAAS,UAAAQ,CAAA,CAC9B,CAAC,EAIQC,EAAM,CACf,KAAAV,EACA,OAAAK,EACA,OAAAR,EACA,WAAYc,EAAAA,kBAChB"}

package/dist/promises.d.ts

@@ -0,0 +1,83 @@
+import { KeyLike } from 'crypto';
+import { JWT as JSONWebToken, JWTPayload, SupportedAlgorithm, JWTHeader } from './index.js';
+export { type SupportedAlgorithm, SupportedAlgorithms, SignatureAlgorithm, type JWTHeader, type JWTPayload } from './index.js';
+/**
+ * Decode a JWT string into its parts (without verification)
+ */
+export declare const decode: (token: string) => Promise<JSONWebToken>;
+/**
+ * Sign a JWT
+ */
+export declare const sign: (payload: JWTPayload, secret: KeyLike, options?: {
+    alg?: SupportedAlgorithm;
+    kid?: string;
+    typ?: string;
+}) => Promise<string>;
+/**
+ * Verify and validate a JWT
+ *
+ * @throws { { reason: string; code: string } } if invalid
+ */
+export declare const verify: (token: string, secret: KeyLike, options?: {
+    ignoreExpiration?: boolean;
+    clockSkew?: number;
+}) => Promise<{
+    header: JWTHeader;
+    payload: JWTPayload;
+    signature: string;
+}>;
+export type JWT = JSONWebToken;
+export declare const JWT: {
+    sign: (payload: JWTPayload, secret: KeyLike, options?: {
+        alg?: SupportedAlgorithm;
+        kid?: string;
+        typ?: string;
+    }) => Promise<string>;
+    verify: (token: string, secret: KeyLike, options?: {
+        ignoreExpiration?: boolean;
+        clockSkew?: number;
+    }) => Promise<{
+        header: JWTHeader;
+        payload: JWTPayload;
+        signature: string;
+    }>;
+    decode: (token: string) => Promise<JSONWebToken>;
+    algorithms: {
+        readonly HS256: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly HS384: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly HS512: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly RS256: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly RS384: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly RS512: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly ES256: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly ES384: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+        readonly ES512: {
+            readonly sign: (data: import('crypto').BinaryLike, secret: KeyLike) => string;
+            readonly verify: (data: import('crypto').BinaryLike, secret: KeyLike, signature: string) => boolean;
+        };
+    };
+};

package/dist/promises.es.js

@@ -0,0 +1,23 @@
+import { SignatureAlgorithm as a, decode as d, sign as c, verify as l } from "./index.es.js";
+import { SupportedAlgorithms as y } from "./index.es.js";
+const m = (e) => Promise.resolve().then(() => d(e)), g = (e, r, o = {}) => Promise.resolve().then(() => c(e, r, o)), h = (e, r, o = {}) => Promise.resolve().then(() => {
+  const s = l(e, r, o);
+  if (!s.valid)
+    throw s.error;
+  const { header: t, payload: i, signature: n } = s;
+  return { header: t, payload: i, signature: n };
+}), f = {
+  sign: g,
+  verify: h,
+  decode: m,
+  algorithms: a
+};
+export {
+  f as JWT,
+  a as SignatureAlgorithm,
+  y as SupportedAlgorithms,
+  m as decode,
+  g as sign,
+  h as verify
+};
+//# sourceMappingURL=promises.es.js.map

package/dist/promises.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promises.es.js","sources":["../src/promises.ts"],"sourcesContent":["import type { KeyLike } from 'crypto';\nimport {\n    type JWT as JSONWebToken,\n    decode as decodeSync,\n    sign as signSync,\n    verify as verifySync,\n    JWTPayload,\n    type SupportedAlgorithm,\n    JWTHeader,\n    SignatureAlgorithm\n} from './index.js';\n\nexport { type SupportedAlgorithm, SupportedAlgorithms, SignatureAlgorithm, type JWTHeader, type JWTPayload } from './index.js';\n\n/**\n * Decode a JWT string into its parts (without verification)\n */\nexport const decode = (token: string): Promise<JSONWebToken> =>\n    Promise.resolve().then(() => decodeSync(token));\n\n/**\n * Sign a JWT\n */\nexport const sign = (\n    payload: JWTPayload,\n    secret: KeyLike,\n    options: {\n        alg?: SupportedAlgorithm;\n        kid?: string;\n        typ?: string;\n    } = {}\n): Promise<string> =>\n    Promise.resolve().then(() => signSync(payload, secret, options));\n\n/**\n * Verify and validate a JWT\n *\n * @throws { { reason: string; code: string } } if invalid\n */\nexport const verify = (\n    token: string,\n    secret: KeyLike,\n    options: {\n        ignoreExpiration?: boolean;\n        clockSkew?: number;\n    } = {}\n): Promise<{ header: JWTHeader; payload: JWTPayload; signature: string }> =>\n    Promise.resolve().then(() => {\n        const result = verifySync(token, secret, options);\n        if (!result.valid) {\n            throw result.error;\n        }\n        const { header, payload, signature } = result;\n        return { header, payload, signature };\n    });\n\nexport type JWT = JSONWebToken;\n\nexport const JWT = {\n    sign,\n    verify,\n    decode,\n    algorithms: SignatureAlgorithm\n};\n"],"names":["decode","token","decodeSync","sign","payload","secret","options","signSync","verify","result","verifySync","header","signature","JWT","SignatureAlgorithm"],"mappings":";;AAiBO,MAAMA,IAAS,CAACC,MACnB,QAAQ,QAAA,EAAU,KAAK,MAAMC,EAAWD,CAAK,CAAC,GAKrCE,IAAO,CAChBC,GACAC,GACAC,IAII,CAAA,MAEJ,QAAQ,QAAA,EAAU,KAAK,MAAMC,EAASH,GAASC,GAAQC,CAAO,CAAC,GAOtDE,IAAS,CAClBP,GACAI,GACAC,IAGI,CAAA,MAEJ,QAAQ,UAAU,KAAK,MAAM;AACzB,QAAMG,IAASC,EAAWT,GAAOI,GAAQC,CAAO;AAChD,MAAI,CAACG,EAAO;AACR,UAAMA,EAAO;AAEjB,QAAM,EAAE,QAAAE,GAAQ,SAAAP,GAAS,WAAAQ,EAAA,IAAcH;AACvC,SAAO,EAAE,QAAAE,GAAQ,SAAAP,GAAS,WAAAQ,EAAA;AAC9B,CAAC,GAIQC,IAAM;AAAA,EACf,MAAAV;AAAA,EACA,QAAAK;AAAA,EACA,QAAAR;AAAA,EACA,YAAYc;AAChB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/node-jwt",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight, zero-dependency TypeScript library for creating, verifying and decoding JSON Web Tokens (JWT).",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.es.js",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs.js"
+    },
+    "./promises": {
+      "types": "./dist/promises.d.ts",
+      "import": "./dist/promises.es.js",
+      "require": "./dist/promises.cjs.js"
     }
   },
   "files": [