@qwickapps/server 1.6.0 → 1.7.0

package/README.md

@@ -12,12 +12,21 @@ A flexible, pluggable control panel framework for QwickApps services. Provides a
 - **Frontend App Support**: Handle root path with redirect, static files, or landing page
 - **Theming**: Customizable branding and styling
 
-## What's New in v1.5.0
-
-- **Notifications Plugin UI** - Full management page for SSE notifications with stats widget, connected clients table, and disconnect controls
-- **Users Plugin Enhancements** - Multi-identifier user lookup (`getUserByIdentifier`), batch queries (`getUsersByIds`), and identifier linking
-- **User Search & Ban Management** - Enhanced Control Panel with user search by email/name/ID and ban/unban actions
-- **Audit Logging** - Admin actions now include user context (email, IP) for better traceability
+## What's New in v1.7.0
+
+- **Tenants Plugin** - Complete multi-tenancy system with data isolation and organization management
+  - Support for multiple tenant types: user (single-user), organization, group, department
+  - PostgreSQL store with auto-created tables and foreign key CASCADE delete
+  - Global roles: owner, admin, member, viewer
+  - REST API with 10 endpoints for CRUD, search, and membership management
+  - UI Components: Full tenant management page with create/edit/search/filter capabilities
+  - Member management: Add/remove members, change roles, invite via email
+  - Statistics dashboard showing total tenants by type
+- **Plugin Composition** - Auto-tenant creation on user signup
+  - Users plugin detects tenants plugin and auto-creates personal tenant for new users
+  - Graceful degradation: Works independently or together
+  - Loose coupling: No forced dependencies between plugins
+- **Comprehensive Testing** - 60 unit tests, 11 integration tests, 20 E2E tests for tenants plugin
 
 See [CHANGELOG.md](./CHANGELOG.md) for full release history.
 
@@ -67,6 +76,7 @@ console.log(`Control panel running at http://localhost:3101/cpanel`);
 ## Gateway Pattern
 
 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
@@ -306,6 +316,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
@@ -403,6 +589,7 @@ await pg.withTransaction(async (client) => {
 ```
 
 **Exports:**
+
 - `createPostgresPlugin(config)` - Create and register the plugin
 - `getPostgres(name?)` - Get a PostgreSQL instance (throws if not registered)
 - `hasPostgres(name?)` - Check if an instance is registered
@@ -445,6 +632,7 @@ await cache.flush(); // Clear all keys with prefix
 ```
 
 **Exports:**
+
 - `createCachePlugin(config)` - Create and register the plugin
 - `getCache(name?)` - Get a cache instance (throws if not registered)
 - `hasCache(name?)` - Check if an instance is registered
@@ -560,12 +748,14 @@ createAuthPlugin({
 ```
 
 **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';
 
@@ -580,6 +770,7 @@ if (isAuthenticated(req)) {
 ```
 
 **Middleware Helpers:**
+
 ```typescript
 import { requireAuth, requireRoles, requireAnyRole } from '@qwickapps/server';
 
@@ -632,6 +823,7 @@ createUsersPlugin({
 ```
 
 **REST API Endpoints:**
+
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/api/users` | GET | List/search users |
@@ -646,6 +838,7 @@ createUsersPlugin({
 | `/api/users/:id/bans` | GET | Get user's ban history |
 
 **Helper Functions:**
+
 ```typescript
 import { getUserById, getUserByEmail, isUserBanned, findOrCreateUser } from '@qwickapps/server';
 
@@ -694,7 +887,115 @@ await unbanEmail({
 });
 ```
 
+#### Tenants Plugin
+
+Multi-tenant data isolation and organization management with role-based access control.
+
+```typescript
+import { createTenantsPlugin, postgresTenantStore } from '@qwickapps/server';
+import { Pool } from 'pg';
+
+// Create with PostgreSQL storage
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+createTenantsPlugin({
+  store: postgresTenantStore({
+    pool,
+    tenantsTable: 'tenants',
+    membershipsTable: 'tenant_memberships',
+    autoCreateTables: true,
+  }),
+  apiPrefix: '/api/tenants',
+  apiEnabled: true,
+});
+```
+
+**Tenant Types:**
+
+- `user` - Single-user personal tenant (auto-created on user signup)
+- `organization` - Multi-user organization
+- `group` - Team or project group
+- `department` - Company department
+
+**Global Roles:**
+
+- `owner` - Full control, can delete tenant
+- `admin` - Manage members and settings
+- `member` - Standard access
+- `viewer` - Read-only access
+
+**Authentication & Authorization:**
+
+All tenant API routes require authentication. Authorization rules:
+
+- **List tenants**: Users can only list their own tenants
+- **Get/View tenant**: User must be a member of the tenant
+- **Create tenant**: User can only create tenants for themselves (auto-added as owner)
+- **Update tenant**: User must be admin or owner
+- **Delete tenant**: User must be owner only
+- **View members**: User must be a member of the tenant
+- **Add/Remove members**: User must be admin or owner
+- **Update member roles**: User must be admin or owner
+
+**REST API Endpoints:**
+
+| Endpoint | Method | Description | Auth Required |
+|----------|--------|-------------|---------------|
+| `/api/tenants` | GET | List user's tenants | Yes (returns only user's tenants) |
+| `/api/tenants` | POST | Create tenant | Yes (owner auto-set to current user) |
+| `/api/tenants/:id` | GET | Get tenant by ID | Yes (must be member) |
+| `/api/tenants/:id` | PUT | Update tenant | Yes (admin or owner) |
+| `/api/tenants/:id` | DELETE | Delete tenant | Yes (owner only) |
+| `/api/tenants/user/:userId` | GET | Get user's tenants | Yes (own tenants only) |
+| `/api/tenants/:tenantId/members` | GET | List tenant members | Yes (must be member) |
+| `/api/tenants/:tenantId/members` | POST | Add member | Yes (admin or owner) |
+| `/api/tenants/:tenantId/members/:userId` | PUT | Update member role | Yes (admin or owner) |
+| `/api/tenants/:tenantId/members/:userId` | DELETE | Remove member | Yes (admin or owner) |
+
+**Helper Functions:**
+
+```typescript
+import { getTenantStore } from '@qwickapps/server';
+
+const store = getTenantStore();
+
+// Get tenant
+const tenant = await store.getById('tenant-123');
+
+// Search tenants
+const results = await store.search({
+  type: 'organization',
+  query: 'acme',
+  page: 1,
+  limit: 20,
+});
+
+// Get user's tenants
+const userTenants = await store.getTenantsForUser('user-123');
+
+// Manage members
+await store.addMember({
+  tenant_id: 'tenant-123',
+  user_id: 'user-456',
+  role: 'member',
+});
+```
+
+**Plugin Composition:**
+
+The Tenants plugin integrates seamlessly with the Users plugin through the plugin registry:
+
+```typescript
+// Users plugin auto-detects tenants plugin
+createUsersPlugin({ store: userStore });
+createTenantsPlugin({ store: tenantStore });
+
+// When a user is created, a personal tenant is auto-created
+// Works gracefully whether tenants plugin is present or not
+```
+
 **Email Ban API Endpoints:**
+
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/api/users/email-bans` | GET | List active email bans |
@@ -702,6 +1003,116 @@ await unbanEmail({
 | `/api/users/email-bans` | POST | Ban an email |
 | `/api/users/email-bans/:email` | DELETE | Unban an email |
 
+#### Tenants Plugin
+
+Multi-tenant data isolation and organization management with role-based access control.
+
+```typescript
+import { createTenantsPlugin, postgresTenantStore } from '@qwickapps/server';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+createTenantsPlugin({
+  store: postgresTenantStore({
+    pool,
+    tenantsTable: 'tenants',
+    membershipsTable: 'tenant_memberships',
+    autoCreateTables: true,
+  }),
+  apiPrefix: '/api/tenants',
+  apiEnabled: true,
+  debug: false,
+});
+```
+
+**Tenant Types:**
+
+- `user` - Single-user personal tenant (auto-created for each user)
+- `organization` - Multi-user organization with team members
+- `group` - Collaborative group workspace
+- `department` - Department or division within an organization
+
+**Global Roles:**
+
+- `owner` - Full control, can delete tenant
+- `admin` - Administrative access, can manage members
+- `member` - Standard member access
+- `viewer` - Read-only access
+
+**Features:**
+
+- Auto-creates owner membership when tenant is created
+- Foreign key constraints with CASCADE delete for data integrity
+- UPSERT behavior for membership updates (ON CONFLICT DO UPDATE)
+- Search with filtering by type, owner, and query string
+- Pagination and sorting support
+
+**Authentication & Authorization:**
+
+All tenant API routes require authentication. Authorization rules enforce tenant-level access control:
+
+- **List tenants**: Users see only their own tenants
+- **Get tenant**: User must be a member
+- **Create tenant**: Auto-added as owner
+- **Update tenant**: Admin or owner role required
+- **Delete tenant**: Owner role only
+- **Manage members**: Admin or owner role required
+
+**REST API Endpoints:**
+
+| Endpoint | Method | Description | Authorization |
+|----------|--------|-------------|---------------|
+| `/api/tenants` | GET | List/search user's tenants | Authenticated (returns user's tenants) |
+| `/api/tenants` | POST | Create new tenant | Authenticated (becomes owner) |
+| `/api/tenants/:id` | GET | Get tenant by ID | Member of tenant |
+| `/api/tenants/:id` | PUT | Update tenant | Admin or owner |
+| `/api/tenants/:id` | DELETE | Delete tenant (cascades) | Owner only |
+| `/api/tenants/user/:userId` | GET | Get tenants for user | Own tenants only |
+| `/api/tenants/:tenantId/members` | GET | List tenant members | Member of tenant |
+| `/api/tenants/:tenantId/members` | POST | Add member to tenant | Admin or owner |
+| `/api/tenants/:tenantId/members/:userId` | PUT | Update member role | Admin or owner |
+| `/api/tenants/:tenantId/members/:userId` | DELETE | Remove member | Admin or owner |
+
+**Helper Functions:**
+
+```typescript
+import { getTenantStore } from '@qwickapps/server';
+
+const store = getTenantStore();
+
+// Get tenant
+const tenant = await store.getById('tenant-123');
+
+// Get all tenants for a user with membership info
+const tenants = await store.getTenantsForUser('user-123');
+
+// Create organization tenant
+const org = await store.create({
+  name: 'Acme Corp',
+  type: 'organization',
+  owner_id: 'user-123',
+  metadata: { industry: 'technology' },
+});
+
+// Add team member
+await store.addMember({
+  tenant_id: org.id,
+  user_id: 'user-456',
+  role: 'admin',
+});
+
+// Search tenants
+const results = await store.search({
+  query: 'acme',
+  type: 'organization',
+  page: 1,
+  limit: 20,
+  sortBy: 'name',
+  sortOrder: 'asc',
+});
+```
+
 #### Preferences Plugin
 
 Per-user preferences storage with PostgreSQL Row-Level Security (RLS) for data isolation.
@@ -736,6 +1147,7 @@ createPreferencesPlugin({
 **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) |
@@ -743,6 +1155,7 @@ createPreferencesPlugin({
 | `/api/preferences` | DELETE | Reset preferences to defaults |
 
 **Helper Functions:**
+
 ```typescript
 import {
   getPreferences,
@@ -773,6 +1186,7 @@ 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
@@ -831,6 +1245,7 @@ app.use(rateLimitMiddleware({
 ```
 
 **Rate Limiting Strategies:**
+
 | Strategy | Description | Best For |
 |----------|-------------|----------|
 | `sliding-window` | Smooth rate limiting with weighted overlap | Most use cases (default) |
@@ -838,6 +1253,7 @@ app.use(rateLimitMiddleware({
 | `token-bucket` | Allows bursts while maintaining average rate | APIs needing burst capacity |
 
 **REST API Endpoints:**
+
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/api/rate-limit/status` | GET | Get rate limit status for current user |
@@ -845,6 +1261,7 @@ app.use(rateLimitMiddleware({
 | `/api/rate-limit/clear/:key` | DELETE | Clear a rate limit (requires auth) |
 
 **Programmatic API:**
+
 ```typescript
 import {
   isLimited,
@@ -870,6 +1287,7 @@ await clearLimit('user:123:api');
 ```
 
 **Response Headers:**
+
 ```
 RateLimit-Limit: 100
 RateLimit-Remaining: 55
@@ -878,6 +1296,7 @@ Retry-After: 30  (only when limited)
 ```
 
 **Security Features:**
+
 - PostgreSQL Row-Level Security isolates rate limits per user
 - Redis caching with in-memory fallback for high availability
 - Fail-open by default (allows requests on errors)
@@ -919,12 +1338,14 @@ Config status endpoint: `GET /api/rate-limit/config/status`
 **Runtime Configuration UI:**
 
 The Rate Limit plugin includes a Control Panel page for live configuration:
+
 - Navigate to `/rate-limits` in the Control Panel
 - Edit default window size, max requests, and strategy
 - Toggle cleanup job on/off and adjust interval
 - Changes take effect immediately (no restart required)
 
 **Runtime Config API:**
+
 ```bash
 # Get current config
 curl http://localhost:3000/api/rate-limit/config
@@ -1037,6 +1458,7 @@ This software is licensed under the **PolyForm Shield License 1.0.0**.
 ### What This Means
 
 **Permitted Uses:**
+
 - Internal business applications
 - Learning and educational projects
 - Non-competitive commercial applications
@@ -1044,6 +1466,7 @@ This software is licensed under the **PolyForm Shield License 1.0.0**.
 - Building applications that use this control panel framework
 
 **Prohibited Uses:**
+
 - Creating competing control panel frameworks
 - Building competing developer tools or dashboards
 - Reselling or redistributing as a competing product
@@ -1051,8 +1474,10 @@ This software is licensed under the **PolyForm Shield License 1.0.0**.
 
 For full license terms, see [PolyForm Shield 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/).
 
-For commercial licensing options, contact **legal@qwickapps.com**.
+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/src/core/control-panel.d.ts.map

@@ -0,0 +1 @@
+{"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"}