@vurb/jwt 3.1.31

package/README.md

@@ -0,0 +1,79 @@
+<p align="center">
+  <h1 align="center">@vurb/jwt</h1>
+  <p align="center">
+    <strong>JWT Verification Middleware</strong> — Standards-compliant token validation for Vurb.ts servers
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@vurb/jwt"><img src="https://img.shields.io/npm/v/@vurb/jwt?color=blue" alt="npm" /></a>
+  <a href="https://github.com/vinkius-labs/vurb.ts/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node" />
+</p>
+
+---
+
+> JWT verification middleware for MCP servers built with Vurb.ts. Timing-safe validation with `jose`, JWKS auto-discovery, and self-healing error responses.
+
+## Quick Start
+
+```typescript
+import { initVurb } from '@vurb/core';
+import { jwtGuard } from '@vurb/jwt';
+
+const f = initVurb<AppContext>();
+
+const withJwt = jwtGuard({
+    secret: process.env.JWT_SECRET!,
+    algorithms: ['HS256'],
+});
+
+export default f.query('billing.invoices')
+    .use(withJwt)
+    .handle(async (input, ctx) => {
+        // ctx.jwt contains the decoded payload
+        return db.invoices.findMany({ where: { tenantId: ctx.jwt.sub } });
+    });
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Algorithms** | HS256, RS256, ES256 — all standard algorithms via `jose` |
+| **JWKS** | Auto-discovery from `/.well-known/jwks.json` with key rotation |
+| **Self-Healing** | Expired/invalid tokens return actionable hints to the LLM agent |
+| **Timing-Safe** | Constant-time signature verification |
+| **Zero Config** | Works with Auth0, Clerk, Supabase, Firebase, any OIDC provider |
+
+## JWKS Auto-Discovery
+
+```typescript
+const withJwt = jwtGuard({
+    jwksUri: 'https://auth.example.com/.well-known/jwks.json',
+    issuer: 'https://auth.example.com/',
+    audience: 'my-mcp-server',
+});
+```
+
+## Installation
+
+```bash
+npm install @vurb/jwt jose
+```
+
+### Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `vurb` | `^2.0.0` |
+| `jose` | `^5.0.0` (optional) |
+
+## Requirements
+
+- **Node.js** ≥ 18.0.0
+- **Vurb.ts** ≥ 2.0.0 (peer dependency)
+
+## License
+
+[Apache-2.0](https://github.com/vinkius-labs/vurb.ts/blob/main/LICENSE)

package/dist/JwtVerifier.d.ts

@@ -0,0 +1,128 @@
+/**
+ * JWT Verifier — Standards-Compliant Token Verification
+ *
+ * Verifies JWTs using `jose` when installed, or falls back to
+ * native `crypto.subtle` (Web Crypto API) for HS256 verification.
+ *
+ * Supports:
+ * - HS256, RS256, ES256 (via jose)
+ * - HS256 native fallback (via crypto.subtle)
+ * - JWKS endpoint auto-discovery
+ * - Claims validation: `exp`, `nbf`, `iss`, `aud`
+ *
+ * @example
+ * ```ts
+ * import { JwtVerifier } from '@vurb/jwt';
+ *
+ * // With symmetric secret (HS256)
+ * const verifier = new JwtVerifier({ secret: 'my-secret' });
+ *
+ * // With JWKS endpoint (RS256, ES256)
+ * const verifier = new JwtVerifier({ jwksUri: 'https://auth.example.com/.well-known/jwks.json' });
+ *
+ * const payload = await verifier.verify(token);
+ * if (payload) console.log(payload.sub); // user ID
+ * ```
+ */
+export interface JwtVerifierConfig {
+    /** Symmetric secret for HS256. */
+    readonly secret?: string;
+    /** JWKS endpoint URL for RS256/ES256 key fetching. Requires `jose`. */
+    readonly jwksUri?: string;
+    /** PEM-encoded public key for RS256/ES256. */
+    readonly publicKey?: string;
+    /** Algorithm for public key verification (e.g. 'RS256', 'ES256', 'ES384', 'ES512'). Default: 'RS256'. */
+    readonly algorithm?: string;
+    /** Expected issuer (`iss` claim). */
+    readonly issuer?: string | string[];
+    /** Expected audience (`aud` claim). */
+    readonly audience?: string | string[];
+    /** Clock tolerance in seconds for `exp`/`nbf` checks. Default: 60 */
+    readonly clockTolerance?: number;
+    /** Required claims that must be present in the payload. */
+    readonly requiredClaims?: string[];
+}
+export interface JwtPayload {
+    /** Subject — typically the user ID */
+    readonly sub?: string;
+    /** Issuer */
+    readonly iss?: string;
+    /** Audience */
+    readonly aud?: string | string[];
+    /** Expiration time (Unix seconds) */
+    readonly exp?: number;
+    /** Not before (Unix seconds) */
+    readonly nbf?: number;
+    /** Issued at (Unix seconds) */
+    readonly iat?: number;
+    /** JWT ID */
+    readonly jti?: string;
+    /** Additional claims */
+    readonly [key: string]: unknown;
+}
+export interface JwtVerifyResult {
+    /** Whether the token is valid */
+    readonly valid: boolean;
+    /** Decoded payload (only present if valid) */
+    readonly payload?: JwtPayload;
+    /** Error reason (only present if invalid) */
+    readonly reason?: string;
+}
+export declare class JwtVerifier {
+    private readonly _config;
+    private readonly _clockTolerance;
+    private _joseLoaded;
+    private _jwtVerify;
+    private _createRemoteJWKSet;
+    private _jwks;
+    constructor(config: JwtVerifierConfig);
+    /**
+     * Verify a JWT and return the decoded payload.
+     *
+     * @param token - Raw JWT string (without "Bearer " prefix)
+     * @returns The decoded payload, or `null` if verification fails
+     */
+    verify(token: string): Promise<JwtPayload | null>;
+    /**
+     * Verify a JWT with detailed result including error reason.
+     *
+     * @param token - Raw JWT string
+     * @returns Detailed verification result
+     */
+    verifyDetailed(token: string): Promise<JwtVerifyResult>;
+    /**
+     * Attempt to verify using jose.
+     * Returns `undefined` if jose is not installed.
+     *
+     * @internal
+     */
+    private _verifyWithJose;
+    /**
+     * Load jose dynamically. Silently fails if not installed.
+     * @internal
+     */
+    private _loadJose;
+    /**
+     * Verify HS256 JWT using Node.js native crypto.
+     * @internal
+     */
+    private _verifyHS256Native;
+    /**
+     * Validate claims (exp, nbf, required) on an already signature-verified payload.
+     * @internal
+     */
+    private _validateClaims;
+    /**
+     * Decode a JWT payload WITHOUT verifying the signature.
+     * Useful for inspecting tokens in logging/debugging.
+     *
+     * ⚠️ Never trust decoded-only payloads for authorization decisions.
+     */
+    static decode(token: string): JwtPayload | null;
+    /**
+     * Check if a token is expired without verifying signature.
+     * Returns `true` if expired or unparseable.
+     */
+    static isExpired(token: string, clockTolerance?: number): boolean;
+}
+//# sourceMappingURL=JwtVerifier.d.ts.map

package/dist/JwtVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtVerifier.d.ts","sourceRoot":"","sources":["../src/JwtVerifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,MAAM,WAAW,iBAAiB;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,yGAAyG;IACzG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEpC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEtC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACvB,sCAAsC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa;IACb,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe;IACf,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACjC,qCAAqC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa;IACb,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAGzC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAuG;IACzH,OAAO,CAAC,mBAAmB,CAAwC;IACnE,OAAO,CAAC,KAAK,CAAiB;gBAElB,MAAM,EAAE,iBAAiB;IAUrC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAKvD;;;;;OAKG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA8B7D;;;;;OAKG;YACW,eAAe;IAkC7B;;;OAGG;YACW,SAAS;IAavB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0C1B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgDvB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAU/C;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,SAAK,GAAG,OAAO;CAKhE"}

package/dist/JwtVerifier.js

@@ -0,0 +1,259 @@
+/**
+ * JWT Verifier — Standards-Compliant Token Verification
+ *
+ * Verifies JWTs using `jose` when installed, or falls back to
+ * native `crypto.subtle` (Web Crypto API) for HS256 verification.
+ *
+ * Supports:
+ * - HS256, RS256, ES256 (via jose)
+ * - HS256 native fallback (via crypto.subtle)
+ * - JWKS endpoint auto-discovery
+ * - Claims validation: `exp`, `nbf`, `iss`, `aud`
+ *
+ * @example
+ * ```ts
+ * import { JwtVerifier } from '@vurb/jwt';
+ *
+ * // With symmetric secret (HS256)
+ * const verifier = new JwtVerifier({ secret: 'my-secret' });
+ *
+ * // With JWKS endpoint (RS256, ES256)
+ * const verifier = new JwtVerifier({ jwksUri: 'https://auth.example.com/.well-known/jwks.json' });
+ *
+ * const payload = await verifier.verify(token);
+ * if (payload) console.log(payload.sub); // user ID
+ * ```
+ */
+import * as crypto from 'node:crypto';
+// ============================================================================
+// JwtVerifier
+// ============================================================================
+export class JwtVerifier {
+    _config;
+    _clockTolerance;
+    // Lazy-loaded jose references
+    _joseLoaded = false;
+    _jwtVerify = null;
+    _createRemoteJWKSet = null;
+    _jwks = null;
+    constructor(config) {
+        if (!config.secret && !config.jwksUri && !config.publicKey) {
+            throw new Error('JwtVerifier requires at least one of: secret, jwksUri, publicKey');
+        }
+        this._config = config;
+        this._clockTolerance = config.clockTolerance ?? 60;
+    }
+    // ── Public API ───────────────────────────────────────
+    /**
+     * Verify a JWT and return the decoded payload.
+     *
+     * @param token - Raw JWT string (without "Bearer " prefix)
+     * @returns The decoded payload, or `null` if verification fails
+     */
+    async verify(token) {
+        const result = await this.verifyDetailed(token);
+        return result.valid ? result.payload : null;
+    }
+    /**
+     * Verify a JWT with detailed result including error reason.
+     *
+     * @param token - Raw JWT string
+     * @returns Detailed verification result
+     */
+    async verifyDetailed(token) {
+        if (!token || typeof token !== 'string') {
+            return { valid: false, reason: 'Token is empty or not a string' };
+        }
+        try {
+            // Try jose first (supports all algorithms)
+            const payload = await this._verifyWithJose(token);
+            if (payload !== undefined) {
+                return this._validateClaims(payload);
+            }
+            // Fallback: native HS256 verification (secret only)
+            if (this._config.secret) {
+                const payload = this._verifyHS256Native(token);
+                if (payload) {
+                    return this._validateClaims(payload);
+                }
+                return { valid: false, reason: 'Signature verification failed' };
+            }
+            return { valid: false, reason: 'No verification method available (install jose for RS256/ES256)' };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { valid: false, reason: message };
+        }
+    }
+    // ── Jose Integration ─────────────────────────────────
+    /**
+     * Attempt to verify using jose.
+     * Returns `undefined` if jose is not installed.
+     *
+     * @internal
+     */
+    async _verifyWithJose(token) {
+        if (!this._joseLoaded) {
+            await this._loadJose();
+        }
+        if (!this._jwtVerify)
+            return undefined;
+        const options = {};
+        if (this._config.issuer)
+            options['issuer'] = this._config.issuer;
+        if (this._config.audience)
+            options['audience'] = this._config.audience;
+        options['clockTolerance'] = this._clockTolerance;
+        let key;
+        if (this._config.jwksUri) {
+            if (!this._jwks && this._createRemoteJWKSet) {
+                this._jwks = this._createRemoteJWKSet(new URL(this._config.jwksUri));
+            }
+            key = this._jwks;
+        }
+        else if (this._config.publicKey) {
+            // jose importSPKI for PEM keys
+            const jose = await import('jose');
+            key = await jose.importSPKI(this._config.publicKey, this._config.algorithm ?? 'RS256');
+        }
+        else if (this._config.secret) {
+            const encoder = new TextEncoder();
+            key = encoder.encode(this._config.secret);
+        }
+        if (!key)
+            return undefined;
+        const result = await this._jwtVerify(token, key, options);
+        return result.payload;
+    }
+    /**
+     * Load jose dynamically. Silently fails if not installed.
+     * @internal
+     */
+    async _loadJose() {
+        this._joseLoaded = true;
+        try {
+            const jose = await import('jose');
+            this._jwtVerify = jose.jwtVerify;
+            this._createRemoteJWKSet = jose.createRemoteJWKSet;
+        }
+        catch {
+            // jose not installed — will use native fallback
+        }
+    }
+    // ── Native HS256 Fallback ────────────────────────────
+    /**
+     * Verify HS256 JWT using Node.js native crypto.
+     * @internal
+     */
+    _verifyHS256Native(token) {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const headerB64 = parts[0];
+        const payloadB64 = parts[1];
+        const signatureB64 = parts[2];
+        // Verify header
+        try {
+            const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString());
+            if (header.alg !== 'HS256')
+                return null; // Only HS256 in native mode
+        }
+        catch {
+            return null;
+        }
+        // Verify signature
+        const expectedSignature = crypto
+            .createHmac('sha256', this._config.secret)
+            .update(`${headerB64}.${payloadB64}`)
+            .digest('base64url');
+        // Guard against RangeError from timingSafeEqual when
+        // a malformed JWT carries a truncated or oversized signature.
+        // The length check is safe — the expected length (32 bytes for
+        // SHA-256) is publicly known and leaks no secret information.
+        const sigBuf = Buffer.from(signatureB64, 'base64url');
+        const expBuf = Buffer.from(expectedSignature, 'base64url');
+        if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
+            return null;
+        }
+        // Decode payload
+        try {
+            return JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Claims Validation ────────────────────────────────
+    /**
+     * Validate claims (exp, nbf, required) on an already signature-verified payload.
+     * @internal
+     */
+    _validateClaims(payload) {
+        const now = Math.floor(Date.now() / 1000);
+        // Check expiration
+        if (payload.exp !== undefined) {
+            if (now > payload.exp + this._clockTolerance) {
+                return { valid: false, reason: 'Token has expired' };
+            }
+        }
+        // Check not-before
+        if (payload.nbf !== undefined) {
+            if (now < payload.nbf - this._clockTolerance) {
+                return { valid: false, reason: 'Token is not yet valid (nbf)' };
+            }
+        }
+        // Check issuer (when not using jose, which validates it internally)
+        if (this._config.issuer && !this._jwtVerify) {
+            const issuers = Array.isArray(this._config.issuer) ? this._config.issuer : [this._config.issuer];
+            if (!payload.iss || !issuers.includes(payload.iss)) {
+                return { valid: false, reason: `Invalid issuer: ${payload.iss}` };
+            }
+        }
+        // Check audience (when not using jose)
+        if (this._config.audience && !this._jwtVerify) {
+            const audiences = Array.isArray(this._config.audience) ? this._config.audience : [this._config.audience];
+            const tokenAud = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
+            if (!tokenAud.some(a => audiences.includes(a))) {
+                return { valid: false, reason: `Invalid audience: ${payload.aud}` };
+            }
+        }
+        // Check required claims
+        if (this._config.requiredClaims) {
+            for (const claim of this._config.requiredClaims) {
+                if (payload[claim] === undefined) {
+                    return { valid: false, reason: `Missing required claim: ${claim}` };
+                }
+            }
+        }
+        return { valid: true, payload };
+    }
+    // ── Utilities ────────────────────────────────────────
+    /**
+     * Decode a JWT payload WITHOUT verifying the signature.
+     * Useful for inspecting tokens in logging/debugging.
+     *
+     * ⚠️ Never trust decoded-only payloads for authorization decisions.
+     */
+    static decode(token) {
+        try {
+            const parts = token.split('.');
+            if (parts.length !== 3)
+                return null;
+            return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if a token is expired without verifying signature.
+     * Returns `true` if expired or unparseable.
+     */
+    static isExpired(token, clockTolerance = 60) {
+        const payload = JwtVerifier.decode(token);
+        if (!payload?.exp)
+            return true;
+        return Math.floor(Date.now() / 1000) > payload.exp + clockTolerance;
+    }
+}
+//# sourceMappingURL=JwtVerifier.js.map

package/dist/JwtVerifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtVerifier.js","sourceRoot":"","sources":["../src/JwtVerifier.ts"],"names":[],"mappings":"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"}

package/dist/createJwtAuthTool.d.ts

@@ -0,0 +1,43 @@
+/**
+ * JWT Auth Tool Factory — Pre-built JWT Verification Tool
+ *
+ * Creates a complete vurb tool with verify and status actions.
+ * Consumers only need to provide their JWT verification config.
+ *
+ * @example
+ * ```ts
+ * import { createJwtAuthTool } from '@vurb/jwt';
+ *
+ * const jwtTool = createJwtAuthTool({
+ *     secret: process.env.JWT_SECRET!,
+ *     toolName: 'jwt_auth',
+ * });
+ * ```
+ */
+import type { JwtVerifierConfig } from './JwtVerifier.js';
+export interface JwtAuthToolConfig<TContext = unknown> extends JwtVerifierConfig {
+    /** Tool name in MCP. Default: 'jwt_auth' */
+    readonly toolName?: string;
+    /** Tool description for the LLM. */
+    readonly description?: string;
+    /** Tags for selective tool exposure. */
+    readonly tags?: string[];
+    /**
+     * Extracts the JWT from the context.
+     * Required for the `status` action.
+     */
+    readonly extractToken?: (ctx: TContext) => string | null | undefined;
+}
+/**
+ * Creates a complete JWT auth tool with verify and status actions.
+ *
+ * Actions:
+ * - `verify` — Verify a JWT and return decoded claims
+ * - `status` — Check if JWT is present/valid/expired
+ */
+export declare function createJwtAuthTool<TContext = unknown>(config: JwtAuthToolConfig<TContext>): import("vurb").GroupedToolBuilder<TContext, Record<string, never>, string, Record<string, never> & {
+    [x: `${string}.verify`]: Record<string, unknown>;
+} & {
+    [x: `${string}.status`]: Record<string, unknown>;
+}>;
+//# sourceMappingURL=createJwtAuthTool.d.ts.map

package/dist/createJwtAuthTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createJwtAuthTool.d.ts","sourceRoot":"","sources":["../src/createJwtAuthTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,kBAAkB,CAAC;AAMtE,MAAM,WAAW,iBAAiB,CAAC,QAAQ,GAAG,OAAO,CAAE,SAAQ,iBAAiB;IAC5E,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,oCAAoC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACxE;AAkBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC;;;;GAuFxF"}

package/dist/createJwtAuthTool.js

@@ -0,0 +1,115 @@
+/**
+ * JWT Auth Tool Factory — Pre-built JWT Verification Tool
+ *
+ * Creates a complete vurb tool with verify and status actions.
+ * Consumers only need to provide their JWT verification config.
+ *
+ * @example
+ * ```ts
+ * import { createJwtAuthTool } from '@vurb/jwt';
+ *
+ * const jwtTool = createJwtAuthTool({
+ *     secret: process.env.JWT_SECRET!,
+ *     toolName: 'jwt_auth',
+ * });
+ * ```
+ */
+import { createTool } from 'vurb';
+import { JwtVerifier } from './JwtVerifier.js';
+// ============================================================================
+// Response Helpers
+// ============================================================================
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function fail(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], isError: true };
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a complete JWT auth tool with verify and status actions.
+ *
+ * Actions:
+ * - `verify` — Verify a JWT and return decoded claims
+ * - `status` — Check if JWT is present/valid/expired
+ */
+export function createJwtAuthTool(config) {
+    const verifier = new JwtVerifier(config);
+    const toolName = config.toolName ?? 'jwt_auth';
+    const description = config.description ?? 'JWT authentication — verify tokens and check status';
+    const extractToken = config.extractToken;
+    const tool = createTool(toolName);
+    if (config.tags?.length) {
+        tool.tags(...config.tags);
+    }
+    return tool
+        .action({
+        name: 'verify',
+        description: 'Verify a JWT and return decoded claims',
+        handler: async (_ctx, args) => {
+            const token = args['token'];
+            if (!token) {
+                return fail({ message: 'Token is required' });
+            }
+            const rawToken = token.startsWith('Bearer ') ? token.slice(7) : token;
+            const result = await verifier.verifyDetailed(rawToken);
+            if (!result.valid) {
+                return fail({
+                    message: `Verification failed: ${result.reason}`,
+                    valid: false,
+                });
+            }
+            return ok({
+                valid: true,
+                payload: result.payload,
+                claims: {
+                    sub: result.payload?.sub,
+                    iss: result.payload?.iss,
+                    aud: result.payload?.aud,
+                    exp: result.payload?.exp,
+                    iat: result.payload?.iat,
+                },
+            });
+        },
+    })
+        .action({
+        name: 'status',
+        description: 'Check JWT authentication status from context',
+        handler: async (ctx) => {
+            if (!extractToken) {
+                return ok({
+                    available: false,
+                    reason: 'No token extractor configured',
+                });
+            }
+            const raw = extractToken(ctx);
+            if (!raw) {
+                return ok({
+                    authenticated: false,
+                    reason: 'No JWT found in context',
+                });
+            }
+            const token = typeof raw === 'string' && raw.startsWith('Bearer ') ? raw.slice(7) : raw;
+            // Decode without verification for status info
+            const decoded = JwtVerifier.decode(token);
+            const isExpired = JwtVerifier.isExpired(token, config.clockTolerance);
+            // Full verification
+            const result = await verifier.verifyDetailed(token);
+            return ok({
+                authenticated: result.valid,
+                expired: isExpired,
+                valid: result.valid,
+                reason: result.reason,
+                claims: decoded ? {
+                    sub: decoded.sub,
+                    iss: decoded.iss,
+                    exp: decoded.exp ? new Date(decoded.exp * 1000).toISOString() : undefined,
+                    iat: decoded.iat ? new Date(decoded.iat * 1000).toISOString() : undefined,
+                } : undefined,
+            });
+        },
+    });
+}
+//# sourceMappingURL=createJwtAuthTool.js.map

package/dist/createJwtAuthTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createJwtAuthTool.js","sourceRoot":"","sources":["../src/createJwtAuthTool.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @vurb/jwt — JWT Verification for MCP Servers
+ *
+ * Standards-compliant JWT verification with jose integration,
+ * native HS256 fallback, and vurb middleware.
+ *
+ * @example
+ * ```ts
+ * import { JwtVerifier, requireJwt, createJwtAuthTool } from '@vurb/jwt';
+ *
+ * // Middleware
+ * const projects = createTool('projects')
+ *     .use(requireJwt({ secret: 'my-secret' }))
+ *     .action({ name: 'list', handler: async () => success([]) });
+ *
+ * // Standalone
+ * const verifier = new JwtVerifier({ secret: 'my-secret' });
+ * const payload = await verifier.verify(token);
+ * ```
+ *
+ * @module @vurb/jwt
+ * @author Vinkius Labs
+ * @license Apache-2.0
+ */
+export { JwtVerifier } from './JwtVerifier.js';
+export type { JwtVerifierConfig, JwtPayload, JwtVerifyResult, } from './JwtVerifier.js';
+export { createJwtAuthTool } from './createJwtAuthTool.js';
+export type { JwtAuthToolConfig } from './createJwtAuthTool.js';
+export { requireJwt } from './middleware.js';
+export type { RequireJwtOptions } from './middleware.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACR,iBAAiB,EACjB,UAAU,EACV,eAAe,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * @vurb/jwt — JWT Verification for MCP Servers
+ *
+ * Standards-compliant JWT verification with jose integration,
+ * native HS256 fallback, and vurb middleware.
+ *
+ * @example
+ * ```ts
+ * import { JwtVerifier, requireJwt, createJwtAuthTool } from '@vurb/jwt';
+ *
+ * // Middleware
+ * const projects = createTool('projects')
+ *     .use(requireJwt({ secret: 'my-secret' }))
+ *     .action({ name: 'list', handler: async () => success([]) });
+ *
+ * // Standalone
+ * const verifier = new JwtVerifier({ secret: 'my-secret' });
+ * const payload = await verifier.verify(token);
+ * ```
+ *
+ * @module @vurb/jwt
+ * @author Vinkius Labs
+ * @license Apache-2.0
+ */
+export { JwtVerifier } from './JwtVerifier.js';
+export { createJwtAuthTool } from './createJwtAuthTool.js';
+export { requireJwt } from './middleware.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAO/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,54 @@
+/**
+ * JWT Auth Middleware — requireJwt()
+ *
+ * vurb middleware that ensures requests carry a valid JWT.
+ * Extracts the token, verifies it via JwtVerifier, and rejects
+ * invalid/expired/missing tokens with self-healing error responses.
+ *
+ * @example
+ * ```ts
+ * import { requireJwt } from '@vurb/jwt';
+ *
+ * const projects = createTool('projects')
+ *     .use(requireJwt({ secret: process.env.JWT_SECRET! }))
+ *     .action({ name: 'list', handler: async (ctx) => { ... } });
+ * ```
+ */
+import type { ToolResponse } from 'vurb';
+import type { JwtVerifierConfig, JwtPayload } from './JwtVerifier.js';
+export interface RequireJwtOptions extends JwtVerifierConfig {
+    /**
+     * Custom function to extract the JWT from the context.
+     * Default: checks `ctx.token`, `ctx.jwt`, `ctx.headers.authorization` (Bearer).
+     */
+    readonly extractToken?: (ctx: unknown) => string | null | undefined;
+    /**
+     * Callback invoked after successful verification.
+     * Use this to inject the decoded payload into the context.
+     *
+     * @example
+     * ```ts
+     * requireJwt({
+     *     secret: 'my-secret',
+     *     onVerified: (ctx, payload) => {
+     *         (ctx as any).userId = payload.sub;
+     *     },
+     * });
+     * ```
+     */
+    readonly onVerified?: (ctx: unknown, payload: JwtPayload) => void;
+    /** Error code for toolError response. Default: 'JWT_INVALID' */
+    readonly errorCode?: string;
+    /** Recovery hint for the LLM. Default: 'Provide a valid JWT in the authorization context' */
+    readonly recoveryHint?: string;
+    /** Recovery action name. Default: 'auth' */
+    readonly recoveryAction?: string;
+}
+/**
+ * Creates a vurb middleware that verifies JWTs.
+ *
+ * Returns `toolError('JWT_INVALID')` with self-healing hints
+ * when no valid JWT is found.
+ */
+export declare function requireJwt(options: RequireJwtOptions): (ctx: unknown, _args: Record<string, unknown>, next: () => Promise<ToolResponse>) => Promise<ToolResponse>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtE,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IACxD;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAEpE;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IAElE,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,6FAA6F;IAC7F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACpC;AAMD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,IAQnC,KAAK,OAAO,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,OAAO,CAAC,YAAY,CAAC,KAAG,OAAO,CAAC,YAAY,CAAC,CA8BxH"}

package/dist/middleware.js

@@ -0,0 +1,91 @@
+/**
+ * JWT Auth Middleware — requireJwt()
+ *
+ * vurb middleware that ensures requests carry a valid JWT.
+ * Extracts the token, verifies it via JwtVerifier, and rejects
+ * invalid/expired/missing tokens with self-healing error responses.
+ *
+ * @example
+ * ```ts
+ * import { requireJwt } from '@vurb/jwt';
+ *
+ * const projects = createTool('projects')
+ *     .use(requireJwt({ secret: process.env.JWT_SECRET! }))
+ *     .action({ name: 'list', handler: async (ctx) => { ... } });
+ * ```
+ */
+import { toolError } from 'vurb';
+import { JwtVerifier } from './JwtVerifier.js';
+// ============================================================================
+// Middleware Factory
+// ============================================================================
+/**
+ * Creates a vurb middleware that verifies JWTs.
+ *
+ * Returns `toolError('JWT_INVALID')` with self-healing hints
+ * when no valid JWT is found.
+ */
+export function requireJwt(options) {
+    const verifier = new JwtVerifier(options);
+    const extractToken = options.extractToken ?? defaultExtractToken;
+    const errorCode = options.errorCode ?? 'JWT_INVALID';
+    const recoveryHint = options.recoveryHint ?? 'Provide a valid JWT in the authorization context';
+    const recoveryAction = options.recoveryAction ?? 'auth';
+    const onVerified = options.onVerified;
+    return async (ctx, _args, next) => {
+        const raw = extractToken(ctx);
+        if (!raw) {
+            return toolError(errorCode, {
+                message: 'JWT authentication required',
+                suggestion: recoveryHint,
+                availableActions: [recoveryAction],
+            });
+        }
+        // Strip "Bearer " prefix if present
+        const token = raw.startsWith('Bearer ') ? raw.slice(7) : raw;
+        const result = await verifier.verifyDetailed(token);
+        if (!result.valid) {
+            return toolError(errorCode, {
+                message: `JWT verification failed: ${result.reason}`,
+                suggestion: recoveryHint,
+                availableActions: [recoveryAction],
+            });
+        }
+        if (onVerified && result.payload) {
+            onVerified(ctx, result.payload);
+        }
+        return next();
+    };
+}
+// ============================================================================
+// Default Token Extractor
+// ============================================================================
+/**
+ * Default JWT extractor — checks common patterns:
+ * - `ctx.token`
+ * - `ctx.jwt`
+ * - `ctx.headers.authorization` (Bearer prefix)
+ */
+function defaultExtractToken(ctx) {
+    if (!ctx || typeof ctx !== 'object')
+        return null;
+    const obj = ctx;
+    // Direct token property
+    if (typeof obj['token'] === 'string' && obj['token']) {
+        return obj['token'];
+    }
+    // JWT property
+    if (typeof obj['jwt'] === 'string' && obj['jwt']) {
+        return obj['jwt'];
+    }
+    // Authorization header
+    const headers = obj['headers'];
+    if (headers) {
+        const auth = headers['authorization'];
+        if (typeof auth === 'string' && auth) {
+            return auth;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@vurb/jwt",
+  "version": "3.1.31",
+  "description": "JWT verification middleware for MCP servers built with vurb. Standards-compliant token validation with jose, JWKS support, and self-healing error responses.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "vurb",
+    "jwt",
+    "json-web-token",
+    "authentication",
+    "middleware",
+    "ai",
+    "llm"
+  ],
+  "author": "Renato Marinho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinkius-labs/vurb.ts.git",
+    "directory": "packages/jwt"
+  },
+  "bugs": {
+    "url": "https://github.com/vinkius-labs/vurb.ts/issues"
+  },
+  "homepage": "https://vurb.vinkius.com/",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@vurb/core": "^3.0.0",
+    "jose": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vurb/core": ">=3.0.0"
+  },
+  "license": "Apache-2.0"
+}