@qwickapps/server 1.2.0 → 1.3.1

package/README.md

@@ -61,6 +61,8 @@ For production deployments, use `createGateway` to run a gateway that:
 1. Serves the control panel UI (always responsive, even if the API crashes)
 2. Proxies API requests to an internal service
 3. Handles graceful error responses when the internal service is down
+4. Supports maintenance mode with customizable status pages
+5. Shows service unavailable pages when mounted apps are unreachable
 
 ```typescript
 import { createGateway, createHealthPlugin } from '@qwickapps/server';
@@ -115,6 +117,68 @@ Internet → Gateway (3101, public) → API Service (3100, internal)
 
 The gateway is always responsive even if the internal API service crashes, allowing you to view diagnostics and error information.
 
+### Mounted Apps with Maintenance Mode
+
+Mount frontend apps or proxy services with full maintenance and fallback support:
+
+```typescript
+const gateway = createGateway({
+  // ... base config
+  mountedApps: [
+    {
+      path: '/app',
+      name: 'Main App',
+      type: 'proxy',
+      target: 'http://localhost:4000',
+      maintenance: {
+        enabled: false,  // Toggle to enable maintenance mode
+        title: 'Scheduled Maintenance',
+        message: 'We are upgrading our systems.',
+        expectedBackAt: '2 hours',  // or ISO date, or "soon"
+        contactUrl: 'https://status.example.com',
+        bypassPaths: ['/app/health', '/app/api/status'],
+      },
+      fallback: {
+        title: 'Service Unavailable',
+        message: 'The application is temporarily unavailable.',
+        showRetry: true,
+        autoRefresh: 30,  // seconds
+      },
+    },
+    {
+      path: '/docs',
+      name: 'Documentation',
+      type: 'static',
+      staticPath: './docs-dist',
+    },
+  ],
+});
+```
+
+### Maintenance and Fallback Configuration
+
+**MaintenanceConfig** - Shown when maintenance mode is enabled:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Enable/disable maintenance mode |
+| `title` | `string` | Page title (default: "Under Maintenance") |
+| `message` | `string` | Custom message to display |
+| `expectedBackAt` | `string` | ETA: ISO date, relative time ("2 hours"), or "soon" |
+| `contactUrl` | `string` | Link to status page or contact |
+| `bypassPaths` | `string[]` | Paths that bypass maintenance (e.g., health checks) |
+
+**FallbackConfig** - Shown when the proxied service is unreachable:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Page title (default: "Service Unavailable") |
+| `message` | `string` | Custom message to display |
+| `showRetry` | `boolean` | Show retry button (default: true) |
+| `autoRefresh` | `number` | Auto-refresh countdown in seconds (default: 30) |
+
+Both pages feature modern, responsive designs with automatic dark mode support.
+
 ## Configuration
 
 ### ControlPanelConfig
@@ -377,6 +441,334 @@ await cache.flush(); // Clear all keys with prefix
 - `hasCache(name?)` - Check if an instance is registered
 - `CacheInstance` - TypeScript type for the instance
 
+#### Auth Plugin
+
+Pluggable authentication with support for multiple providers via the adapter pattern.
+
+##### Zero-Config Environment Setup
+
+The simplest way to configure auth is via environment variables:
+
+```typescript
+import { createAuthPluginFromEnv } from '@qwickapps/server';
+
+// Auto-configures based on AUTH_ADAPTER env var
+const authPlugin = createAuthPluginFromEnv();
+
+// With overrides
+const authPlugin = createAuthPluginFromEnv({
+  excludePaths: ['/health', '/metrics'],
+  authRequired: true,
+});
+```
+
+**Environment Variables:**
+
+```bash
+# General (required to enable auth)
+AUTH_ADAPTER=supertokens|auth0|supabase|basic
+AUTH_REQUIRED=true                    # Default: true
+AUTH_EXCLUDE_PATHS=/health,/metrics   # Comma-separated
+AUTH_DEBUG=false
+
+# Supertokens
+SUPERTOKENS_CONNECTION_URI=http://localhost:3567
+SUPERTOKENS_APP_NAME=MyApp
+SUPERTOKENS_API_DOMAIN=http://localhost:3000
+SUPERTOKENS_WEBSITE_DOMAIN=http://localhost:3000
+SUPERTOKENS_API_KEY=                  # Optional, for managed service
+SUPERTOKENS_GOOGLE_CLIENT_ID=         # Optional social providers
+SUPERTOKENS_GOOGLE_CLIENT_SECRET=
+SUPERTOKENS_GITHUB_CLIENT_ID=
+SUPERTOKENS_GITHUB_CLIENT_SECRET=
+
+# Auth0
+AUTH0_DOMAIN=myapp.auth0.com
+AUTH0_CLIENT_ID=
+AUTH0_CLIENT_SECRET=
+AUTH0_BASE_URL=http://localhost:3000
+AUTH0_SECRET=                         # Session encryption secret
+AUTH0_AUDIENCE=                       # Optional, for API access tokens
+AUTH0_SCOPES=openid,profile,email     # Default scopes
+
+# Supabase
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_ANON_KEY=
+
+# Basic Auth
+BASIC_AUTH_USERNAME=admin
+BASIC_AUTH_PASSWORD=
+BASIC_AUTH_REALM=Protected            # Default: Protected
+```
+
+**Plugin States:**
+
+| State | Condition | Behavior |
+|-------|-----------|----------|
+| `disabled` | `AUTH_ADAPTER` not set | No auth middleware |
+| `enabled` | Valid configuration | Auth active |
+| `error` | Invalid configuration | Disabled with error details |
+
+**Check Auth Status:**
+
+```typescript
+import { getAuthStatus } from '@qwickapps/server';
+
+const status = getAuthStatus();
+// { state: 'enabled', adapter: 'supertokens', config: {...} }
+```
+
+##### Programmatic Configuration
+
+For more control, configure adapters directly in code:
+
+```typescript
+import { createAuthPlugin, auth0Adapter, basicAdapter } from '@qwickapps/server';
+
+// Auth0 with RBAC and domain restrictions
+createAuthPlugin({
+  adapter: auth0Adapter({
+    domain: process.env.AUTH0_DOMAIN!,
+    clientId: process.env.AUTH0_CLIENT_ID!,
+    clientSecret: process.env.AUTH0_CLIENT_SECRET!,
+    baseUrl: 'https://myapp.example.com',
+    secret: process.env.SESSION_SECRET!,
+    audience: process.env.AUTH0_AUDIENCE,    // For API access tokens
+    allowedRoles: ['admin', 'support'],       // RBAC filtering
+    allowedDomains: ['@company.com'],         // Domain whitelist
+    exposeAccessToken: true,                  // For downstream API calls
+  }),
+  excludePaths: ['/health', '/api/public'],
+});
+
+// Basic auth fallback
+createAuthPlugin({
+  adapter: basicAdapter({
+    username: 'admin',
+    password: process.env.ADMIN_PASSWORD!,
+  }),
+});
+```
+
+**Available Adapters:**
+- `supertokensAdapter` - Supertokens email/password + social logins (requires `supertokens-node`)
+- `auth0Adapter` - Auth0 OIDC (requires `express-openid-connect`)
+- `supabaseAdapter` - Supabase JWT validation
+- `basicAdapter` - HTTP Basic authentication
+
+**Helper Functions:**
+```typescript
+import { isAuthenticated, getAuthenticatedUser, getAccessToken } from '@qwickapps/server';
+
+// In your route handlers
+if (isAuthenticated(req)) {
+  const user = getAuthenticatedUser(req);
+  // { id, email, name, picture, emailVerified, roles }
+
+  const accessToken = getAccessToken(req);
+  // Use for downstream API calls
+}
+```
+
+**Middleware Helpers:**
+```typescript
+import { requireAuth, requireRoles, requireAnyRole } from '@qwickapps/server';
+
+// Require authentication
+app.get('/admin', requireAuth(), (req, res) => { ... });
+
+// Require specific roles (all required)
+app.get('/admin/users', requireRoles('admin', 'user-manager'), (req, res) => { ... });
+
+// Require any of the roles
+app.get('/dashboard', requireAnyRole('admin', 'editor', 'viewer'), (req, res) => { ... });
+```
+
+#### Users Plugin
+
+Storage-agnostic user management with ban support.
+
+```typescript
+import { createUsersPlugin, postgresUserStore, getPostgres } from '@qwickapps/server';
+import { Pool } from 'pg';
+
+// Create with PostgreSQL storage
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+createUsersPlugin({
+  store: postgresUserStore({
+    pool,
+    usersTable: 'users',
+    bansTable: 'user_bans',
+    autoCreateTables: true,
+  }),
+  bans: {
+    enabled: true,
+    supportTemporary: true, // Enable expiring bans
+    onBan: async (user, ban) => {
+      // Notify external systems, revoke sessions, etc.
+      console.log(`User ${user.email} banned: ${ban.reason}`);
+    },
+    onUnban: async (user) => {
+      console.log(`User ${user.email} unbanned`);
+    },
+  },
+  api: {
+    prefix: '/api/users',
+    crud: true,    // GET/POST/PUT/DELETE /api/users
+    search: true,  // GET /api/users?q=...
+    bans: true,    // Ban management endpoints
+  },
+});
+```
+
+**REST API Endpoints:**
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/users` | GET | List/search users |
+| `/api/users` | POST | Create user |
+| `/api/users/:id` | GET | Get user by ID |
+| `/api/users/:id` | PUT | Update user |
+| `/api/users/:id` | DELETE | Delete user |
+| `/api/users/bans` | GET | List active bans |
+| `/api/users/:id/ban` | GET | Get user's ban status |
+| `/api/users/:id/ban` | POST | Ban user |
+| `/api/users/:id/ban` | DELETE | Unban user |
+| `/api/users/:id/bans` | GET | Get user's ban history |
+
+**Helper Functions:**
+```typescript
+import { getUserById, getUserByEmail, isUserBanned, findOrCreateUser } from '@qwickapps/server';
+
+// Get user
+const user = await getUserById('user-123');
+const userByEmail = await getUserByEmail('test@example.com');
+
+// Check ban status
+const banned = await isUserBanned('user-123');
+
+// Find or create from auth provider
+const user = await findOrCreateUser({
+  email: 'user@example.com',
+  name: 'Test User',
+  external_id: 'auth0|12345',
+  provider: 'auth0',
+});
+```
+
+**Email Ban Support (for auth-only scenarios):**
+
+For cases where you don't store users locally but need to ban by email:
+
+```typescript
+import { isEmailBanned, getEmailBan, banEmail, unbanEmail } from '@qwickapps/server';
+
+// Check if email is banned
+const banned = await isEmailBanned('user@example.com');
+
+// Get ban details
+const ban = await getEmailBan('user@example.com');
+
+// Ban an email
+await banEmail({
+  email: 'user@example.com',
+  reason: 'Spam activity',
+  banned_by: 'admin@company.com',
+  duration: 86400, // 24 hours (optional, null = permanent)
+});
+
+// Unban an email
+await unbanEmail({
+  email: 'user@example.com',
+  unbanned_by: 'admin@company.com',
+  note: 'Cleared after review',
+});
+```
+
+**Email Ban API Endpoints:**
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/users/email-bans` | GET | List active email bans |
+| `/api/users/email-bans/:email` | GET | Check email ban status |
+| `/api/users/email-bans` | POST | Ban an email |
+| `/api/users/email-bans/:email` | DELETE | Unban an email |
+
+#### Preferences Plugin
+
+Per-user preferences storage with PostgreSQL Row-Level Security (RLS) for data isolation.
+
+```typescript
+import { createPreferencesPlugin, postgresPreferencesStore } from '@qwickapps/server';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+createPreferencesPlugin({
+  store: postgresPreferencesStore({
+    pool,
+    tableName: 'user_preferences',
+    autoCreateTables: true,
+    enableRLS: true,  // Enable Row-Level Security
+  }),
+  defaults: {
+    theme: 'system',
+    notifications: {
+      email: true,
+      push: true,
+    },
+  },
+  api: {
+    prefix: '/preferences',
+    enabled: true,
+  },
+});
+```
+
+**Note:** The Preferences plugin requires the Users plugin to be loaded first, as it creates a foreign key reference to the users table.
+
+**REST API Endpoints:**
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/preferences` | GET | Get current user's preferences (merged with defaults) |
+| `/api/preferences` | PUT | Update preferences (deep merge with existing) |
+| `/api/preferences` | DELETE | Reset preferences to defaults |
+
+**Helper Functions:**
+```typescript
+import {
+  getPreferences,
+  updatePreferences,
+  deletePreferences,
+  getDefaultPreferences,
+  deepMerge,
+} from '@qwickapps/server';
+
+// Get user preferences (merged with defaults)
+const prefs = await getPreferences('user-123');
+
+// Update preferences (deep merge - preserves nested values)
+const updated = await updatePreferences('user-123', {
+  theme: 'dark',
+  notifications: { email: false },
+});
+// Result: { theme: 'dark', notifications: { email: false, push: true } }
+
+// Reset to defaults
+await deletePreferences('user-123');
+
+// Get configured defaults
+const defaults = getDefaultPreferences();
+
+// Deep merge utility (exported for custom use)
+const merged = deepMerge(baseObject, overrides);
+```
+
+**Security Features:**
+- PostgreSQL Row-Level Security ensures users can only access their own preferences
+- Transaction-safe RLS context for connection pooling compatibility
+- Input validation: 100KB size limit, 10-level nesting depth
+- Foreign key to users table with `ON DELETE CASCADE`
+
 ### Creating Custom Plugins
 
 ```typescript

package/dist/core/control-panel.d.ts

@@ -6,10 +6,15 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 import { type LoggingConfig } from './logging.js';
-import type { ControlPanelConfig, ControlPanelPlugin, ControlPanelInstance, Logger } from './types.js';
+import type { ControlPanelConfig, ControlPanelInstance, Logger } from './types.js';
+import { type Plugin, type PluginConfig } from './plugin-registry.js';
 export interface CreateControlPanelOptions {
     config: ControlPanelConfig;
-    plugins?: ControlPanelPlugin[];
+    /** Plugins to start with the control panel */
+    plugins?: Array<{
+        plugin: Plugin;
+        config?: PluginConfig;
+    }>;
     logger?: Logger;
     /** Logging configuration */
     logging?: LoggingConfig;

package/dist/core/control-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-panel.d.ts","sourceRoot":"","sources":["../../src/core/control-panel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5F,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EAIpB,MAAM,EACP,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,oBAAoB,CA4Q3F"}
+{"version":3,"file":"control-panel.d.ts","sourceRoot":"","sources":["../../src/core/control-panel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5F,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EAGpB,MAAM,EACP,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAuB9B,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,oBAAoB,CA+U3F"}