@uploadista/server 0.0.3

package/dist/auth/jwt/validate.d.ts

@@ -0,0 +1,58 @@
+import type { AuthContext } from "../types";
+import type { JwtValidationConfig, JwtValidationResult } from "./types";
+/**
+ * Validates a JWT token and returns the validation result with claims.
+ *
+ * This function verifies:
+ * - Token signature using the provided secret/public key
+ * - Token expiry (with clock tolerance)
+ * - Issuer claim (if configured)
+ * - Audience claim (if configured)
+ * - Required subject (sub) claim presence
+ *
+ * @param token - The JWT token string to validate
+ * @param config - Validation configuration (secret, issuer, audience, etc.)
+ * @returns JwtValidationResult with success status and claims or error
+ *
+ * @example
+ * ```typescript
+ * const result = await validateJwtToken(token, {
+ *   secret: 'my-secret-key',
+ *   issuer: 'https://auth.example.com',
+ *   audience: 'uploadista-api',
+ *   clockTolerance: 60,
+ * });
+ *
+ * if (result.success) {
+ *   console.log('User ID:', result.userId);
+ *   console.log('Claims:', result.claims);
+ * } else {
+ *   console.error('Validation failed:', result.error);
+ * }
+ * ```
+ */
+export declare function validateJwtToken(token: string, config: JwtValidationConfig): Promise<JwtValidationResult>;
+/**
+ * Extracts AuthContext from a validated JWT token.
+ * This is a convenience function that combines validation and extraction.
+ *
+ * @param token - The JWT token string to validate and extract from
+ * @param config - Validation configuration
+ * @returns AuthContext if validation succeeds, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const authContext = await extractAuthContextFromJwt(token, {
+ *   secret: process.env.JWT_SECRET,
+ *   issuer: 'https://auth.example.com',
+ * });
+ *
+ * if (authContext) {
+ *   console.log('Authenticated user:', authContext.userId);
+ * } else {
+ *   console.log('Invalid token');
+ * }
+ * ```
+ */
+export declare function extractAuthContextFromJwt(token: string, config: JwtValidationConfig): Promise<AuthContext | null>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/auth/jwt/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/auth/jwt/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAmF9B;AA6ED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAmC7B"}

package/dist/auth/jwt/validate.js

@@ -0,0 +1,226 @@
+import { jwtVerify } from "jose";
+/**
+ * Validates a JWT token and returns the validation result with claims.
+ *
+ * This function verifies:
+ * - Token signature using the provided secret/public key
+ * - Token expiry (with clock tolerance)
+ * - Issuer claim (if configured)
+ * - Audience claim (if configured)
+ * - Required subject (sub) claim presence
+ *
+ * @param token - The JWT token string to validate
+ * @param config - Validation configuration (secret, issuer, audience, etc.)
+ * @returns JwtValidationResult with success status and claims or error
+ *
+ * @example
+ * ```typescript
+ * const result = await validateJwtToken(token, {
+ *   secret: 'my-secret-key',
+ *   issuer: 'https://auth.example.com',
+ *   audience: 'uploadista-api',
+ *   clockTolerance: 60,
+ * });
+ *
+ * if (result.success) {
+ *   console.log('User ID:', result.userId);
+ *   console.log('Claims:', result.claims);
+ * } else {
+ *   console.error('Validation failed:', result.error);
+ * }
+ * ```
+ */
+export async function validateJwtToken(token, config) {
+    try {
+        // Prepare secret/key for validation
+        let secret;
+        if (typeof config.secret === "string") {
+            secret = new TextEncoder().encode(config.secret);
+        }
+        else {
+            secret = config.secret;
+        }
+        // Prepare verification options
+        const options = {
+            clockTolerance: config.clockTolerance ?? 60, // Default 1 minute tolerance
+        };
+        if (config.issuer) {
+            options.issuer = config.issuer;
+        }
+        if (config.audience) {
+            options.audience = config.audience;
+        }
+        if (config.algorithms && config.algorithms.length > 0) {
+            options.algorithms = config.algorithms;
+        }
+        // Verify the JWT
+        let verifyResult;
+        try {
+            verifyResult = await jwtVerify(token, secret, options);
+        }
+        catch (error) {
+            return handleJwtVerifyError(error, config);
+        }
+        const { payload, protectedHeader } = verifyResult;
+        // Validate algorithm if specified
+        if (config.algorithms &&
+            config.algorithms.length > 0 &&
+            !config.algorithms.includes(protectedHeader.alg)) {
+            return {
+                success: false,
+                error: {
+                    type: "INVALID_ALGORITHM",
+                    message: `Invalid algorithm: expected one of [${config.algorithms.join(", ")}], got ${protectedHeader.alg}`,
+                    expected: config.algorithms,
+                    actual: protectedHeader.alg,
+                },
+            };
+        }
+        // Extract userId from sub claim
+        const userId = payload.sub;
+        if (!userId) {
+            return {
+                success: false,
+                error: {
+                    type: "MISSING_SUBJECT",
+                    message: "Token is missing required 'sub' claim. Cannot extract user ID.",
+                },
+            };
+        }
+        // Return success with claims
+        return {
+            success: true,
+            claims: payload,
+            userId,
+        };
+    }
+    catch (error) {
+        // Catch-all for unexpected errors
+        return {
+            success: false,
+            error: {
+                type: "INVALID_TOKEN",
+                message: error instanceof Error ? error.message : "Unknown error occurred",
+            },
+        };
+    }
+}
+/**
+ * Handles errors from jose's jwtVerify and converts them to our error format
+ */
+function handleJwtVerifyError(error, config) {
+    if (!(error instanceof Error)) {
+        return {
+            success: false,
+            error: {
+                type: "INVALID_TOKEN",
+                message: "Unknown validation error occurred",
+            },
+        };
+    }
+    const message = error.message.toLowerCase();
+    // Check for specific error types - order matters!
+    // Check issuer/audience before expired since "exp" might match "expected"
+    if (message.includes("issuer") || message.includes('"iss"') || message.includes("'iss'")) {
+        return {
+            success: false,
+            error: {
+                type: "INVALID_ISSUER",
+                message: "Token issuer does not match expected value",
+                expected: config.issuer ?? "",
+                actual: "unknown",
+            },
+        };
+    }
+    if (message.includes("audience") || message.includes('"aud"') || message.includes("'aud'")) {
+        return {
+            success: false,
+            error: {
+                type: "INVALID_AUDIENCE",
+                message: "Token audience does not match expected value",
+                expected: config.audience ?? "",
+                actual: "unknown",
+            },
+        };
+    }
+    if (message.includes("expired") || (message.includes("exp") && !message.includes("unexpected"))) {
+        return {
+            success: false,
+            error: {
+                type: "EXPIRED",
+                message: "Token has expired",
+            },
+        };
+    }
+    if (message.includes("signature")) {
+        return {
+            success: false,
+            error: {
+                type: "INVALID_SIGNATURE",
+                message: "Invalid token signature",
+            },
+        };
+    }
+    // Default to invalid token error
+    return {
+        success: false,
+        error: {
+            type: "INVALID_TOKEN",
+            message: error.message,
+        },
+    };
+}
+/**
+ * Extracts AuthContext from a validated JWT token.
+ * This is a convenience function that combines validation and extraction.
+ *
+ * @param token - The JWT token string to validate and extract from
+ * @param config - Validation configuration
+ * @returns AuthContext if validation succeeds, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const authContext = await extractAuthContextFromJwt(token, {
+ *   secret: process.env.JWT_SECRET,
+ *   issuer: 'https://auth.example.com',
+ * });
+ *
+ * if (authContext) {
+ *   console.log('Authenticated user:', authContext.userId);
+ * } else {
+ *   console.log('Invalid token');
+ * }
+ * ```
+ */
+export async function extractAuthContextFromJwt(token, config) {
+    const result = await validateJwtToken(token, config);
+    if (!result.success) {
+        return null;
+    }
+    // Extract permissions from claims (if present)
+    const permissions = Array.isArray(result.claims.permissions)
+        ? result.claims.permissions
+        : undefined;
+    // Extract metadata (all claims except standard JWT claims)
+    const standardClaims = new Set([
+        "iss",
+        "sub",
+        "aud",
+        "exp",
+        "nbf",
+        "iat",
+        "jti",
+        "permissions",
+    ]);
+    const metadata = {};
+    for (const [key, value] of Object.entries(result.claims)) {
+        if (!standardClaims.has(key)) {
+            metadata[key] = value;
+        }
+    }
+    return {
+        userId: result.userId,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        permissions,
+    };
+}

package/dist/auth/jwt/validate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/auth/jwt/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../../../src/auth/jwt/validate.test.ts"],"names":[],"mappings":""}