@dws-std/jwt 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominus Web Services (DWS)
+
+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,109 @@
+# 🔐 DWS JWT
+
+Signing and verifying JWTs shouldn't require boilerplate.  
+`@dws-std/jwt` wraps [jose](https://github.com/panva/jose) with sane defaults — HS256, standard claims pre-filled, human-readable expiration - so you can focus on what matters instead of re-reading the JWT spec.
+
+## 📌 Table of Contents
+
+- [Installation](#-installation)
+- [Usage](#-usage)
+    - [signJWT](#signjwt)
+    - [verifyJWT](#verifyjwt)
+- [Error handling](#-error-handling)
+- [License](#-license)
+
+## 🔧 Installation
+
+```bash
+bun add @dws-std/jwt
+```
+
+## ⚙️ Usage
+
+### `signJWT`
+
+Signs a payload and returns a JWT string.  
+All standard claims (`iss`, `sub`, `aud`, `jti`, `nbf`, `iat`, `exp`) are included automatically - just pass your custom data and let the function handle the rest.
+
+```ts
+import { signJWT } from '@dws-std/jwt';
+
+// Default expiration: 15 minutes
+const token = await signJWT(secret, { userId: 42, role: 'admin' });
+
+// Numeric offset in seconds
+const token = await signJWT(secret, { userId: 42 }, 3600);
+
+// Date object
+const token = await signJWT(secret, { userId: 42 }, new Date(Date.now() + 3600_000));
+
+// Human-readable — powered by @dws-std/common
+const token = await signJWT(secret, { userId: 42 }, '1 hour');
+const token = await signJWT(secret, { userId: 42 }, '30 minutes');
+const token = await signJWT(secret, { userId: 42 }, '7 days');
+```
+
+The secret must be at least 32 characters long (HS256 requirement). Any shorter and it throws immediately — better to catch it at startup than in production.
+
+Default claims can be overridden by providing them in the payload:
+
+```ts
+const token = await signJWT(secret, {
+	iss: 'my-service',
+	sub: 'user-123',
+	aud: ['my-api'],
+	userId: 42
+});
+```
+
+### `verifyJWT`
+
+Verifies a token and returns the decoded payload. Throws if anything is wrong.
+
+```ts
+import { verifyJWT } from '@dws-std/jwt';
+
+const { payload } = await verifyJWT(token, secret);
+console.log(payload.userId);
+```
+
+Optionally validate `iss` and `aud` claims:
+
+```ts
+const { payload } = await verifyJWT(token, secret, {
+	issuer: 'my-service',
+	audience: 'my-api'
+});
+```
+
+## 🚨 Error handling
+
+All errors are `Exception` instances from `@dws-std/error` with a `key` you can check:
+
+| Key                     | When                                                            |
+| ----------------------- | --------------------------------------------------------------- |
+| `jwt.secret_too_weak`   | Secret is shorter than 32 characters                            |
+| `jwt.expiration_passed` | Expiration is in the past or equals now                         |
+| `jwt.sign_error`        | jose failed to sign the token                                   |
+| `jwt.token_expired`     | Token is valid but past its expiry date                         |
+| `jwt.unauthorized`      | Invalid signature, malformed token, or claim validation failure |
+
+```ts
+import { Exception } from '@dws-std/error';
+import { JWT_ERROR_KEYS, verifyJWT } from '@dws-std/jwt';
+
+try {
+	const { payload } = await verifyJWT(token, secret);
+} catch (error) {
+	if (error instanceof Exception) {
+		if (error.key === JWT_ERROR_KEYS.JWT_EXPIRED) {
+			// Token expired — trigger a refresh
+		}
+		// Everything else is unauthorized
+	}
+}
+```
+
+## ⚖️ License
+
+MIT - Feel free to use it.

package/dist/constant/jwt-error-keys.d.ts

@@ -0,0 +1,7 @@
+export declare const JWT_ERROR_KEYS: {
+    readonly JWT_SECRET_TOO_WEAK: "jwt.secret_too_weak";
+    readonly JWT_EXPIRATION_PASSED: "jwt.expiration_passed";
+    readonly JWT_SIGN_ERROR: "jwt.sign_error";
+    readonly JWT_EXPIRED: "jwt.token_expired";
+    readonly JWT_UNAUTHORIZED: "jwt.unauthorized";
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { JWT_ERROR_KEYS } from './constant/jwt-error-keys';
+export { signJWT, verifyJWT, type VerifyOptions } from './jwt';

package/dist/index.js

@@ -0,0 +1,68 @@
+// @bun
+// src/constant/jwt-error-keys.ts
+var JWT_ERROR_KEYS = {
+  JWT_SECRET_TOO_WEAK: "jwt.secret_too_weak",
+  JWT_EXPIRATION_PASSED: "jwt.expiration_passed",
+  JWT_SIGN_ERROR: "jwt.sign_error",
+  JWT_EXPIRED: "jwt.token_expired",
+  JWT_UNAUTHORIZED: "jwt.unauthorized"
+};
+// src/jwt.ts
+import { parseHumanTimeToSeconds } from "@dws-std/common";
+import { Exception } from "@dws-std/error";
+import { SignJWT, errors, jwtVerify } from "jose";
+var _textEncoder = new TextEncoder;
+var signJWT = (secret, payload, expiration = 60 * 15) => {
+  if (secret.length < 32)
+    throw new Exception("Secret key must be at least 32 characters long", {
+      key: JWT_ERROR_KEYS.JWT_SECRET_TOO_WEAK,
+      cause: { providedLength: secret.length }
+    });
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const exp = expiration instanceof Date ? Math.floor(expiration.getTime() / 1000) : typeof expiration === "number" ? nowSeconds + expiration : nowSeconds + parseHumanTimeToSeconds(expiration);
+  if (exp <= nowSeconds)
+    throw new Exception("Expiration time must be in the future", {
+      key: JWT_ERROR_KEYS.JWT_EXPIRATION_PASSED,
+      cause: { providedExpiration: expiration }
+    });
+  const finalPayload = {
+    iss: "DWS-Issuer",
+    sub: "",
+    aud: ["DWS-Audience"],
+    jti: Bun.randomUUIDv7(),
+    nbf: nowSeconds,
+    iat: nowSeconds,
+    exp,
+    ...payload
+  };
+  try {
+    return new SignJWT(finalPayload).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(_textEncoder.encode(secret));
+  } catch (error) {
+    throw new Exception("Failed to sign JWT", {
+      key: JWT_ERROR_KEYS.JWT_SIGN_ERROR,
+      cause: error
+    });
+  }
+};
+var verifyJWT = async (token, secret, options) => {
+  try {
+    return await jwtVerify(token, _textEncoder.encode(secret), {
+      algorithms: ["HS256"],
+      ...options?.issuer && { issuer: options.issuer },
+      ...options?.audience && { audience: options.audience }
+    });
+  } catch (error) {
+    if (error instanceof errors.JWTExpired)
+      throw new Exception("JWT token has expired", {
+        key: JWT_ERROR_KEYS.JWT_EXPIRED
+      });
+    throw new Exception("Unauthorized", {
+      key: JWT_ERROR_KEYS.JWT_UNAUTHORIZED
+    });
+  }
+};
+export {
+  verifyJWT,
+  signJWT,
+  JWT_ERROR_KEYS
+};

package/dist/jwt.d.ts

@@ -0,0 +1,29 @@
+import { type JWTPayload, type JWTVerifyResult } from 'jose';
+export interface VerifyOptions {
+    issuer?: string;
+    audience?: string | string[];
+}
+/**
+ * Signs a JWT with the given payload and expiration
+ *
+ * @param secret - The secret key used for HS256 signing (minimum 32 characters)
+ * @param payload - The JWT payload claims
+ * @param expiration - Token expiration as seconds offset, Date, or human-readable string (default: 15 minutes)
+ *
+ * @throws ({@link Exception}) – If secret is too short, expiration is in the past, or signing fails
+ *
+ * @returns A Promise resolving to the signed JWT string
+ */
+export declare const signJWT: (secret: string, payload: JWTPayload, expiration?: number | string | Date) => Promise<string>;
+/**
+ * Verifies a JWT token and throws Exception on failure
+ *
+ * @param token - The JWT token string to verify
+ * @param secret - The secret key used for HS256 verification
+ * @param options - Optional verification options for issuer/audience validation
+ *
+ * @throws ({@link Exception}) – 401 if token is expired, invalid signature, malformed, or claim validation fails
+ *
+ * @returns The verification result with payload and protected header
+ */
+export declare const verifyJWT: (token: string, secret: string, options?: VerifyOptions) => Promise<JWTVerifyResult>;

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@dws-std/jwt",
+	"version": "1.0.0",
+	"description": "JWT utilities for Dominus Web Services (DWS) projects.",
+	"keywords": [
+		"bun",
+		"dws",
+		"jwt",
+		"types",
+		"utilities"
+	],
+	"license": "MIT",
+	"author": "Dominus Web Services (DWS)",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Dominus-Web-Service/std",
+		"directory": "packages/common"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "bun builder.ts",
+		"docs": "bunx typedoc --tsconfig tsconfig.build.json",
+		"fmt:check": "oxfmt --check",
+		"fmt": "oxfmt",
+		"lint:fix": "oxlint --type-aware --type-check --fix ./src",
+		"lint:github": "oxlint --type-aware --type-check --format=github ./src",
+		"lint": "oxlint --type-aware --type-check ./src",
+		"test": "bun test --pass-with-no-tests --coverage"
+	},
+	"dependencies": {
+		"@dws-std/common": "^1.0.0",
+		"@dws-std/error": "^2.1.0",
+		"jose": "^6.2.2"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.11",
+		"oxfmt": "0.41.0",
+		"oxlint": "1.56.0",
+		"oxlint-tsgolint": "0.17.0",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@dws-std/common": "^1.0.0",
+		"@dws-std/error": "^2.1.0"
+	}
+}