@qwickapps/server 1.5.2 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to @qwickapps/server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.6.1] - 2026-01-09
+
+### Added
+
+- **Seed Management UI**: Database seed script management with real-time execution monitoring (#702)
+  - Seed discovery: Auto-discover `seed-*.mjs` scripts in configured scripts directory
+  - Real-time execution: Stream stdout/stderr via Server-Sent Events (SSE)
+  - Execution history: Track seed runs with status, duration, and output (requires PostgreSQL)
+  - Security: Path traversal prevention, concurrent execution blocking, minimal environment isolation
+  - API endpoints: `/api/maintenance/seeds/discover`, `/api/maintenance/seeds/execute`, `/api/maintenance/seeds/history`
+  - Startup cleanup: Automatically marks orphaned 'running' executions as failed on server restart
+  - Process isolation: Child processes spawned with `process.execPath` for reliable node binary resolution
+
+- **Preferences UI**: User preferences management page with JSON editor (#592)
+  - PreferencesPage component with real-time JSON validation and syntax highlighting
+  - Client-side nesting depth validation (max 10 levels)
+  - Size limit indicator with color coding (100KB max)
+  - Actions: Save, Reset to Defaults, Format JSON
+  - Preferences API methods: `getPreferences()`, `updatePreferences()`, `deletePreferences()`
+  - Exported `MAX_PREFERENCES_SIZE` and `MAX_NESTING_DEPTH` constants from backend types
+  - Plugin registry integration: backend registers UI page via `registry.addPage()`
+
+- **API Keys Phase 2: Scope-Based Authorization** (#573)
+  - Plugin-declared scopes: Plugins can now declare scopes via `scopes` property
+  - QwickBrain declares `qwickbrain:read` and `qwickbrain:execute` scopes
+  - Automatic scope registration: API Keys plugin auto-registers scopes when plugins start
+  - Plugin scope store: PostgreSQL storage for plugin-declared scopes with caching
+  - Usage log store: Partitioned tables track all API key requests with 30-day intervals
+  - GET `/cpanel/api/auth/scopes` endpoint - List all available scopes grouped by plugin
+  - GET `/cpanel/api/auth/keys/:id/usage` endpoint - Usage logs with query filters and statistics
+  - Usage logging middleware: Async, non-blocking request logging using setImmediate
+  - Scope format: `plugin-id:action` (e.g., `qwickbrain:execute`)
+  - Backwards compatibility: Legacy scopes (`read`, `write`, `admin`) auto-convert to `system:*`
+  - System scopes seeded: `system:read`, `system:write`, `system:admin`
+  - Usage statistics: Calls by status code, calls by endpoint, total calls, last used timestamp
+
+## [1.6.1] - 2026-01-06
+
+### Fixed
+
+- **Plugin Route Prefixes** - Auto-detect and fix duplicate slug prefixes in plugin routes (#746)
+  - Added runtime auto-fix in plugin-registry.ts to detect duplicate slug in route paths
+  - Auto-normalizes paths to prevent double-prefixing (e.g., `/api/users/users` → `/api/users`)
+  - Logs warning with fix instructions when duplicate detected
+  - Added pre-commit hook to catch duplicate slug patterns before commit
+  - Fixed authkeaper plugin configurations (users, bans, entitlements, auth0-settings)
+  - Prevents 404 errors caused by double-prefixed routes
+
+## [1.6.0] - 2025-12-25
+
+### Added
+
+- **User Invitation System** - Complete user invitation workflow for control panel
+  - Added invitation creation, acceptance, and management APIs
+  - Added `AcceptInvitationPage` UI for users to accept invitations
+  - Added invitation UI to `UsersPage` for admins to send invitations
+  - Store invitations in PostgreSQL with expiration and token validation
+  - Support for role assignment during invitation
+
+### Fixed
+
+- **Frontend API Paths** - Fixed UI calling incorrect API endpoints
+  - Updated logs API paths: `/api/logs` → `/api/logs/logs`, `/api/logs/sources` → `/api/logs/logs/sources`
+  - Updated users API paths: `/api/users` → `/api/users/users` and all related endpoints
+  - Fixes "Logs request failed" error on logs page
+  - Fixes users page indefinite loading issue
+  - Aligns frontend paths with plugin slug prefixing (introduced in v1.6.0)
+- **Route Registration** - Fixed plugin routes not being accessible
+  - Plugin routes now correctly register on the router instead of app
+  - Routes are properly mounted at `/cpanel/api/*` endpoints
+  - Fixes 404 errors for `/cpanel/api/users`, `/cpanel/api/logs`, etc.
+- **Auth Exclusion Paths** - Fixed auth middleware blocking control panel
+  - Added `/cpanel` to excludePaths to match both `/cpanel` and `/cpanel/*`
+  - Control panel now correctly bypasses SuperTokens authentication
+  - Basic auth guard works properly for admin access
+
+### Removed
+
+- **QwickBrain Plugin** - Removed redundant `qwickbrain-tailscale` health check
+  - Removed health check that required tailscale CLI inside Docker container
+  - Removed `tailscaleStatus` field from `QwickBrainConnectionStatus` interface
+  - Removed `checkTailscaleStatus()` function
+  - Existing `tailscale` and `qwickbrain-connection` health checks provide sufficient monitoring
+
 ## [1.5.2] - 2025-12-21
 
 ### Fixed

package/README.md

@@ -306,6 +306,182 @@ createFrontendAppPlugin({
 })
 ```
 
+### API Authentication (M2M)
+
+Enable machine-to-machine authentication for your API routes using bearer tokens. This is ideal for service-to-service communication.
+
+#### Prerequisites
+
+API authentication requires the rate-limit plugin:
+
+```typescript
+import { createRateLimitPlugin, postgresRateLimitStore, getPostgres } from '@qwickapps/server';
+
+plugins: [
+  // PostgreSQL plugin (required by rate-limit)
+  {
+    plugin: createPostgresPlugin({
+      url: process.env.DATABASE_URL,
+    }),
+  },
+
+  // Rate-limit plugin (required by API keys auth)
+  {
+    plugin: createRateLimitPlugin({
+      store: postgresRateLimitStore({
+        pool: () => getPostgres().getPool(),
+      }),
+      defaults: {
+        maxRequests: 1000,
+        windowMs: 60000, // 1 minute
+      },
+    }),
+  },
+]
+```
+
+#### Enabling Authentication on Routes
+
+Routes can opt-in to M2M authentication by setting `auth: { required: true }`:
+
+```typescript
+import { createControlPanel } from '@qwickapps/server';
+
+const controlPanel = createControlPanel({
+  config: { /* ... */ },
+  plugins: [
+    {
+      plugin: {
+        name: 'my-api',
+        async start({ registry }) {
+          // Authenticated route - requires API key
+          registry.addRoute({
+            method: 'post',
+            path: '/api/jobs/schedule',
+            pluginId: 'my-api',
+            auth: { required: true }, // Enable authentication
+            handler: async (req, res) => {
+              // req.apiKey contains verified key info
+              res.json({ success: true });
+            },
+          });
+
+          // Public route - no authentication required
+          registry.addRoute({
+            method: 'get',
+            path: '/api/status',
+            pluginId: 'my-api',
+            // No auth property = unauthenticated
+            handler: async (req, res) => {
+              res.json({ status: 'ok' });
+            },
+          });
+        },
+      },
+    },
+  ],
+});
+```
+
+#### Generating API Keys
+
+Create M2M API keys for your clients:
+
+```typescript
+import { createApiKey } from '@qwickapps/server';
+
+// Generate a new M2M API key
+const apiKey = await createApiKey({
+  user_id: '00000000-0000-0000-0000-000000000000', // Service user ID
+  name: 'production-worker',
+  key_type: 'm2m', // Machine-to-machine
+  scopes: [], // No scopes required in Phase 1A
+  expires_at: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // 90 days
+});
+
+console.log(`API Key: ${apiKey.plaintext_key}`);
+// Output: qk_live_BdrbOkdpYidqkx0vkFnulmSUR4eYFLbAGndrPOAOxM8
+```
+
+**Important**: The `plaintext_key` is only returned once during creation. Store it securely.
+
+#### Using API Keys
+
+Clients pass the API key in the `Authorization` header:
+
+```bash
+# cURL example
+curl -X POST https://api.example.com/api/jobs/schedule \
+  -H "Authorization: Bearer qk_live_BdrbOkdpYidqkx0vkFnulmSUR4eYFLbAGndrPOAOxM8" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "llm-completion", "model": "gpt-3.5-turbo"}'
+```
+
+```typescript
+// Node.js example
+const response = await fetch('https://api.example.com/api/jobs/schedule', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.API_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    type: 'llm-completion',
+    model: 'gpt-3.5-turbo',
+  }),
+});
+```
+
+#### API Key Management
+
+```typescript
+import { listApiKeys, getApiKey, updateApiKey, deleteApiKey } from '@qwickapps/server';
+
+// List all keys for a user
+const keys = await listApiKeys(userId);
+
+// Get specific key
+const key = await getApiKey(userId, keyId);
+
+// Update key (name, scopes, expiration, active status)
+await updateApiKey(userId, keyId, {
+  name: 'updated-name',
+  is_active: false, // Disable key
+});
+
+// Delete (revoke) key
+await deleteApiKey(userId, keyId);
+```
+
+#### Security Best Practices
+
+1. **Store keys securely**: Use environment variables or secrets management
+2. **Rotate keys regularly**: Generate new keys and delete old ones every 90 days
+3. **Use HTTPS**: Always transmit keys over encrypted connections
+4. **Monitor usage**: Track `last_used_at` to identify unused keys
+5. **Set expiration**: Configure `expires_at` for automatic key expiry
+6. **Revoke compromised keys**: Delete keys immediately if leaked
+
+#### Error Handling
+
+Authentication failures return HTTP 401:
+
+```json
+{
+  "success": false,
+  "error": "Invalid, expired, or inactive API key"
+}
+```
+
+Rate limit exceeded returns HTTP 429:
+
+```json
+{
+  "success": false,
+  "error": "Rate limit exceeded"
+}
+```
+
 ## Plugins
 
 ### Built-in Plugins
@@ -1056,3 +1232,4 @@ For commercial licensing options, contact **legal@qwickapps.com**.
 ---
 
 Copyright (c) 2025 QwickApps. All rights reserved.
+# Build trigger Mon Dec 29 09:36:28 EST 2025

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,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,CA8Y3F"}
+{"version":3,"file":"control-panel.d.ts","sourceRoot":"","sources":["../../src/core/control-panel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,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;AAyB9B,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;AAyDD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,oBAAoB,CAqW3F"}