@qwickapps/server 1.2.0 → 1.3.1

package/dist/plugins/auth/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Auth Plugin Types
+ *
+ * Type definitions for the pluggable authentication system.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Request, Response, RequestHandler } from 'express';
+/**
+ * Authenticated user information
+ */
+export interface AuthenticatedUser {
+    /** Unique user ID from the provider */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name?: string;
+    /** User's profile picture URL */
+    picture?: string;
+    /** Whether the email is verified */
+    emailVerified?: boolean;
+    /** User's roles from the provider */
+    roles?: string[];
+    /** Raw user object from the provider */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Auth adapter interface - all adapters must implement this
+ */
+export interface AuthAdapter {
+    /** Adapter name (e.g., 'auth0', 'supabase', 'basic') */
+    name: string;
+    /**
+     * Initialize the adapter - called once during plugin setup
+     * Returns middleware to apply to the Express app
+     */
+    initialize(): RequestHandler | RequestHandler[];
+    /**
+     * Check if the request is authenticated
+     */
+    isAuthenticated(req: Request): boolean;
+    /**
+     * Get the authenticated user from the request
+     * Can be async for adapters that need to validate tokens
+     */
+    getUser(req: Request): AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+    /**
+     * Check if user has required roles (optional)
+     */
+    hasRoles?(req: Request, roles: string[]): boolean;
+    /**
+     * Get the access token for downstream API calls (optional)
+     */
+    getAccessToken?(req: Request): string | null;
+    /**
+     * Handler for unauthorized requests (optional custom behavior)
+     */
+    onUnauthorized?(req: Request, res: Response): void;
+    /**
+     * Cleanup resources on shutdown (optional)
+     */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Auth0 adapter configuration
+ */
+export interface Auth0AdapterConfig {
+    /** Auth0 domain (e.g., 'myapp.auth0.com') */
+    domain: string;
+    /** Auth0 client ID */
+    clientId: string;
+    /** Auth0 client secret */
+    clientSecret: string;
+    /** Base URL of the application */
+    baseUrl: string;
+    /** Session secret for cookie encryption */
+    secret: string;
+    /** API audience for access tokens (optional) */
+    audience?: string;
+    /** Scopes to request (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+    /** Allowed roles - only these roles can access (optional) */
+    allowedRoles?: string[];
+    /** Allowed email domains - only these domains can access (optional) */
+    allowedDomains?: string[];
+    /** Whether to expose the access token to handlers (default: false) */
+    exposeAccessToken?: boolean;
+    /** Auth routes configuration */
+    routes?: {
+        login?: string;
+        logout?: string;
+        callback?: string;
+    };
+}
+/**
+ * Supabase adapter configuration
+ */
+export interface SupabaseAdapterConfig {
+    /** Supabase project URL */
+    url: string;
+    /** Supabase anon key */
+    anonKey: string;
+}
+/**
+ * Basic auth adapter configuration
+ */
+export interface BasicAdapterConfig {
+    /** Username for basic auth */
+    username: string;
+    /** Password for basic auth */
+    password: string;
+    /** Realm name for the WWW-Authenticate header */
+    realm?: string;
+}
+/**
+ * Supertokens adapter configuration
+ */
+export interface SupertokensAdapterConfig {
+    /** Supertokens connection URI (e.g., 'http://localhost:3567') */
+    connectionUri: string;
+    /** Supertokens API key (for managed service) */
+    apiKey?: string;
+    /** App name for branding */
+    appName: string;
+    /** API domain (e.g., 'http://localhost:3000') */
+    apiDomain: string;
+    /** Website domain (e.g., 'http://localhost:3000') */
+    websiteDomain: string;
+    /** API base path (default: '/auth') */
+    apiBasePath?: string;
+    /** Website base path (default: '/auth') */
+    websiteBasePath?: string;
+    /** Enable email/password auth (default: true) */
+    enableEmailPassword?: boolean;
+    /** Social login providers */
+    socialProviders?: {
+        google?: {
+            clientId: string;
+            clientSecret: string;
+        };
+        apple?: {
+            clientId: string;
+            clientSecret: string;
+            keyId: string;
+            teamId: string;
+        };
+        github?: {
+            clientId: string;
+            clientSecret: string;
+        };
+    };
+}
+/**
+ * Auth plugin configuration
+ */
+export interface AuthPluginConfig {
+    /** Primary adapter for authentication */
+    adapter: AuthAdapter;
+    /** Fallback adapters checked in order if primary fails (optional) */
+    fallback?: AuthAdapter[];
+    /** Paths to exclude from authentication */
+    excludePaths?: string[];
+    /** Whether auth is required for all routes (default: true) */
+    authRequired?: boolean;
+    /** Custom unauthorized handler */
+    onUnauthorized?: (req: Request, res: Response) => void;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Extended Express Request with auth info
+ */
+export interface AuthenticatedRequest extends Request {
+    auth: {
+        isAuthenticated: boolean;
+        user: AuthenticatedUser | null;
+        adapter: string;
+        accessToken?: string;
+    };
+}
+/**
+ * Helper type guard for authenticated requests
+ */
+export declare function isAuthenticatedRequest(req: Request): req is AuthenticatedRequest;
+/**
+ * Auth plugin state
+ */
+export type AuthPluginState = 'disabled' | 'enabled' | 'error';
+/**
+ * Options for createAuthPluginFromEnv (overrides only)
+ */
+export interface AuthEnvPluginOptions {
+    /** Paths to exclude from authentication (can also use AUTH_EXCLUDE_PATHS env var) */
+    excludePaths?: string[];
+    /** Whether auth is required (can also use AUTH_REQUIRED env var, default: true) */
+    authRequired?: boolean;
+    /** Enable debug logging (can also use AUTH_DEBUG env var) */
+    debug?: boolean;
+    /** Custom unauthorized handler */
+    onUnauthorized?: (req: Request, res: Response) => void;
+}
+/**
+ * Auth configuration status returned by getAuthStatus()
+ */
+export interface AuthConfigStatus {
+    /** Current plugin state */
+    state: AuthPluginState;
+    /** Active adapter name (null if disabled or error) */
+    adapter: string | null;
+    /** Error message if state is 'error' */
+    error?: string;
+    /** List of missing environment variables if state is 'error' */
+    missingVars?: string[];
+    /** Current configuration with secrets masked */
+    config?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/auth/types.d.ts.map

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

package/dist/plugins/auth/types.js

@@ -0,0 +1,14 @@
+/**
+ * Auth Plugin Types
+ *
+ * Type definitions for the pluggable authentication system.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+/**
+ * Helper type guard for authenticated requests
+ */
+export function isAuthenticatedRequest(req) {
+    return 'auth' in req && req.auth?.isAuthenticated === true;
+}
+//# sourceMappingURL=types.js.map

package/dist/plugins/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/plugins/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkMH;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,MAAM,IAAI,GAAG,IAAK,GAA4B,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;AACvF,CAAC"}

package/dist/plugins/bans/bans-plugin.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bans Plugin
+ *
+ * User ban management plugin for @qwickapps/server.
+ * Bans are always on USER entities (by user_id), not emails.
+ *
+ * This plugin depends on the Users Plugin for user resolution.
+ * Use `isEmailBanned()` convenience function to check bans by email,
+ * which internally resolves email → user_id → ban status.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Plugin } from '../../core/plugin-registry.js';
+import type { BansPluginConfig, BanStore, Ban, CreateBanInput, RemoveBanInput } from './types.js';
+/**
+ * Create the Bans plugin
+ */
+export declare function createBansPlugin(config: BansPluginConfig): Plugin;
+/**
+ * Get the current ban store instance
+ */
+export declare function getBanStore(): BanStore | null;
+/**
+ * Check if a user is banned by user ID
+ */
+export declare function isUserBanned(userId: string): Promise<boolean>;
+/**
+ * Check if a user is banned by email
+ *
+ * This is a convenience function that:
+ * 1. Resolves email → user via Users Plugin
+ * 2. Checks ban status by user_id
+ *
+ * Returns false if user doesn't exist (unknown user = not banned)
+ */
+export declare function isEmailBanned(email: string): Promise<boolean>;
+/**
+ * Get active ban for a user
+ */
+export declare function getActiveBan(userId: string): Promise<Ban | null>;
+/**
+ * Ban a user
+ */
+export declare function banUser(input: CreateBanInput): Promise<Ban>;
+/**
+ * Unban a user
+ */
+export declare function unbanUser(input: RemoveBanInput): Promise<boolean>;
+/**
+ * List all active bans
+ */
+export declare function listActiveBans(options?: {
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    bans: Ban[];
+    total: number;
+}>;
+//# sourceMappingURL=bans-plugin.d.ts.map

package/dist/plugins/bans/bans-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bans-plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/bans/bans-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAgC,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,GAAG,EACH,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AASpB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CA8UjE;AAMD;;GAEG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,IAAI,CAE7C;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAKtE;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAoBjE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBvE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAC3F,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAKD"}