Skip to main content
Deno 2 is finally here 🎉️
Learn more

JWT by 4zeroiv

This is a JWT library written in TypeScript which supports Deno, Node.Js, Cloudflare Workers & Bun

Github Repo GitHub License GitHub top language

NPM Deno

🔻 Installation

# From NPM
npm i @4zeroiv/jwt
# From JSR (JavaScript Registry)
deno add jsr:@4zeroiv/jwt

Importing from published packages

  • Deno:
import { HS256 } from "https://deno.land/x/jwtx/mod.ts";
  • NPM:
import { HS256 } from "@4zeroiv/jwt";

✍️ HS256(payload: object, secret: string, signatureOnly?: boolean): Promise<string | object>

Signs a payload using the HMAC-SHA256 algorithm and returns either the full JWT or just the signature.

📥 Parameters

Name Type Required Description
payload object ✅ The JSON data to encode and sign
secret string ✅ The secret key used for HMAC-SHA256 signing
signatureOnly boolean ❌ If true, only the signature is returned (default: false)

🔁 Returns

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

📘 Example

import { HS256 } from "@4zeroiv/jwt"

const payload = {
  userId: 123,
  exp: Math.floor(Date.now() / 1000) + 60 * 60 // expires in 1 hour
}

const token = await HS256(payload, "my-secret")
// token -> "header.payload.signature"

const signature = await HS256(payload, "my-secret", true)
// signature -> "aWJsdGV..."

console.log(token)

✅ verify(token: string, secret: string, debugMode?: boolean): Promise<boolean | VerifyResponse>

Verifies the validity of a JWT by checking its structure, signature, and time-based claims (nbf, exp).

📥 Parameters

Name Type Required Description
token string ✅ The JWT to verify
secret string ✅ The secret used to sign the token
debugMode boolean ❌ If true, returns an object with status and a message (default: false)

🔁 Returns

  • boolean – true if valid, false if not (when debugMode is false)
  • object – { status: boolean, msg: string } (when debugMode is true)

📘 Example

import { verify } from "@4zeroiv/jwt"

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTMwMDAwMDB9.XYZ..."
const isValid = await verify(token, "my-secret", true)
console.log(isValid)

🧩 decodePayload(token: string): object

Decodes the payload section of a JWT (JSON Web Token) and returns it as a JavaScript object.

📥 Parameters

Name Type Description
token string The JWT string to decode (must be in valid format)

🔁 Returns

Type Description
object Returns the decoded payload as an object if the JWT is valid
object Returns an error object with status: false and a message if decoding fails

📘 Example

import { decodePayload } from "@4zeroiv/jwt"

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywiZXhwIjoxNzUzMD..." // etc
const payload = decodePayload(token)
console.log(payload)

🧾 Verify Function Response Messages

Status Message Condition
false Token isn't in header.payload.signature format (all 3 parts doesn't exist) Token does not have exactly 3 segments separated by .
false The header isn't in a valid format to decode Header is invalid Base64 or not a valid JSON
false The payload isn't in a valid format to decode Payload is invalid Base64 or not a valid JSON
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 alg is not supported (i.e., not HS256)
false This token is invalid Signature comparison fails
true This token is valid Signature is valid, and token passes nbf, exp, and alg checks

🧾 Decode Payload Function Response Messages

Status Message Condition
false Token isn't in header.payload.signature format (all 3 parts doesn't exist) Token does not have exactly 3 segments separated by .
false The payload isn't in a valid format to decode Payload is not valid Base64
false The header isn't in a valid format to decode Decoded payload is not valid JSON
object (decoded payload) Token is valid and payload successfully decoded