@veloxts/auth 0.6.84 → 0.6.86

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/auth
 
+## 0.6.86
+
+### Patch Changes
+
+- updated documentation
+- Updated dependencies
+  - @veloxts/core@0.6.86
+  - @veloxts/router@0.6.86
+
+## 0.6.85
+
+### Patch Changes
+
+- implement missing features from original requirements
+- Updated dependencies
+  - @veloxts/core@0.6.85
+  - @veloxts/router@0.6.85
+
 ## 0.6.84
 
 ### Patch Changes

package/GUIDE.md

@@ -54,14 +54,27 @@ const getProfile = procedure()
 ## Guards
 
 ```typescript
-import { hasRole, hasPermission } from '@veloxts/auth';
+import { authenticated, hasRole, hasPermission } from '@veloxts/auth';
 
+// Require authentication
+const getProfile = procedure()
+  .guard(authenticated)
+  .query(({ ctx }) => ctx.user);
+
+// Require admin role
 const adminOnly = procedure()
-  .use(auth.middleware({ guards: [hasRole('admin')] }))
+  .guard(hasRole('admin'))
   .mutation(handler);
 
+// Require specific permission
 const canEdit = procedure()
-  .use(auth.middleware({ guards: [hasPermission('posts.write')] }))
+  .guard(hasPermission('posts.write'))
+  .mutation(handler);
+
+// Chain multiple guards (all must pass)
+const adminWithPermission = procedure()
+  .guard(authenticated)
+  .guard(hasRole('admin'))
   .mutation(handler);
 ```
 

package/dist/adapter.d.ts

@@ -195,11 +195,12 @@ export interface AdapterRoute {
  */
 export interface AuthAdapterConfig {
     /**
-     * Adapter name for identification and logging
+     * Adapter name for identification and logging (optional)
      *
      * Should be a unique identifier like 'better-auth', 'clerk', 'auth0'.
+     * If not provided, the factory function or adapter class will supply a default.
      */
-    name: string;
+    name?: string;
     /**
      * Enable debug logging
      *
@@ -486,6 +487,9 @@ export interface AuthAdapter<TConfig extends AuthAdapterConfig = AuthAdapterConf
 export declare function defineAuthAdapter<TConfig extends AuthAdapterConfig = AuthAdapterConfig>(adapter: AuthAdapter<TConfig>): AuthAdapter<TConfig>;
 /**
  * Plugin options for the auth adapter plugin
+ *
+ * @deprecated Use the simplified form: `createAuthAdapterPlugin(adapter)` where adapter
+ * is created via a factory function like `createClerkAdapter()` that attaches config.
  */
 export interface AuthAdapterPluginOptions<TConfig extends AuthAdapterConfig = AuthAdapterConfig> {
     /**
@@ -497,6 +501,17 @@ export interface AuthAdapterPluginOptions<TConfig extends AuthAdapterConfig = Au
      */
     config: TConfig;
 }
+/**
+ * Adapter with attached configuration (returned by factory functions)
+ *
+ * Factory functions like `createClerkAdapter()` return an adapter with its
+ * configuration attached, enabling the simplified plugin registration:
+ * `createAuthAdapterPlugin(adapter)` instead of
+ * `createAuthAdapterPlugin({ adapter, config: adapter.config })`
+ */
+export type AdapterWithConfig<TAdapter extends AuthAdapter<TConfig>, TConfig extends AuthAdapterConfig = AuthAdapterConfig> = TAdapter & {
+    config: TConfig;
+};
 /**
  * Creates a VeloxTS plugin from an auth adapter
  *
@@ -510,31 +525,34 @@ export interface AuthAdapterPluginOptions<TConfig extends AuthAdapterConfig = Au
  * - Cleanup on shutdown
  *
  * @template TConfig - Adapter-specific configuration type
- * @param options - Plugin options with adapter and config
+ * @param adapterOrOptions - Either an adapter with attached config (from factory), or legacy options object
  * @returns VeloxTS plugin ready for registration
  *
- * @example
+ * @example Simplified API (recommended)
  * ```typescript
  * import { createAuthAdapterPlugin } from '@veloxts/auth';
- * import { betterAuthAdapter } from './adapters/better-auth';
+ * import { createClerkAdapter } from '@veloxts/auth/adapters/clerk';
  *
- * const authPlugin = createAuthAdapterPlugin({
- *   adapter: betterAuthAdapter,
- *   config: {
- *     name: 'better-auth',
- *     auth: betterAuth({
- *       database: db,
- *       trustedOrigins: ['http://localhost:3000'],
- *     }),
- *     debug: process.env.NODE_ENV === 'development',
- *   },
+ * const adapter = createClerkAdapter({
+ *   clerk: createClerkClient({ secretKey: '...' }),
+ *   debug: process.env.NODE_ENV === 'development',
  * });
  *
- * // Register with VeloxApp
+ * // Simple: just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
  * app.use(authPlugin);
  * ```
+ *
+ * @example Legacy API (still supported)
+ * ```typescript
+ * const authPlugin = createAuthAdapterPlugin({
+ *   adapter: myAdapter,
+ *   config: { ... },
+ * });
+ * ```
  */
-export declare function createAuthAdapterPlugin<TConfig extends AuthAdapterConfig>(options: AuthAdapterPluginOptions<TConfig>): VeloxPlugin<AuthAdapterPluginOptions<TConfig>>;
+export declare function createAuthAdapterPlugin<TConfig extends AuthAdapterConfig>(adapterOrOptions: AdapterWithConfig<AuthAdapter<TConfig>, TConfig> | AuthAdapterPluginOptions<TConfig>): VeloxPlugin<AuthAdapterPluginOptions<TConfig>>;
 /**
  * Options for adapter-based auth middleware
  */

package/dist/adapter.js

@@ -182,32 +182,47 @@ function matchesExcludePattern(path, patterns) {
  * - Cleanup on shutdown
  *
  * @template TConfig - Adapter-specific configuration type
- * @param options - Plugin options with adapter and config
+ * @param adapterOrOptions - Either an adapter with attached config (from factory), or legacy options object
  * @returns VeloxTS plugin ready for registration
  *
- * @example
+ * @example Simplified API (recommended)
  * ```typescript
  * import { createAuthAdapterPlugin } from '@veloxts/auth';
- * import { betterAuthAdapter } from './adapters/better-auth';
+ * import { createClerkAdapter } from '@veloxts/auth/adapters/clerk';
  *
- * const authPlugin = createAuthAdapterPlugin({
- *   adapter: betterAuthAdapter,
- *   config: {
- *     name: 'better-auth',
- *     auth: betterAuth({
- *       database: db,
- *       trustedOrigins: ['http://localhost:3000'],
- *     }),
- *     debug: process.env.NODE_ENV === 'development',
- *   },
+ * const adapter = createClerkAdapter({
+ *   clerk: createClerkClient({ secretKey: '...' }),
+ *   debug: process.env.NODE_ENV === 'development',
  * });
  *
- * // Register with VeloxApp
+ * // Simple: just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
  * app.use(authPlugin);
  * ```
+ *
+ * @example Legacy API (still supported)
+ * ```typescript
+ * const authPlugin = createAuthAdapterPlugin({
+ *   adapter: myAdapter,
+ *   config: { ... },
+ * });
+ * ```
  */
-export function createAuthAdapterPlugin(options) {
-    const { adapter, config } = options;
+export function createAuthAdapterPlugin(adapterOrOptions) {
+    // Support both new simplified API and legacy options object
+    let adapter;
+    let config;
+    if ('adapter' in adapterOrOptions && 'config' in adapterOrOptions) {
+        // Legacy: { adapter, config } object
+        adapter = adapterOrOptions.adapter;
+        config = adapterOrOptions.config;
+    }
+    else {
+        // New: adapter with attached config
+        adapter = adapterOrOptions;
+        config = adapterOrOptions.config;
+    }
     const debug = config.debug ?? false;
     const excludeRoutes = config.excludeRoutes ?? [];
     const transformUser = config.transformUser ?? defaultTransformUser;
@@ -216,7 +231,8 @@ export function createAuthAdapterPlugin(options) {
         version: adapter.version,
         dependencies: ['@veloxts/core'],
         async register(server, _opts) {
-            const mergedConfig = { ...config, ..._opts.config };
+            // Config is already captured from adapter - _opts.config is for legacy override support
+            const mergedConfig = _opts?.config ? { ...config, ..._opts.config } : config;
             // Prevent double-registration of auth systems
             checkDoubleRegistration(server, `adapter:${adapter.name}`);
             if (debug) {

package/dist/adapters/auth0.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Auth0 Adapter for @veloxts/auth
+ *
+ * Integrates Auth0 (https://auth0.com) with VeloxTS's pluggable
+ * authentication system. Auth0 is an identity platform providing
+ * authentication and authorization services.
+ *
+ * This adapter uses JWKS (JSON Web Key Sets) for JWT verification,
+ * allowing secure token validation without sharing secrets.
+ *
+ * @module auth/adapters/auth0
+ *
+ * @example
+ * ```typescript
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ * import { createAuth0Adapter } from '@veloxts/auth/adapters/auth0';
+ *
+ * const adapter = createAuth0Adapter({
+ *   domain: process.env.AUTH0_DOMAIN!,
+ *   audience: process.env.AUTH0_AUDIENCE!,
+ *   clientId: process.env.AUTH0_CLIENT_ID,
+ * });
+ *
+ * // Simplified API - just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
+ * app.use(authPlugin);
+ * ```
+ */
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { AdapterRoute, AdapterSessionResult, AuthAdapterConfig } from '../adapter.js';
+import { BaseAuthAdapter } from '../adapter.js';
+/**
+ * Auth0 JWT claims (standard + custom)
+ *
+ * Represents the claims in a verified Auth0 JWT.
+ */
+export interface Auth0Claims {
+    /** Subject (user ID - Auth0's user_id) */
+    sub: string;
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+    /** Not before timestamp */
+    nbf?: number;
+    /** Issuer (Auth0 domain) */
+    iss: string;
+    /** Audience */
+    aud: string | string[];
+    /** Authorized party */
+    azp?: string;
+    /** Token scope */
+    scope?: string;
+    /** Token permissions (RBAC) */
+    permissions?: string[];
+    /** Organization ID (Auth0 Organizations) */
+    org_id?: string;
+    /** Organization name */
+    org_name?: string;
+    /** Email (if included in token) */
+    email?: string;
+    /** Email verified status */
+    email_verified?: boolean;
+    /** User name */
+    name?: string;
+    /** User nickname */
+    nickname?: string;
+    /** Profile picture URL */
+    picture?: string;
+    /** Updated at timestamp */
+    updated_at?: string;
+}
+/**
+ * Auth0 Management API user object
+ *
+ * Full user profile from Auth0's Management API.
+ */
+export interface Auth0User {
+    /** User ID */
+    user_id: string;
+    /** Email address */
+    email?: string;
+    /** Whether email is verified */
+    email_verified?: boolean;
+    /** Display name */
+    name?: string;
+    /** Nickname */
+    nickname?: string;
+    /** First name */
+    given_name?: string;
+    /** Last name */
+    family_name?: string;
+    /** Profile picture URL */
+    picture?: string;
+    /** Last login timestamp */
+    last_login?: string;
+    /** Login count */
+    logins_count?: number;
+    /** Account creation timestamp */
+    created_at?: string;
+    /** Account update timestamp */
+    updated_at?: string;
+    /** User metadata (writable by user) */
+    user_metadata?: Record<string, unknown>;
+    /** App metadata (writable by app) */
+    app_metadata?: Record<string, unknown>;
+    /** Identity providers linked to this user */
+    identities?: Array<{
+        connection: string;
+        provider: string;
+        user_id: string;
+        isSocial: boolean;
+    }>;
+}
+/**
+ * JWKS Key object
+ *
+ * JSON Web Key from Auth0's JWKS endpoint.
+ */
+export interface JWKSKey {
+    /** Key type (always 'RSA' for Auth0) */
+    kty: string;
+    /** Key ID */
+    kid: string;
+    /** Algorithm (RS256) */
+    alg: string;
+    /** Key use (signature) */
+    use: string;
+    /** RSA modulus */
+    n: string;
+    /** RSA exponent */
+    e: string;
+    /** X.509 certificate chain */
+    x5c?: string[];
+    /** X.509 thumbprint */
+    x5t?: string;
+}
+/**
+ * JWKS response from Auth0
+ */
+export interface JWKSResponse {
+    keys: JWKSKey[];
+}
+/**
+ * JWT verifier interface
+ *
+ * For custom JWT verification implementations.
+ * The adapter provides a default implementation using jose library.
+ */
+export interface JwtVerifier {
+    /**
+     * Verify a JWT token
+     *
+     * @param token - JWT token to verify
+     * @returns Decoded claims if valid, throws if invalid
+     */
+    verify(token: string): Promise<Auth0Claims>;
+}
+/**
+ * Auth0 adapter configuration
+ *
+ * @example
+ * ```typescript
+ * const config: Auth0AdapterConfig = {
+ *   name: 'auth0',
+ *   domain: 'your-tenant.auth0.com',
+ *   audience: 'https://your-api.example.com',
+ *   clientId: 'your-client-id', // Optional for additional validation
+ *   debug: true,
+ * };
+ * ```
+ */
+export interface Auth0AdapterConfig extends AuthAdapterConfig {
+    /**
+     * Auth0 domain
+     *
+     * Your Auth0 tenant domain (e.g., 'your-tenant.auth0.com').
+     * Can be the custom domain if configured.
+     */
+    domain: string;
+    /**
+     * API audience
+     *
+     * The identifier for your API in Auth0.
+     * Tokens must have this audience to be valid.
+     */
+    audience: string;
+    /**
+     * Client ID (optional)
+     *
+     * If provided, validates the authorized party (azp) claim.
+     * Useful for ensuring tokens were issued for your specific client.
+     */
+    clientId?: string;
+    /**
+     * Custom JWT verifier (optional)
+     *
+     * Provide a custom JWT verification implementation.
+     * If not provided, uses the default JWKS-based verifier.
+     */
+    jwtVerifier?: JwtVerifier;
+    /**
+     * JWKS cache TTL in milliseconds
+     *
+     * How long to cache the JWKS keys before fetching fresh ones.
+     *
+     * @default 3600000 (1 hour)
+     */
+    jwksCacheTtl?: number;
+    /**
+     * Clock tolerance in seconds
+     *
+     * Tolerance for clock skew when validating exp/iat/nbf claims.
+     *
+     * @default 5
+     */
+    clockTolerance?: number;
+    /**
+     * Custom header name for the authorization token
+     *
+     * @default 'authorization'
+     */
+    authHeader?: string;
+    /**
+     * Token issuer (optional)
+     *
+     * Override the expected issuer. By default, constructs from domain.
+     * Useful for custom domains.
+     */
+    issuer?: string;
+}
+/**
+ * Auth0 Adapter
+ *
+ * Integrates Auth0 with VeloxTS by:
+ * - Verifying Auth0 JWTs using JWKS
+ * - Extracting user data from token claims
+ * - Supporting Auth0 Organizations and RBAC
+ *
+ * @example
+ * ```typescript
+ * const adapter = new Auth0Adapter();
+ * const plugin = createAuthAdapterPlugin({
+ *   adapter,
+ *   config: {
+ *     name: 'auth0',
+ *     domain: 'your-tenant.auth0.com',
+ *     audience: 'https://your-api.example.com',
+ *   },
+ * });
+ * ```
+ */
+export declare class Auth0Adapter extends BaseAuthAdapter<Auth0AdapterConfig> {
+    private verifier;
+    private domain;
+    private clientId?;
+    private authHeader;
+    constructor();
+    /**
+     * Initialize the adapter with Auth0 configuration
+     */
+    initialize(fastify: FastifyInstance, config: Auth0AdapterConfig): Promise<void>;
+    /**
+     * Get session from Auth0 JWT
+     *
+     * Extracts the Bearer token from the Authorization header
+     * and verifies it using JWKS.
+     */
+    getSession(request: FastifyRequest): Promise<AdapterSessionResult | null>;
+    /**
+     * Get routes for Auth0
+     *
+     * Auth0 handles auth on the client side via their SDK.
+     * Server only needs to verify tokens, not handle auth routes.
+     *
+     * If you need to handle Auth0 webhooks or Actions callbacks,
+     * override this method.
+     */
+    getRoutes(): AdapterRoute[];
+    /**
+     * Clean up adapter resources
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Create an Auth0 adapter
+ *
+ * This is the recommended way to create an Auth0 adapter.
+ * It returns an adapter instance with the configuration attached.
+ *
+ * @param config - Adapter configuration
+ * @returns Auth0 adapter with configuration
+ *
+ * @example
+ * ```typescript
+ * import { createAuth0Adapter } from '@veloxts/auth/adapters/auth0';
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ *
+ * const adapter = createAuth0Adapter({
+ *   domain: process.env.AUTH0_DOMAIN!,
+ *   audience: process.env.AUTH0_AUDIENCE!,
+ *   clientId: process.env.AUTH0_CLIENT_ID, // Optional
+ *   debug: process.env.NODE_ENV === 'development',
+ * });
+ *
+ * // Simplified API - just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
+ * app.use(authPlugin);
+ * ```
+ */
+export declare function createAuth0Adapter(config: Auth0AdapterConfig): Auth0Adapter & {
+    config: Auth0AdapterConfig;
+};
+export { AuthAdapterError } from '../adapter.js';