README.md

JWT

A JWT (JSON Web Token) library written in TypeScript which supports Deno, Node.Js, Cloudflare Workers & Bun

Important

This package is no longer maintained on deno.land/x.
Please use the npm package (jwtkn) moving forward.

Live Demo

🔻 Installation

• From NPM:

npm i jwtkn

Importing the package

• NPM:

import { sign } from "jwtkn";

Usage

Sign

//the function expects a object as the payload, pass a JavaScript object to get the expected result
//✅Correct ex:
const payload = { sub: "1234", name: "Matheesha", exp: 1753195572 }
//❌Wrong ex:
const payload = '{ "sub": "1234", "name": "Matheesha", "exp": "1753195572" }'

//the header is added by the function itself and is formatted as below:
{
    alg: [given_algorithm],
    typ: 'JWT'
}

const token = sign(payload, secret, 'HS256', false)
//returns the full JWT ex: Response: xxxxxxxx.yyyyyyyy.zzzzzzzz
//if the signatureOnly is true it will return only the signatre ex: Response: zzzzzzzz

Supported Algorithms

Algorithm	Hash
HS256	SHA-256
HS384	SHA-384
HS512	SHA-512

Parameters

Parameters	Type	Required	Description
payload	object	✅	The JavaScript object to encode and sign
secret	string	✅	The key used to sign the JWT using the given algorithm
alg	string	✅	The algorithm used to sign the token
signatureOnly	boolean	❌	If true, only the signature is returned (default: false)

Returns

Type	Description
string	Returns the Base64Url encoded signature (if signatureOnly is true)
string	Returns the full JWT in header.payload.signature format (if signatureOnly is false)

Verify

const isValid = verify(token, secret, true)
//returns a object with the status and the messsage
//ex: Response: { status: false, msg: "This token is expired" }
//if debugMode is false it will return just the status in boolean type
//ex: Response: false

Parameters

Parameters	Type	Required	Description
token	string	✅	The JWT to decode and verify
secret	string	✅	The key used to encode the JWT
debugMode	boolean	❌	If true, a object will be returned else just a bool (default: false)

Returns

Type	Description
object	Returns { status: boolean, msg: string } (when debugMode is true)
boolean	Returns true if valid, false if not (when debugMode is false)

Response Messages

Status	Message (debugMode: true)	Condition
false	Token isn't in header.payload.signature format	Token does not have exactly 3 segments separated by . operator
false	The header isn't in a valid format to decode	Header is invalid Base64 or not a valid object
false	The payload isn't in a valid format to decode	Payload is invalid Base64 or not a valid object
false	This token isn't valid yet	Payload has nbf (Not Before) and current time is earlier
false	This token is expired	Payload has exp (Expiration) and current time is later
false	Token header doesn't have a valid signing algorithm	Header has alg (Algorithm) which isn't supported by the library
false	This token is invalid	The signature comparision between the given token and the recomputed signature failed
true	This token is valid	The signature comparision is success

Decode Payload

const payload = decodePayload(token)
//input the jWT and it will return the decoded payload from the token as a JavaScript object (no secret key required)
//ex: Response: 
{
    sub: "4321",
    name: "Matheesha",
    exp: 1753195572,
    admin: true
}

Parameters

Parameters	Type	Required	Description
token	string	✅	The JWT from which the payload will be decoded

Returns

Type	Description
object	Returns the decoded payload as a object

Response Messages

Status	Message	Condition
false	Token isn't in header.payload.signature format	Token does not have exactly 3 segments separated by . operator
false	The payload isn't in a valid format to decode	Payload is invalid Base64 or not a valid object
object	(decoded payload)	The payload is decoded successfully

📄 License

MIT — © 2025 0xMatheesha