nitrostack 1.0.0

package/dist/auth/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * NitroStack Authentication Module
+ *
+ * Multiple authentication options:
+ * 1. Simple JWT - For 70% of use cases (internal tools, APIs)
+ * 2. API Keys - For simple scenarios (service-to-service)
+ * 3. OAuth 2.1 - For enterprise/SaaS (full compliance)
+ *
+ * Standards:
+ * - OAuth 2.1 (IETF draft-ietf-oauth-v2-1-13)
+ * - RFC 9728 - Protected Resource Metadata
+ * - RFC 8414 - Authorization Server Metadata
+ * - RFC 7591 - Dynamic Client Registration
+ * - RFC 8707 - Resource Indicators (Token Audience Binding)
+ * - RFC 7636 - PKCE
+ * - RFC 7662 - Token Introspection
+ * - RFC 6750 - Bearer Token Usage
+ */
+export { createSimpleJWTAuth, generateJWT, verifyJWT, decodeJWT, type SimpleJWTConfig, type JWTPayload, } from './simple-jwt.js';
+export { createAPIKeyAuth, generateAPIKey, hashAPIKey, isValidAPIKeyFormat, generateAPIKeyWithMetadata, validateAPIKeyWithMetadata, type APIKeyConfig, type APIKeyWithMetadata, } from './api-key.js';
+export { setupJWTAuth, setupAPIKeyAuth, setupOAuthAuth, generateTestCredentials, printAuthSetupInstructions, validateAuthEnv, } from './quick-setup.js';
+export * from './types.js';
+export * from './pkce.js';
+export * from './server-metadata.js';
+export * from './token-validation.js';
+export { createAuthMiddleware, requireScopes, optionalAuth, RequireScopes, isAuthenticated, hasScope, hasAnyScope, hasAllScopes, } from './middleware.js';
+export { OAuth2Client } from './client.js';
+export { TokenStore, MemoryTokenStore, FileTokenStore, createDefaultTokenStore, isTokenExpired, calculateExpiration, tokenResponseToStored, } from './token-store.js';
+export { configureServerAuth, createScopeGuards, createMCPScopeGuards, getStandardMCPScopes, validateAuthConfig, } from './server-integration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAK1B,cAAc,YAAY,CAAC;AAG3B,cAAc,WAAW,CAAC;AAG1B,cAAc,sBAAsB,CAAC;AAGrC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,43 @@
+/**
+ * NitroStack Authentication Module
+ *
+ * Multiple authentication options:
+ * 1. Simple JWT - For 70% of use cases (internal tools, APIs)
+ * 2. API Keys - For simple scenarios (service-to-service)
+ * 3. OAuth 2.1 - For enterprise/SaaS (full compliance)
+ *
+ * Standards:
+ * - OAuth 2.1 (IETF draft-ietf-oauth-v2-1-13)
+ * - RFC 9728 - Protected Resource Metadata
+ * - RFC 8414 - Authorization Server Metadata
+ * - RFC 7591 - Dynamic Client Registration
+ * - RFC 8707 - Resource Indicators (Token Audience Binding)
+ * - RFC 7636 - PKCE
+ * - RFC 7662 - Token Introspection
+ * - RFC 6750 - Bearer Token Usage
+ */
+// ==================== SIMPLE AUTH (Recommended for most users) ====================
+// Simple JWT Auth (no OAuth complexity!)
+export { createSimpleJWTAuth, generateJWT, verifyJWT, decodeJWT, } from './simple-jwt.js';
+// API Key Auth (simplest option)
+export { createAPIKeyAuth, generateAPIKey, hashAPIKey, isValidAPIKeyFormat, generateAPIKeyWithMetadata, validateAPIKeyWithMetadata, } from './api-key.js';
+// Quick Setup Helpers (1-liner auth!)
+export { setupJWTAuth, setupAPIKeyAuth, setupOAuthAuth, generateTestCredentials, printAuthSetupInstructions, validateAuthEnv, } from './quick-setup.js';
+// ==================== OAUTH 2.1 (Advanced users) ====================
+// Types
+export * from './types.js';
+// PKCE utilities
+export * from './pkce.js';
+// Server metadata
+export * from './server-metadata.js';
+// Token validation
+export * from './token-validation.js';
+// Middleware (for servers)
+export { createAuthMiddleware, requireScopes, optionalAuth, RequireScopes, isAuthenticated, hasScope, hasAnyScope, hasAllScopes, } from './middleware.js';
+// OAuth client (for clients)
+export { OAuth2Client } from './client.js';
+// Token storage
+export { MemoryTokenStore, FileTokenStore, createDefaultTokenStore, isTokenExpired, calculateExpiration, tokenResponseToStored, } from './token-store.js';
+// Server integration helpers
+export { configureServerAuth, createScopeGuards, createMCPScopeGuards, getStandardMCPScopes, validateAuthConfig, } from './server-integration.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qFAAqF;AAErF,yCAAyC;AACzC,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,SAAS,GAGV,MAAM,iBAAiB,CAAC;AAEzB,iCAAiC;AACjC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,GAG3B,MAAM,cAAc,CAAC;AAEtB,sCAAsC;AACtC,OAAO,EACL,YAAY,EACZ,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AAEvE,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,iBAAiB;AACjB,cAAc,WAAW,CAAC;AAE1B,kBAAkB;AAClB,cAAc,sBAAsB,CAAC;AAErC,mBAAmB;AACnB,cAAc,uBAAuB,CAAC;AAEtC,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,gBAAgB;AAChB,OAAO,EAEL,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,6BAA6B;AAC7B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC"}

package/dist/auth/middleware.d.ts

@@ -0,0 +1,95 @@
+import { Request, RequestHandler } from 'express';
+import { McpAuthConfig, AuthContext } from './types.js';
+/**
+ * Auth Middleware for Express
+ *
+ * Protects MCP server routes with OAuth 2.1 Bearer token authentication
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            auth?: AuthContext;
+        }
+    }
+}
+/**
+ * Create authentication middleware
+ *
+ * @param config - Auth configuration
+ * @returns Express middleware
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = createAuthMiddleware({
+ *   resourceUri: 'https://mcp.example.com',
+ *   authorizationServers: ['https://auth.example.com'],
+ *   tokenIntrospectionEndpoint: 'https://auth.example.com/oauth/introspect',
+ *   tokenIntrospectionClientId: 'mcp-server',
+ *   tokenIntrospectionClientSecret: process.env.INTROSPECTION_SECRET,
+ *   audience: 'https://mcp.example.com',
+ *   scopesSupported: ['mcp:read', 'mcp:write', 'mcp:admin']
+ * });
+ *
+ * app.use('/mcp', authMiddleware);
+ * ```
+ */
+export declare function createAuthMiddleware(config: McpAuthConfig): RequestHandler;
+/**
+ * Require specific scopes
+ *
+ * @param requiredScopes - Scopes required to access this route
+ * @returns Express middleware
+ *
+ * @example
+ * ```typescript
+ * app.post('/mcp/tools/execute',
+ *   authMiddleware,
+ *   requireScopes('mcp:write'),
+ *   (req, res) => {
+ *     // Handle tool execution
+ *   }
+ * );
+ * ```
+ */
+export declare function requireScopes(...requiredScopes: string[]): RequestHandler;
+/**
+ * Optional authentication
+ *
+ * Attempts to authenticate but allows request to proceed even without auth.
+ * Useful for endpoints that have different behavior for authenticated users.
+ *
+ * @param config - Auth configuration
+ * @returns Express middleware
+ */
+export declare function optionalAuth(config: McpAuthConfig): RequestHandler;
+/**
+ * Scope-based access control decorator
+ *
+ * @example
+ * ```typescript
+ * class ToolController {
+ *   @RequireScopes('mcp:write', 'tools:execute')
+ *   async executeTool(req: Request, res: Response) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function RequireScopes(...scopes: string[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Check if request is authenticated
+ */
+export declare function isAuthenticated(req: Request): boolean;
+/**
+ * Check if request has specific scope
+ */
+export declare function hasScope(req: Request, scope: string): boolean;
+/**
+ * Check if request has any of the specified scopes
+ */
+export declare function hasAnyScope(req: Request, scopes: string[]): boolean;
+/**
+ * Check if request has all of the specified scopes
+ */
+export declare function hasAllScopes(req: Request, scopes: string[]): boolean;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIxD;;;;GAIG;AAGH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,WAAW,CAAC;SACpB;KACF;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAmD1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,GAAG,cAAc,EAAE,MAAM,EAAE,GAAG,cAAc,CAmBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAmClE;AAiFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,IAE7C,QAAQ,GAAG,EACX,aAAa,MAAM,EACnB,YAAY,kBAAkB,wBAsBjC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAEnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAEpE"}

package/dist/auth/middleware.js

@@ -0,0 +1,260 @@
+import { validateToken, extractBearerToken, validateScopes } from './token-validation.js';
+import { generateWWWAuthenticateHeader } from './server-metadata.js';
+/**
+ * Create authentication middleware
+ *
+ * @param config - Auth configuration
+ * @returns Express middleware
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = createAuthMiddleware({
+ *   resourceUri: 'https://mcp.example.com',
+ *   authorizationServers: ['https://auth.example.com'],
+ *   tokenIntrospectionEndpoint: 'https://auth.example.com/oauth/introspect',
+ *   tokenIntrospectionClientId: 'mcp-server',
+ *   tokenIntrospectionClientSecret: process.env.INTROSPECTION_SECRET,
+ *   audience: 'https://mcp.example.com',
+ *   scopesSupported: ['mcp:read', 'mcp:write', 'mcp:admin']
+ * });
+ *
+ * app.use('/mcp', authMiddleware);
+ * ```
+ */
+export function createAuthMiddleware(config) {
+    // Enforce HTTPS in production
+    if (config.requireHttps !== false && process.env.NODE_ENV === 'production') {
+        validateHttpsConfig();
+    }
+    return async (req, res, next) => {
+        try {
+            // 1. Extract Bearer token from Authorization header
+            const authHeader = req.headers.authorization;
+            const token = extractBearerToken(authHeader);
+            if (!token) {
+                // No token provided - return 401 with WWW-Authenticate challenge
+                return sendUnauthorized(res, config, 'No Bearer token provided');
+            }
+            // 2. Validate token
+            const validationResult = await validateToken(token, config);
+            if (!validationResult.valid || !validationResult.introspection) {
+                // Invalid token - return 401
+                return sendUnauthorized(res, config, validationResult.error || 'Invalid token', 'invalid_token');
+            }
+            const introspection = validationResult.introspection;
+            // 3. Attach auth context to request
+            req.auth = {
+                authenticated: true,
+                tokenInfo: introspection,
+                scopes: introspection.scope ? introspection.scope.split(' ') : [],
+                clientId: introspection.client_id,
+                subject: introspection.sub,
+            };
+            // 4. Continue to next middleware
+            next();
+        }
+        catch (error) {
+            // Server error during validation
+            res.status(500).json({
+                error: 'server_error',
+                error_description: 'Token validation failed',
+            });
+        }
+    };
+}
+/**
+ * Require specific scopes
+ *
+ * @param requiredScopes - Scopes required to access this route
+ * @returns Express middleware
+ *
+ * @example
+ * ```typescript
+ * app.post('/mcp/tools/execute',
+ *   authMiddleware,
+ *   requireScopes('mcp:write'),
+ *   (req, res) => {
+ *     // Handle tool execution
+ *   }
+ * );
+ * ```
+ */
+export function requireScopes(...requiredScopes) {
+    return (req, res, next) => {
+        if (!req.auth || !req.auth.authenticated) {
+            return res.status(401).json({
+                error: 'unauthorized',
+                error_description: 'Authentication required',
+            });
+        }
+        // Check if token has all required scopes
+        const hasScopes = validateScopes(req.auth.tokenInfo, requiredScopes);
+        if (!hasScopes) {
+            // Insufficient scope - return 403 with step-up challenge
+            return sendInsufficientScope(res, requiredScopes, req.auth.scopes);
+        }
+        next();
+    };
+}
+/**
+ * Optional authentication
+ *
+ * Attempts to authenticate but allows request to proceed even without auth.
+ * Useful for endpoints that have different behavior for authenticated users.
+ *
+ * @param config - Auth configuration
+ * @returns Express middleware
+ */
+export function optionalAuth(config) {
+    return async (req, res, next) => {
+        try {
+            const authHeader = req.headers.authorization;
+            const token = extractBearerToken(authHeader);
+            if (!token) {
+                // No token - proceed without auth
+                req.auth = { authenticated: false, scopes: [] };
+                return next();
+            }
+            const validationResult = await validateToken(token, config);
+            if (validationResult.valid && validationResult.introspection) {
+                req.auth = {
+                    authenticated: true,
+                    tokenInfo: validationResult.introspection,
+                    scopes: validationResult.introspection.scope
+                        ? validationResult.introspection.scope.split(' ')
+                        : [],
+                    clientId: validationResult.introspection.client_id,
+                    subject: validationResult.introspection.sub,
+                };
+            }
+            else {
+                req.auth = { authenticated: false, scopes: [] };
+            }
+            next();
+        }
+        catch (error) {
+            // On error, proceed without auth
+            req.auth = { authenticated: false, scopes: [] };
+            next();
+        }
+    };
+}
+/**
+ * Send 401 Unauthorized response with WWW-Authenticate header
+ */
+function sendUnauthorized(res, config, description, error) {
+    // Generate WWW-Authenticate header
+    const wwwAuthenticate = generateWWWAuthenticateHeader({
+        resourceMetadataUrl: getWellKnownMetadataUrl(config.resourceUri),
+        scope: config.scopesSupported?.join(' '),
+        error,
+        errorDescription: description,
+    });
+    res.status(401)
+        .header('WWW-Authenticate', wwwAuthenticate)
+        .json({
+        error: error || 'unauthorized',
+        error_description: description,
+    });
+}
+/**
+ * Send 403 Forbidden response with insufficient_scope error
+ * This triggers step-up authorization flow in clients
+ */
+function sendInsufficientScope(res, requiredScopes, currentScopes) {
+    // Include both current and required scopes for step-up
+    const allScopes = [...new Set([...currentScopes, ...requiredScopes])];
+    const wwwAuthenticate = generateWWWAuthenticateHeader({
+        error: 'insufficient_scope',
+        scope: allScopes.join(' '),
+        errorDescription: `Required scopes: ${requiredScopes.join(', ')}`,
+    });
+    res.status(403)
+        .header('WWW-Authenticate', wwwAuthenticate)
+        .json({
+        error: 'insufficient_scope',
+        error_description: `Required scopes: ${requiredScopes.join(', ')}`,
+        required_scopes: requiredScopes,
+        current_scopes: currentScopes,
+    });
+}
+/**
+ * Get well-known metadata URL for this resource
+ */
+function getWellKnownMetadataUrl(resourceUri) {
+    try {
+        const url = new URL(resourceUri);
+        return `${url.origin}/.well-known/oauth-protected-resource`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Validate HTTPS configuration
+ */
+function validateHttpsConfig() {
+    // In production, should be running behind HTTPS
+    // This is a warning, not a hard failure
+    if (process.env.NODE_ENV === 'production') {
+        console.warn('⚠️  WARNING: OAuth 2.1 requires HTTPS in production. ' +
+            'Ensure your server is behind a reverse proxy with TLS termination.');
+    }
+}
+/**
+ * Scope-based access control decorator
+ *
+ * @example
+ * ```typescript
+ * class ToolController {
+ *   @RequireScopes('mcp:write', 'tools:execute')
+ *   async executeTool(req: Request, res: Response) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function RequireScopes(...scopes) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (req, res, next) {
+            if (!req.auth || !req.auth.authenticated) {
+                return res.status(401).json({
+                    error: 'unauthorized',
+                    error_description: 'Authentication required',
+                });
+            }
+            const hasScopes = validateScopes(req.auth.tokenInfo, scopes);
+            if (!hasScopes) {
+                return sendInsufficientScope(res, scopes, req.auth.scopes);
+            }
+            return originalMethod.apply(this, arguments);
+        };
+        return descriptor;
+    };
+}
+/**
+ * Check if request is authenticated
+ */
+export function isAuthenticated(req) {
+    return req.auth?.authenticated === true;
+}
+/**
+ * Check if request has specific scope
+ */
+export function hasScope(req, scope) {
+    return req.auth?.scopes.includes(scope) === true;
+}
+/**
+ * Check if request has any of the specified scopes
+ */
+export function hasAnyScope(req, scopes) {
+    return scopes.some((scope) => hasScope(req, scope));
+}
+/**
+ * Check if request has all of the specified scopes
+ */
+export function hasAllScopes(req, scopes) {
+    return scopes.every((scope) => hasScope(req, scope));
+}
+//# sourceMappingURL=middleware.js.map

package/dist/auth/middleware.js.map

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

package/dist/auth/pkce.d.ts

@@ -0,0 +1,53 @@
+import { PKCEParams } from './types.js';
+export type { PKCEParams } from './types.js';
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ * Implements RFC 7636
+ *
+ * PKCE is REQUIRED by OAuth 2.1 to prevent authorization code interception attacks
+ */
+/**
+ * Generate a cryptographically secure random code verifier
+ *
+ * Per RFC 7636:
+ * - code_verifier = high-entropy cryptographic random STRING
+ * - using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * - minimum length of 43 characters and maximum length of 128 characters
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generate code challenge from code verifier
+ *
+ * @param codeVerifier - The code verifier string
+ * @param method - Challenge method: 'S256' (SHA-256) or 'plain'
+ */
+export declare function generateCodeChallenge(codeVerifier: string, method?: 'S256' | 'plain'): string;
+/**
+ * Generate complete PKCE parameters
+ *
+ * @param method - Challenge method (defaults to S256 as required by OAuth 2.1)
+ * @returns PKCEParams with verifier and challenge
+ */
+export declare function generatePKCEParams(method?: 'S256' | 'plain'): PKCEParams;
+/**
+ * Verify PKCE challenge
+ * Used by authorization servers to verify the code_verifier matches the code_challenge
+ *
+ * @param codeVerifier - The code verifier from token request
+ * @param codeChallenge - The code challenge from authorization request
+ * @param method - The challenge method used
+ * @returns true if verification succeeds
+ */
+export declare function verifyPKCE(codeVerifier: string, codeChallenge: string, method: 'S256' | 'plain'): boolean;
+/**
+ * Validate code verifier format
+ * Per RFC 7636: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * Length: 43-128 characters
+ */
+export declare function isValidCodeVerifier(verifier: string): boolean;
+/**
+ * Validate PKCE method support
+ * OAuth 2.1 REQUIRES S256 when technically capable
+ */
+export declare function validatePKCESupport(supportedMethods: string[] | undefined): boolean;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,MAAM,GAAG,OAAgB,GAChC,MAAM,CAeR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,MAAM,GAAG,OAAgB,GAAG,UAAU,CAShF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GAAG,OAAO,GACvB,OAAO,CAGT;AAcD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,MAAM,EAAE,GAAG,SAAS,GACrC,OAAO,CAQT"}

package/dist/auth/pkce.js

@@ -0,0 +1,105 @@
+import crypto from 'crypto';
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ * Implements RFC 7636
+ *
+ * PKCE is REQUIRED by OAuth 2.1 to prevent authorization code interception attacks
+ */
+/**
+ * Generate a cryptographically secure random code verifier
+ *
+ * Per RFC 7636:
+ * - code_verifier = high-entropy cryptographic random STRING
+ * - using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * - minimum length of 43 characters and maximum length of 128 characters
+ */
+export function generateCodeVerifier() {
+    // Generate 32 random bytes (256 bits of entropy)
+    const randomBytes = crypto.randomBytes(32);
+    // Convert to base64url encoding (URL-safe base64 without padding)
+    return base64URLEncode(randomBytes);
+}
+/**
+ * Generate code challenge from code verifier
+ *
+ * @param codeVerifier - The code verifier string
+ * @param method - Challenge method: 'S256' (SHA-256) or 'plain'
+ */
+export function generateCodeChallenge(codeVerifier, method = 'S256') {
+    if (method === 'plain') {
+        // Plain method: code_challenge = code_verifier
+        // NOT RECOMMENDED - only for constrained environments
+        return codeVerifier;
+    }
+    // S256 method (REQUIRED by OAuth 2.1 when technically capable):
+    // code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))
+    const hash = crypto
+        .createHash('sha256')
+        .update(codeVerifier, 'ascii')
+        .digest();
+    return base64URLEncode(hash);
+}
+/**
+ * Generate complete PKCE parameters
+ *
+ * @param method - Challenge method (defaults to S256 as required by OAuth 2.1)
+ * @returns PKCEParams with verifier and challenge
+ */
+export function generatePKCEParams(method = 'S256') {
+    const code_verifier = generateCodeVerifier();
+    const code_challenge = generateCodeChallenge(code_verifier, method);
+    return {
+        code_verifier,
+        code_challenge,
+        code_challenge_method: method,
+    };
+}
+/**
+ * Verify PKCE challenge
+ * Used by authorization servers to verify the code_verifier matches the code_challenge
+ *
+ * @param codeVerifier - The code verifier from token request
+ * @param codeChallenge - The code challenge from authorization request
+ * @param method - The challenge method used
+ * @returns true if verification succeeds
+ */
+export function verifyPKCE(codeVerifier, codeChallenge, method) {
+    const computedChallenge = generateCodeChallenge(codeVerifier, method);
+    return computedChallenge === codeChallenge;
+}
+/**
+ * Convert buffer to base64url encoding
+ * Base64url is URL-safe base64 without padding
+ */
+function base64URLEncode(buffer) {
+    return buffer
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+}
+/**
+ * Validate code verifier format
+ * Per RFC 7636: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * Length: 43-128 characters
+ */
+export function isValidCodeVerifier(verifier) {
+    if (verifier.length < 43 || verifier.length > 128) {
+        return false;
+    }
+    const validPattern = /^[A-Za-z0-9\-._~]+$/;
+    return validPattern.test(verifier);
+}
+/**
+ * Validate PKCE method support
+ * OAuth 2.1 REQUIRES S256 when technically capable
+ */
+export function validatePKCESupport(supportedMethods) {
+    if (!supportedMethods || supportedMethods.length === 0) {
+        // No PKCE support indicated - MUST refuse to proceed
+        return false;
+    }
+    // MUST support S256
+    return supportedMethods.includes('S256');
+}
+//# sourceMappingURL=pkce.js.map

package/dist/auth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAM5B;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB;IAClC,iDAAiD;IACjD,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAE3C,kEAAkE;IAClE,OAAO,eAAe,CAAC,WAAW,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAoB,EACpB,SAA2B,MAAM;IAEjC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,+CAA+C;QAC/C,sDAAsD;QACtD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,gEAAgE;IAChE,2DAA2D;IAC3D,MAAM,IAAI,GAAG,MAAM;SAChB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC;SAC7B,MAAM,EAAE,CAAC;IAEZ,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA2B,MAAM;IAClE,MAAM,aAAa,GAAG,oBAAoB,EAAE,CAAC;IAC7C,MAAM,cAAc,GAAG,qBAAqB,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAEpE,OAAO;QACL,aAAa;QACb,cAAc;QACd,qBAAqB,EAAE,MAAM;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CACxB,YAAoB,EACpB,aAAqB,EACrB,MAAwB;IAExB,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACtE,OAAO,iBAAiB,KAAK,aAAa,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM;SACV,QAAQ,CAAC,QAAQ,CAAC;SAClB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,IAAI,QAAQ,CAAC,MAAM,GAAG,EAAE,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,YAAY,GAAG,qBAAqB,CAAC;IAC3C,OAAO,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,gBAAsC;IAEtC,IAAI,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,qDAAqD;QACrD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,oBAAoB;IACpB,OAAO,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}