unjwt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-PRESENT Johann Schopplich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# unjwt
+
+> Easy creation and verification of JSON Web Tokens (JWT).
+
+You may just use [Jose](https://github.com/panva/jose) or one of the other libraries out there. But I wanted to take my shot at creating a JWT library that is easy to use and has zero dependencies.
+
+## Features
+
+- 💨 Zero dependencies
+- 📦 Works in every context supporting the Web Crypto API
+
+## Installation
+
+Run the following command to add `unjwt` to your project.
+
+```bash
+# pnpm
+pnpm add -D unjwt
+
+# npm
+npm install -D unjwt
+
+# yarn
+yarn add -D unjwt
+```
+
+## Usage
+
+```ts
+import { signJWT, verifyJWT } from 'unjwt'
+
+interface JWTUserClaims {
+  email: string
+}
+
+const secret = 'secret'
+const issuer = 'https://domain.com'
+
+// Sign a JWT
+const accessToken = await signJWT<JWTUserClaims>({
+  payload: {
+    email: 'user@domain.com'
+  },
+  secret,
+  issuer,
+  audience: issuer,
+})
+
+// Verify a JWT
+try {
+  const verifiedAccessToken = await verifyJWT({
+    token: accessToken,
+    secret,
+    issuer,
+    audience: issuer
+  })
+}
+catch (error) {
+  // Handle error
+  console.error(error)
+}
+
+// Decode a JWT – does not verify the signature
+const decodedAccessToken = await decodeJWT<JWTUserClaims>(accessToken)
+console.log(decodedAccessToken.email)
+```
+
+## License
+
+[MIT](./LICENSE) License © 2023-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+/** Recognized JWT Claims Set members */
+interface JWTRegisteredClaims {
+    /**
+     * JWT Issuer
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
+     */
+    iss?: string;
+    /**
+     * JWT Subject
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
+     */
+    sub?: string;
+    /**
+     * JWT Audience
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+     */
+    aud?: string | string[];
+    /**
+     * JWT ID
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
+     */
+    jti?: string;
+    /**
+     * JWT Not Before
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
+     */
+    nbf?: number;
+    /**
+     * JWT Expiration Time
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
+     */
+    exp?: number;
+    /**
+     * JWT Issued At
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
+     */
+    iat?: number;
+}
+
+declare function signJWT<T extends Record<string, any> = Record<string, any>>({ payload, secret, issuer, audience, expires, header, signatureMethod, hashMethod, }: {
+    payload: T;
+    secret: string;
+    issuer: string;
+    audience: string;
+    /**
+     * Expiration time in days
+     * @default 30
+     */
+    expires?: number;
+    /** @default { typ: 'JWT', alg: 'HS256' } */
+    header?: Record<string, any>;
+    /** @default 'HMAC' */
+    signatureMethod?: string;
+    /** @default 'SHA-256' */
+    hashMethod?: string;
+}): Promise<string>;
+declare function verifyJWT({ token, secret, issuer, audience, leeway, signatureMethod, hashMethod, }: {
+    token: string;
+    secret: string;
+    issuer: string;
+    audience: string;
+    /** @default 60 */
+    leeway?: number;
+    /** @default 'HMAC' */
+    signatureMethod?: string;
+    /** @default 'SHA-256' */
+    hashMethod?: string;
+}): Promise<void>;
+declare function decodeJWT<T extends Record<string, any> = Record<string, any>>(token: string): JWTRegisteredClaims & T;
+
+export { JWTRegisteredClaims, decodeJWT, signJWT, verifyJWT };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+/** Recognized JWT Claims Set members */
+interface JWTRegisteredClaims {
+    /**
+     * JWT Issuer
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
+     */
+    iss?: string;
+    /**
+     * JWT Subject
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
+     */
+    sub?: string;
+    /**
+     * JWT Audience
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+     */
+    aud?: string | string[];
+    /**
+     * JWT ID
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
+     */
+    jti?: string;
+    /**
+     * JWT Not Before
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
+     */
+    nbf?: number;
+    /**
+     * JWT Expiration Time
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
+     */
+    exp?: number;
+    /**
+     * JWT Issued At
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
+     */
+    iat?: number;
+}
+
+declare function signJWT<T extends Record<string, any> = Record<string, any>>({ payload, secret, issuer, audience, expires, header, signatureMethod, hashMethod, }: {
+    payload: T;
+    secret: string;
+    issuer: string;
+    audience: string;
+    /**
+     * Expiration time in days
+     * @default 30
+     */
+    expires?: number;
+    /** @default { typ: 'JWT', alg: 'HS256' } */
+    header?: Record<string, any>;
+    /** @default 'HMAC' */
+    signatureMethod?: string;
+    /** @default 'SHA-256' */
+    hashMethod?: string;
+}): Promise<string>;
+declare function verifyJWT({ token, secret, issuer, audience, leeway, signatureMethod, hashMethod, }: {
+    token: string;
+    secret: string;
+    issuer: string;
+    audience: string;
+    /** @default 60 */
+    leeway?: number;
+    /** @default 'HMAC' */
+    signatureMethod?: string;
+    /** @default 'SHA-256' */
+    hashMethod?: string;
+}): Promise<void>;
+declare function decodeJWT<T extends Record<string, any> = Record<string, any>>(token: string): JWTRegisteredClaims & T;
+
+export { JWTRegisteredClaims, decodeJWT, signJWT, verifyJWT };

package/dist/index.mjs

@@ -0,0 +1,117 @@
+const DEFAULT_SIGNATURE_METHOD = "HMAC";
+const DEFAULT_HASH_METHODS = "SHA-256";
+const textEncoder = new TextEncoder();
+async function createSignature(key, algorithm, data) {
+  const encoded = textEncoder.encode(data);
+  const signature = await crypto.subtle.sign(algorithm, key, encoded);
+  return encodeToBase64Url(signature);
+}
+async function importKey({
+  secret,
+  usage = "sign",
+  name = DEFAULT_SIGNATURE_METHOD,
+  hash = DEFAULT_HASH_METHODS
+}) {
+  const encodedKey = textEncoder.encode(secret);
+  return await crypto.subtle.importKey(
+    "raw",
+    encodedKey,
+    { name, hash },
+    false,
+    [usage]
+  );
+}
+function encodeToBase64Url(input) {
+  let data;
+  if (typeof input === "string")
+    data = textEncoder.encode(input);
+  else if (input instanceof ArrayBuffer)
+    data = new Uint8Array(input);
+  else
+    data = textEncoder.encode(JSON.stringify(input));
+  const base64 = btoa(String.fromCodePoint(...data));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeFromBase64Url(base64Url) {
+  const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+  return atob(base64);
+}
+function decodeFromBase64UrlToBuffer(base64Url) {
+  const bytes = decodeFromBase64Url(base64Url);
+  const buffer = Uint8Array.from(bytes, (c) => c.codePointAt(0));
+  return buffer.buffer;
+}
+
+async function signJWT({
+  payload = {},
+  secret,
+  issuer,
+  audience,
+  expires = 30,
+  header = { typ: "JWT", alg: "HS256" },
+  signatureMethod = DEFAULT_SIGNATURE_METHOD,
+  hashMethod = DEFAULT_HASH_METHODS
+}) {
+  const key = await importKey({
+    secret,
+    name: signatureMethod,
+    hash: hashMethod
+  });
+  const iat = Math.floor(Date.now() / 1e3);
+  const exp = iat + expires * 24 * 60 * 60;
+  const jwtPayload = {
+    ...payload,
+    iss: issuer,
+    aud: audience,
+    iat,
+    exp
+  };
+  const signature = await createSignature(
+    key,
+    signatureMethod,
+    `${encodeToBase64Url(header)}.${encodeToBase64Url(jwtPayload)}`
+  );
+  return `${encodeToBase64Url(header)}.${encodeToBase64Url(
+    jwtPayload
+  )}.${signature}`;
+}
+async function verifyJWT({
+  token,
+  secret,
+  issuer,
+  audience,
+  leeway = 60,
+  signatureMethod = DEFAULT_SIGNATURE_METHOD,
+  hashMethod = DEFAULT_HASH_METHODS
+}) {
+  const [header, payload, signature] = token.split(".");
+  const key = await importKey({
+    secret,
+    usage: "verify",
+    name: signatureMethod,
+    hash: hashMethod
+  });
+  const isValid = await crypto.subtle.verify(
+    signatureMethod,
+    key,
+    decodeFromBase64UrlToBuffer(signature),
+    textEncoder.encode(`${header}.${payload}`)
+  );
+  if (!isValid)
+    throw new Error("Invalid JWT signature");
+  const decodedPayload = JSON.parse(
+    decodeFromBase64Url(payload)
+  );
+  const now = Math.floor(Date.now() / 1e3);
+  if (issuer !== decodedPayload.iss || (Array.isArray(decodedPayload.aud) ? !decodedPayload.aud.includes(audience) : audience !== decodedPayload.aud) || decodedPayload.exp && now > decodedPayload.exp + leeway || decodedPayload.nbf && now < decodedPayload.nbf - leeway)
+    throw new Error("Invalid JWT claims");
+}
+function decodeJWT(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3)
+    throw new Error("Invalid token format");
+  const [, payload] = parts;
+  return JSON.parse(decodeFromBase64Url(payload));
+}
+
+export { decodeJWT, signJWT, verifyJWT };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "unjwt",
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@8.6.12",
+  "description": "Easy creation and verification of JSON Web Tokens (JWT)",
+  "author": "Johann Schopplich <pkg@johannschopplich.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/johannschopplich/unjwt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johannschopplich/unjwt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johannschopplich/unjwt/issues"
+  },
+  "keywords": [
+    "cloudflare",
+    "jwt",
+    "serverless",
+    "token",
+    "worker"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "release": "bumpp --commit --push --tag",
+    "test:types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^0.40.2",
+    "bumpp": "^9.1.1",
+    "eslint": "^8.47.0",
+    "typescript": "^5.1.6",
+    "unbuild": "^2.0.0-rc.0"
+  }
+}