nextjs-secure 0.2.0 → 0.5.0

package/dist/auth.d.cts

@@ -1,21 +1,182 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * User object attached to request after authentication
+ */
+interface AuthUser {
+    id: string;
+    email?: string;
+    name?: string;
+    roles?: string[];
+    permissions?: string[];
+    [key: string]: unknown;
+}
+/**
+ * JWT payload structure
+ */
+interface JWTPayload {
+    sub?: string;
+    iss?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    [key: string]: unknown;
+}
+/**
+ * JWT verification options
+ */
+interface JWTConfig {
+    /** Secret key for HS256/HS384/HS512 */
+    secret?: string;
+    /** Public key for RS256/RS384/RS512/ES256/ES384/ES512 */
+    publicKey?: string;
+    /** JWKS endpoint URL */
+    jwksUri?: string;
+    /** Expected issuer */
+    issuer?: string | string[];
+    /** Expected audience */
+    audience?: string | string[];
+    /** Algorithms to accept */
+    algorithms?: string[];
+    /** Clock tolerance in seconds */
+    clockTolerance?: number;
+    /** Extract token from request (default: Authorization header) */
+    getToken?: (req: NextRequest) => string | null | Promise<string | null>;
+    /** Map JWT payload to user object */
+    mapUser?: (payload: JWTPayload) => AuthUser | Promise<AuthUser>;
+}
+/**
+ * API Key authentication config
+ */
+interface APIKeyConfig {
+    /** Header name to check (default: x-api-key) */
+    headerName?: string;
+    /** Query parameter name (default: api_key) */
+    queryParam?: string;
+    /** Validate API key and return user */
+    validate: (key: string, req: NextRequest) => AuthUser | null | Promise<AuthUser | null>;
+}
+/**
+ * Session/Cookie authentication config
+ */
+interface SessionConfig {
+    /** Cookie name (default: session) */
+    cookieName?: string;
+    /** Validate session and return user */
+    validate: (sessionId: string, req: NextRequest) => AuthUser | null | Promise<AuthUser | null>;
+}
+/**
+ * Role-based access control config
+ */
+interface RBACConfig {
+    /** Required roles (user must have at least one) */
+    roles?: string[];
+    /** Required permissions (user must have all) */
+    permissions?: string[];
+    /** Get user roles from request */
+    getUserRoles?: (user: AuthUser) => string[];
+    /** Get user permissions from request */
+    getUserPermissions?: (user: AuthUser) => string[];
+    /** Custom authorization check */
+    authorize?: (user: AuthUser, req: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Combined auth configuration
+ */
+interface AuthConfig {
+    /** JWT authentication */
+    jwt?: JWTConfig;
+    /** API Key authentication */
+    apiKey?: APIKeyConfig;
+    /** Session/Cookie authentication */
+    session?: SessionConfig;
+    /** Role-based access control */
+    rbac?: RBACConfig;
+    /** Custom error response */
+    onError?: (req: NextRequest, error: AuthError) => Response | Promise<Response>;
+    /** Called on successful auth */
+    onSuccess?: (req: NextRequest, user: AuthUser) => void | Promise<void>;
+}
+/**
+ * Auth error types
+ */
+type AuthErrorCode = 'missing_token' | 'invalid_token' | 'expired_token' | 'invalid_signature' | 'missing_api_key' | 'invalid_api_key' | 'missing_session' | 'invalid_session' | 'insufficient_roles' | 'insufficient_permissions' | 'unauthorized';
+interface AuthError {
+    code: AuthErrorCode;
+    message: string;
+    status: number;
+}
+/**
+ * Extended request with auth context
+ */
+interface AuthenticatedRequest extends NextRequest {
+    auth: {
+        user: AuthUser;
+        token?: string;
+        method: 'jwt' | 'apiKey' | 'session';
+    };
+}
+
+type RouteHandler = (req: NextRequest) => Response | Promise<Response>;
+type AuthenticatedHandler = (req: NextRequest, ctx: {
+    user: AuthUser;
+    token?: string;
+}) => Response | Promise<Response>;
+/**
+ * JWT Authentication middleware
+ */
+declare function withJWT(handler: AuthenticatedHandler, config: JWTConfig): RouteHandler;
+/**
+ * API Key Authentication middleware
+ */
+declare function withAPIKey(handler: AuthenticatedHandler, config: APIKeyConfig): RouteHandler;
 /**
- * Authentication Middleware (Coming Soon)
- *
- * @example
- * ```typescript
- * import { withAuth } from 'next-secure/auth'
- *
- * export const GET = withAuth(
- *   async (req, ctx) => {
- *     return Response.json({ user: ctx.user })
- *   },
- *   { roles: ['admin'] }
- * )
- * ```
- *
- * @packageDocumentation
- */
-declare function withAuth(): void;
-declare function createAuthProvider(): void;
+ * Session/Cookie Authentication middleware
+ */
+declare function withSession(handler: AuthenticatedHandler, config: SessionConfig): RouteHandler;
+/**
+ * Role-based access control middleware
+ * Must be used after authentication middleware
+ */
+declare function withRoles(handler: AuthenticatedHandler, config: RBACConfig): (req: NextRequest, ctx: {
+    user: AuthUser;
+    token?: string;
+}) => Promise<Response>;
+/**
+ * Combined auth middleware with multiple strategies
+ */
+declare function withAuth(handler: AuthenticatedHandler, config: AuthConfig): RouteHandler;
+/**
+ * Optional auth - doesn't fail if no auth present
+ */
+declare function withOptionalAuth(handler: (req: NextRequest, ctx: {
+    user: AuthUser | null;
+    token?: string;
+}) => Response | Promise<Response>, config: Omit<AuthConfig, 'rbac'>): RouteHandler;
+
+/**
+ * Parse JWT without verification (for header inspection)
+ */
+declare function decodeJWT(token: string): {
+    header: Record<string, unknown>;
+    payload: JWTPayload;
+    signature: Uint8Array;
+} | null;
+/**
+ * Verify and decode JWT
+ */
+declare function verifyJWT(token: string, config: JWTConfig): Promise<{
+    payload: JWTPayload;
+    error: null;
+} | {
+    payload: null;
+    error: AuthError;
+}>;
+/**
+ * Extract token from Authorization header
+ */
+declare function extractBearerToken(authHeader: string | null): string | null;
 
-export { createAuthProvider, withAuth };
+export { type APIKeyConfig, type AuthConfig, type AuthError, type AuthErrorCode, type AuthUser, type AuthenticatedRequest, type JWTConfig, type JWTPayload, type RBACConfig, type SessionConfig, decodeJWT, extractBearerToken, verifyJWT, withAPIKey, withAuth, withJWT, withOptionalAuth, withRoles, withSession };

package/dist/auth.d.ts

@@ -1,21 +1,182 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * User object attached to request after authentication
+ */
+interface AuthUser {
+    id: string;
+    email?: string;
+    name?: string;
+    roles?: string[];
+    permissions?: string[];
+    [key: string]: unknown;
+}
+/**
+ * JWT payload structure
+ */
+interface JWTPayload {
+    sub?: string;
+    iss?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    [key: string]: unknown;
+}
+/**
+ * JWT verification options
+ */
+interface JWTConfig {
+    /** Secret key for HS256/HS384/HS512 */
+    secret?: string;
+    /** Public key for RS256/RS384/RS512/ES256/ES384/ES512 */
+    publicKey?: string;
+    /** JWKS endpoint URL */
+    jwksUri?: string;
+    /** Expected issuer */
+    issuer?: string | string[];
+    /** Expected audience */
+    audience?: string | string[];
+    /** Algorithms to accept */
+    algorithms?: string[];
+    /** Clock tolerance in seconds */
+    clockTolerance?: number;
+    /** Extract token from request (default: Authorization header) */
+    getToken?: (req: NextRequest) => string | null | Promise<string | null>;
+    /** Map JWT payload to user object */
+    mapUser?: (payload: JWTPayload) => AuthUser | Promise<AuthUser>;
+}
+/**
+ * API Key authentication config
+ */
+interface APIKeyConfig {
+    /** Header name to check (default: x-api-key) */
+    headerName?: string;
+    /** Query parameter name (default: api_key) */
+    queryParam?: string;
+    /** Validate API key and return user */
+    validate: (key: string, req: NextRequest) => AuthUser | null | Promise<AuthUser | null>;
+}
+/**
+ * Session/Cookie authentication config
+ */
+interface SessionConfig {
+    /** Cookie name (default: session) */
+    cookieName?: string;
+    /** Validate session and return user */
+    validate: (sessionId: string, req: NextRequest) => AuthUser | null | Promise<AuthUser | null>;
+}
+/**
+ * Role-based access control config
+ */
+interface RBACConfig {
+    /** Required roles (user must have at least one) */
+    roles?: string[];
+    /** Required permissions (user must have all) */
+    permissions?: string[];
+    /** Get user roles from request */
+    getUserRoles?: (user: AuthUser) => string[];
+    /** Get user permissions from request */
+    getUserPermissions?: (user: AuthUser) => string[];
+    /** Custom authorization check */
+    authorize?: (user: AuthUser, req: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Combined auth configuration
+ */
+interface AuthConfig {
+    /** JWT authentication */
+    jwt?: JWTConfig;
+    /** API Key authentication */
+    apiKey?: APIKeyConfig;
+    /** Session/Cookie authentication */
+    session?: SessionConfig;
+    /** Role-based access control */
+    rbac?: RBACConfig;
+    /** Custom error response */
+    onError?: (req: NextRequest, error: AuthError) => Response | Promise<Response>;
+    /** Called on successful auth */
+    onSuccess?: (req: NextRequest, user: AuthUser) => void | Promise<void>;
+}
+/**
+ * Auth error types
+ */
+type AuthErrorCode = 'missing_token' | 'invalid_token' | 'expired_token' | 'invalid_signature' | 'missing_api_key' | 'invalid_api_key' | 'missing_session' | 'invalid_session' | 'insufficient_roles' | 'insufficient_permissions' | 'unauthorized';
+interface AuthError {
+    code: AuthErrorCode;
+    message: string;
+    status: number;
+}
+/**
+ * Extended request with auth context
+ */
+interface AuthenticatedRequest extends NextRequest {
+    auth: {
+        user: AuthUser;
+        token?: string;
+        method: 'jwt' | 'apiKey' | 'session';
+    };
+}
+
+type RouteHandler = (req: NextRequest) => Response | Promise<Response>;
+type AuthenticatedHandler = (req: NextRequest, ctx: {
+    user: AuthUser;
+    token?: string;
+}) => Response | Promise<Response>;
+/**
+ * JWT Authentication middleware
+ */
+declare function withJWT(handler: AuthenticatedHandler, config: JWTConfig): RouteHandler;
+/**
+ * API Key Authentication middleware
+ */
+declare function withAPIKey(handler: AuthenticatedHandler, config: APIKeyConfig): RouteHandler;
 /**
- * Authentication Middleware (Coming Soon)
- *
- * @example
- * ```typescript
- * import { withAuth } from 'next-secure/auth'
- *
- * export const GET = withAuth(
- *   async (req, ctx) => {
- *     return Response.json({ user: ctx.user })
- *   },
- *   { roles: ['admin'] }
- * )
- * ```
- *
- * @packageDocumentation
- */
-declare function withAuth(): void;
-declare function createAuthProvider(): void;
+ * Session/Cookie Authentication middleware
+ */
+declare function withSession(handler: AuthenticatedHandler, config: SessionConfig): RouteHandler;
+/**
+ * Role-based access control middleware
+ * Must be used after authentication middleware
+ */
+declare function withRoles(handler: AuthenticatedHandler, config: RBACConfig): (req: NextRequest, ctx: {
+    user: AuthUser;
+    token?: string;
+}) => Promise<Response>;
+/**
+ * Combined auth middleware with multiple strategies
+ */
+declare function withAuth(handler: AuthenticatedHandler, config: AuthConfig): RouteHandler;
+/**
+ * Optional auth - doesn't fail if no auth present
+ */
+declare function withOptionalAuth(handler: (req: NextRequest, ctx: {
+    user: AuthUser | null;
+    token?: string;
+}) => Response | Promise<Response>, config: Omit<AuthConfig, 'rbac'>): RouteHandler;
+
+/**
+ * Parse JWT without verification (for header inspection)
+ */
+declare function decodeJWT(token: string): {
+    header: Record<string, unknown>;
+    payload: JWTPayload;
+    signature: Uint8Array;
+} | null;
+/**
+ * Verify and decode JWT
+ */
+declare function verifyJWT(token: string, config: JWTConfig): Promise<{
+    payload: JWTPayload;
+    error: null;
+} | {
+    payload: null;
+    error: AuthError;
+}>;
+/**
+ * Extract token from Authorization header
+ */
+declare function extractBearerToken(authHeader: string | null): string | null;
 
-export { createAuthProvider, withAuth };
+export { type APIKeyConfig, type AuthConfig, type AuthError, type AuthErrorCode, type AuthUser, type AuthenticatedRequest, type JWTConfig, type JWTPayload, type RBACConfig, type SessionConfig, decodeJWT, extractBearerToken, verifyJWT, withAPIKey, withAuth, withJWT, withOptionalAuth, withRoles, withSession };