@nitrotool/jwt 0.0.6 → 0.0.8

package/README.md

@@ -0,0 +1,182 @@
+# @nitrotool/jwt
+
+Lightweight JWT utilities for Nitro/UnJS environments with optional h3 helpers.
+
+- Built on `@tsndr/cloudflare-worker-jwt`
+- Helpers that read `jwtSecret` from your Nitro runtime config
+- h3 utilities to extract tokens from requests and enforce authentication
+
+## Installation
+
+```bash
+npm install @nitrotool/jwt
+```
+
+Peer dependency:
+- `h3` is required only when using the h3 helpers.
+
+## Importing
+
+You can import from the main entry or subpath exports:
+
+```ts
+// Main (all helpers)
+import { encodeJwt, verifyJwt, decodeJwt } from '@nitrotool/jwt';
+
+// Subpath (JWT-only)
+import { encodeJwtRaw, verifyJwtRaw, decodeJwtRaw } from '@nitrotool/jwt/jwt';
+
+// Subpath (h3 helpers)
+import { extractApiToken, requireApiToken } from '@nitrotool/jwt/h3';
+```
+
+## Quick Start
+
+```ts
+import { encodeJwt, verifyJwt, decodeJwt } from '@nitrotool/jwt';
+
+type MyClaims = { userId: string };
+
+const token = await encodeJwt<MyClaims>({ userId: '123' });
+// Later…
+const isValid = await verifyJwt(token);
+const payload = await decodeJwt<MyClaims>(token); // { userId: '123', exp: ... }
+```
+
+By default, non-`Raw` helpers read the secret from your runtime config:
+- `useRuntimeConfig().jwtSecret`
+
+If you need to pass a secret explicitly, use the `*Raw` variants.
+
+## Usage with h3
+
+Extract API tokens and enforce authentication in request handlers:
+
+```ts
+import { defineEventHandler } from 'h3';
+import { extractApiToken, requireApiToken } from '@nitrotool/jwt/h3';
+import { decodeJwt } from '@nitrotool/jwt';
+
+export default defineEventHandler(async (event) => {
+  // Try to read token (Authorization: Bearer <token> or ?token=<token>)
+  const token = extractApiToken(event);
+
+  // Or strictly require it (throws UnauthenticatedError if missing)
+  const requiredToken = requireApiToken(event);
+
+  // Optionally decode/verify
+  const claims = await decodeJwt<{ userId: string }>(requiredToken);
+
+  return { ok: true, userId: claims.userId };
+});
+```
+
+Supported token locations:
+- Authorization header: `Authorization: Bearer <token>`
+- Query string: `?token=<token>`
+
+## Configuration
+
+When using non-`Raw` helpers, ensure a secret is available at runtime:
+
+```ts
+// Example: Nuxt/Nitro runtime config
+export default defineNuxtConfig({
+  runtimeConfig: {
+    jwtSecret: process.env.JWT_SECRET || 'super-secret',
+  },
+});
+```
+
+## Examples
+
+Sign with custom TTL:
+
+```ts
+import { encodeJwtRaw } from '@nitrotool/jwt';
+
+const token = await encodeJwtRaw(
+  { userId: '123', role: 'admin' },
+  process.env.JWT_SECRET!,
+  60 * 10 // 10 minutes
+);
+```
+
+Decode without verifying signature (use only for non-sensitive scenarios):
+
+```ts
+import { decodeJwt } from '@nitrotool/jwt';
+
+const payload = await decodeJwt<{ userId: string }>(token, { verify: false });
+```
+
+Verify with an explicit secret:
+
+```ts
+import { verifyJwtRaw } from '@nitrotool/jwt';
+
+const ok = await verifyJwtRaw(token, process.env.JWT_SECRET!);
+```
+
+## Errors
+
+- `UnauthorizedError('Invalid JWT token.')` is thrown when verification fails in `decodeJwt` / `decodeJwtRaw`.
+- `UnauthenticatedError()` is thrown by `requireApiToken` when no token is present.
+
+## Security Notes
+
+- Keep `jwtSecret` strong and private.
+- Prefer short TTLs and refresh flows.
+- Only set `verify: false` for non-sensitive, debug-like operations.
+- Rotate secrets periodically and invalidate old tokens if needed.
+
+## API Reference
+
+All helpers are asynchronous.
+
+### JWT helpers
+
+- `encodeJwtRaw<T>(payload, secret, ttl = 60): Promise<string>`
+    - Signs a token with the provided `secret`.
+    - `ttl` is in seconds. Default: `60`.
+    - `exp` is set automatically from `ttl`.
+
+- `encodeJwt<T>(payload): Promise<string>`
+    - Same as `encodeJwtRaw`, but uses `useRuntimeConfig().jwtSecret`.
+
+- `verifyJwtRaw(token, secret): Promise<boolean>`
+    - Verifies signature and expiry using the provided `secret`.
+
+- `verifyJwt(token): Promise<boolean>`
+    - Same as `verifyJwtRaw`, but uses `useRuntimeConfig().jwtSecret`.
+
+- `decodeJwtRaw<T>(token, secret, { verify = true } = {}): Promise<T & Partial<JwtPayload>>`
+    - Decodes the token. When `verify` is `true`, verifies signature and expiry.
+    - Throws `UnauthorizedError('Invalid JWT token.')` if verification fails.
+    - Throws if `verify` is `true` but `secret` is empty.
+
+- `decodeJwt<T>(token, { verify = true } = {}): Promise<T & Partial<JwtPayload>>`
+    - Same as `decodeJwtRaw`, but uses `useRuntimeConfig().jwtSecret`.
+    - Throws `UnauthorizedError('Invalid JWT token.')` if verification fails.
+
+Types:
+- `ExtendableJwtPayload<T>` lets you define custom claims merged with standard JWT claims.
+
+### h3 helpers
+
+- `extractBearerToken(event): string | undefined`
+    - Reads `Authorization` header and returns the token without `Bearer `.
+
+- `extractQueryToken(event): string | undefined`
+    - Reads `token` from the query string.
+
+- `extractApiToken(event): string | undefined`
+    - Returns the first non-empty token found by `extractBearerToken` or `extractQueryToken`.
+
+- `requireApiToken(event): string`
+    - Same as `extractApiToken`, but throws `UnauthenticatedError` if missing.
+
+
+## License
+
+MIT

package/dist/h3.d.mts

@@ -1,7 +1,7 @@
 import { H3Event } from 'h3';
 
 declare const extractBearerToken: (event: H3Event) => string;
-declare const extractQueryToken: (event: H3Event) => string | undefined;
+declare const extractQueryToken: (event: H3Event, key?: string) => string | undefined;
 declare const extractApiToken: (event: H3Event) => string | undefined;
 declare const requireApiToken: (event: H3Event) => string;
 

package/dist/h3.d.ts

@@ -1,7 +1,7 @@
 import { H3Event } from 'h3';
 
 declare const extractBearerToken: (event: H3Event) => string;
-declare const extractQueryToken: (event: H3Event) => string | undefined;
+declare const extractQueryToken: (event: H3Event, key?: string) => string | undefined;
 declare const extractApiToken: (event: H3Event) => string | undefined;
 declare const requireApiToken: (event: H3Event) => string;
 

package/dist/h3.mjs

@@ -2,7 +2,7 @@ import { getRequestHeader, getQuery } from 'h3';
 import { UnauthenticatedError } from '@nitrotool/errors';
 
 const extractBearerToken = (event) => getRequestHeader(event, "Authorization")?.replace("Bearer ", "") || void 0;
-const extractQueryToken = (event) => getQuery(event)?.token || void 0;
+const extractQueryToken = (event, key = "token") => getQuery(event)?.[key] || void 0;
 const extractApiToken = (event) => extractBearerToken(event) || extractQueryToken(event);
 const requireApiToken = (event) => {
   const token = extractApiToken(event);

package/dist/jwt.mjs

@@ -1,5 +1,5 @@
 import jwt from '@tsndr/cloudflare-worker-jwt';
-import { createError } from 'h3';
+import { UnauthorizedError } from '@nitrotool/errors';
 
 const encodeJwtRaw = async (payload, secret, ttl = 60) => {
   return await jwt.sign(
@@ -33,16 +33,17 @@ const verifyJwt = async (token) => {
   return verifyJwtRaw(token, secret);
 };
 const decodeJwtRaw = async (token, secret, { verify } = { verify: true }) => {
-  if (!secret && verify) throw new Error("Cannot check signature without secret.");
+  if (!secret && verify)
+    throw new Error("Cannot check signature without secret.");
   if (secret && verify && !await verifyJwtRaw(token, secret)) {
-    throw createError("Invalid JWT token.");
+    throw UnauthorizedError("Invalid JWT token.");
   }
   const { payload } = jwt.decode(token);
   return payload;
 };
 const decodeJwt = async (token, { verify } = { verify: true }) => {
   if (verify && !await verifyJwt(token)) {
-    throw createError("Invalid JWT token.");
+    throw UnauthorizedError("Invalid JWT token.");
   }
   const { payload } = jwt.decode(token);
   return payload;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitrotool/jwt",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "main": "dist/index.mjs",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@tsndr/cloudflare-worker-jwt": "^3.2.0",
-    "@nitrotool/errors": "0.0.6"
+    "@nitrotool/errors": "0.0.8"
   },
   "peerDependencies": {
     "h3": "^1.15.3"

package/src/h3.ts

@@ -1,24 +0,0 @@
-import {
-    type H3Event,
-    getRequestHeader,
-    getQuery,
-} from 'h3';
-import {UnauthenticatedError} from "@nitrotool/errors";
-
-export const extractBearerToken = (event: H3Event) =>
-    getRequestHeader(event, 'Authorization')?.replace('Bearer ', '') || undefined;
-
-export const extractQueryToken = (event: H3Event): string | undefined =>
-    getQuery<{ token: string }>(event)?.token || undefined;
-
-export const extractApiToken = (event: H3Event): string | undefined =>
-    extractBearerToken(event) || extractQueryToken(event);
-
-export const requireApiToken = (event: H3Event) => {
-    const token = extractApiToken(event);
-    if (!token) {
-        throw UnauthenticatedError();
-    }
-
-    return token;
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-// @ts-ignore
-export * from './h3';
-// @ts-ignore
-export * from './jwt';
-

package/src/jwt.ts

@@ -1,80 +0,0 @@
-import jwt, {JwtPayload} from '@tsndr/cloudflare-worker-jwt';
-
-import { createError } from 'h3';
-export type ExtendableJwtPayload<T extends Record<string, any> = {}> =
-    Partial<JwtPayload> & T;
-
-export const encodeJwtRaw = async <
-    T extends Record<string, any> = {},
->(
-    payload: ExtendableJwtPayload<T>,
-    secret: string,
-    ttl = 60,
-): Promise<string> => {
-    return await jwt.sign(
-        {
-            exp: Date.now() / 1000 + ttl,
-            ...payload,
-        },
-        secret,
-    );
-};
-
-export const encodeJwt = async <
-    T extends Record<string, any> = {},
->(
-    payload: ExtendableJwtPayload<T>,
-): Promise<string> => {
-    const secret =
-        //@ts-expect-error Expected.
-        typeof useRuntimeConfig === 'function' ? useRuntimeConfig()?.jwtSecret : '';
-    return encodeJwtRaw(payload, secret);
-};
-
-export const verifyJwtRaw = async (
-    token: string,
-    secret: string,
-): Promise<boolean> => {
-    return new Promise(async (resolve) => {
-        if (await jwt.verify(token, secret, {throwError: false})) {
-            return resolve(true);
-        }
-
-        return resolve(false);
-    });
-};
-
-export const verifyJwt = async (token: string): Promise<boolean> => {
-    const secret =
-        //@ts-expect-error Expected.
-        typeof useRuntimeConfig === 'function' ? useRuntimeConfig()?.jwtSecret : '';
-    return verifyJwtRaw(token, secret);
-};
-
-export const decodeJwtRaw = async <
-    T extends Record<string, any> = {},
->(
-    token: string,
-    secret: string,
-    { verify }: { verify?: boolean } = { verify: true },
-): Promise<ExtendableJwtPayload<T>> => {
-    if (!secret && verify) throw new Error('Cannot check signature without secret.');
-    if (secret && verify && !(await verifyJwtRaw(token, secret))) {
-        throw createError('Invalid JWT token.');
-    }
-    const { payload } = jwt.decode<ExtendableJwtPayload<T>>(token);
-    return payload;
-};
-
-export const decodeJwt = async <
-    T extends Record<string, any> = {},
->(
-    token: string,
-    { verify }: { verify?: boolean } = { verify: true },
-): Promise<ExtendableJwtPayload<T>> => {
-    if (verify && !(await verifyJwt(token))) {
-        throw createError('Invalid JWT token.');
-    }
-    const { payload } = jwt.decode<ExtendableJwtPayload<T>>(token);
-    return payload;
-};