npm - json-rest-api - Versions diffs - 1.0.22 → 1.0.24 - Mend

json-rest-api 1.0.22 → 1.0.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (290) hide show

package/docs/GUIDE/GUIDE_X_Multihome.md DELETED Viewed

@@ -1,666 +0,0 @@
-# Multi-Tenancy with the MultiHome Plugin
-The MultiHome plugin provides automatic data isolation for multi-tenant applications. It ensures that users can only access data belonging to their tenant, making it impossible to accidentally or maliciously access data from other tenants.
-## Table of Contents
-- [Overview](#overview)
-- [How It Works](#how-it-works)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Usage Examples](#usage-examples)
-- [Security Features](#security-features)
-- [Integration with Other Plugins](#integration-with-other-plugins)
-- [API Reference](#api-reference)
-- [Troubleshooting](#troubleshooting)
-- [Best Practices](#best-practices)
-## Overview
-Multi-tenancy is a critical requirement for SaaS applications where multiple customers (tenants) share the same application instance but must have completely isolated data. The MultiHome plugin makes this easy by:
-- **Automatic Query Filtering**: Every database query automatically includes a WHERE clause for the tenant ID
-- **Automatic Record Assignment**: New records are automatically assigned to the current tenant
-- **Request-Based Tenant Detection**: Extracts tenant ID from subdomain, header, path, or custom logic
-- **Zero Data Leakage**: Makes it impossible to access data from the wrong tenant
-- **Flexible Configuration**: Supports various multi-tenancy strategies
-## How It Works
-The plugin operates at multiple levels to ensure complete data isolation:
-### 1. Tenant Extraction (Transport Layer)
-When a request arrives, the plugin extracts the tenant ID using a configurable extractor function:
-```javascript
-// Default: Extract from subdomain
-// mobily.app.com → tenant_id = 'mobily'
-// acme.app.com → tenant_id = 'acme'
-```
-### 2. Query Filtering (Database Layer)
-Every database query is automatically modified to include the tenant filter:
-```sql
--- Original query
-SELECT * FROM posts WHERE status = 'published'
--- Modified query (automatic)
-SELECT * FROM posts WHERE status = 'published' AND multihome_id = 'mobily'
-```
-### 3. Record Creation (API Layer)
-When creating new records, the tenant ID is automatically set:
-```javascript
-// User sends:
-POST /api/posts
-{ "title": "My Post", "content": "..." }
-// Plugin automatically adds:
-{ "title": "My Post", "content": "...", "multihome_id": "mobily" }
-```
-## Installation
-1. First, ensure you have the required dependencies:
-```javascript
-import { Api } from 'hooked-api';
-import { RestApiPlugin } from './plugins/core/rest-api-plugin.js';
-import { RestApiKnexPlugin } from './plugins/core/rest-api-knex-plugin.js';
-import { ExpressPlugin } from './plugins/core/connectors/express-plugin.js';
-import { MultiHomePlugin } from './plugins/core/multihome-plugin.js';
-```
-2. Create your API and install the plugins:
-```javascript
-const api = new Api({
-  name: 'my-multi-tenant-api',
-});
-// Install required plugins first
-await api.use(RestApiPlugin);
-await api.use(RestApiKnexPlugin, { knex: knexInstance });
-await api.use(ExpressPlugin, { app: expressApp });
-// Install MultiHome plugin
-await api.use(MultiHomePlugin, {
-  field: 'tenant_id',              // The database field name
-  excludeResources: ['migrations'], // Resources to exclude
-  requireAuth: true,               // Require tenant context
-  allowMissing: false,             // Require field in schema
-  extractor: (request) => {        // Custom extraction logic
-    // Extract from subdomain
-    const host = request.headers.host;
-    const subdomain = host.split('.')[0];
-    return subdomain;
-  }
-});
-```
-3. Add the tenant field to your resource schemas:
-```javascript
-api.addResource('posts', {
-  schema: {
-    title: { type: 'string', required: true },
-    content: { type: 'string' },
-    tenant_id: { type: 'string', required: true } // Required field
-  }
-});
-```
-## Configuration
-### Plugin Options
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `field` | string | `'multihome_id'` | The database field name for tenant ID |
-| `excludeResources` | array | `['system_migrations', 'system_logs']` | Resources that don't need tenant isolation |
-| `requireAuth` | boolean | `true` | Whether to require tenant context for all operations |
-| `allowMissing` | boolean | `false` | Whether to allow resources without the tenant field |
-| `extractor` | function | Subdomain extractor | Function to extract tenant ID from request |
-### Default Extractor
-The default extractor tries multiple sources:
-1. **Subdomain**: `tenant1.app.com` → `tenant1`
-2. **Header**: `X-Multihome-ID: tenant1`
-3. Returns `null` if no tenant found
-Common subdomains like 'www', 'api', 'app' are ignored.
-### Custom Extractors
-You can provide your own extractor function:
-```javascript
-// Extract from JWT token
-extractor: (request) => {
-  const token = request.headers.authorization?.split(' ')[1];
-  if (token) {
-    const decoded = jwt.verify(token, secret);
-    return decoded.tenant_id;
-  }
-  return null;
-}
-// Extract from URL path
-extractor: (request) => {
-  // /api/tenants/acme/posts → 'acme'
-  const match = request.path.match(/\/tenants\/([^\/]+)/);
-  return match ? match[1] : null;
-}
-// Extract from custom header
-extractor: (request) => {
-  return request.headers['x-tenant-id'];
-}
-// Complex logic with fallbacks
-extractor: (request) => {
-  // Try JWT first
-  if (request.auth?.claims?.tenant_id) {
-    return request.auth.claims.tenant_id;
-  }
-  // Then try subdomain
-  const subdomain = request.headers.host?.split('.')[0];
-  if (subdomain && !['www', 'api'].includes(subdomain)) {
-    return subdomain;
-  }
-  // Finally try header
-  return request.headers['x-customer-id'];
-}
-```
-## Usage Examples
-### Basic Setup with Subdomain-Based Tenancy
-```javascript
-// Configuration
-await api.use(MultiHomePlugin, {
-  field: 'tenant_id',
-  extractor: (request) => {
-    const host = request.headers.host;
-    return host.split('.')[0]; // acme.myapp.com → 'acme'
-  }
-});
-// Define resources with tenant field
-api.addResource('projects', {
-  schema: {
-    name: { type: 'string', required: true },
-    description: { type: 'string' },
-    tenant_id: { type: 'string', required: true }
-  }
-});
-api.addResource('users', {
-  schema: {
-    email: { type: 'string', required: true },
-    name: { type: 'string', required: true },
-    tenant_id: { type: 'string', required: true }
-  }
-});
-```
-### Header-Based Tenancy for APIs
-```javascript
-// Configuration for API clients that send tenant ID in header
-await api.use(MultiHomePlugin, {
-  field: 'organization_id',
-  extractor: (request) => {
-    const tenantId = request.headers['x-organization-id'];
-    if (!tenantId) {
-      throw new Error('X-Organization-ID header is required');
-    }
-    return tenantId;
-  }
-});
-```
-### JWT-Based Tenancy
-```javascript
-// Works with the JWT Auth plugin
-await api.use(JwtAuthPlugin, { secret: process.env.JWT_SECRET });
-await api.use(MultiHomePlugin, {
-  field: 'company_id',
-  extractor: (request) => {
-    // JWT plugin sets request.auth
-    if (!request.auth?.claims?.company_id) {
-      throw new Error('No company context in JWT token');
-    }
-    return request.auth.claims.company_id;
-  }
-});
-```
-### Mixed Mode with System Resources
-```javascript
-// Some resources are tenant-specific, others are global
-await api.use(MultiHomePlugin, {
-  field: 'tenant_id',
-  excludeResources: [
-    'system_settings',    // Global settings
-    'countries',          // Shared reference data
-    'currencies',         // Shared reference data
-    'audit_logs'          // System-wide audit trail
-  ],
-  allowMissing: true      // Allow resources without tenant_id field
-});
-// Tenant-specific resource
-api.addResource('invoices', {
-  schema: {
-    number: { type: 'string', required: true },
-    amount: { type: 'number', required: true },
-    tenant_id: { type: 'string', required: true }
-  }
-});
-// Global resource (no tenant_id)
-api.addResource('countries', {
-  schema: {
-    code: { type: 'string', required: true },
-    name: { type: 'string', required: true }
-    // No tenant_id field
-  }
-});
-```
-## Security Features
-### 1. Automatic Query Filtering
-Every query is automatically filtered at the database level:
-```javascript
-// User tries to access another tenant's data
-GET /api/posts/123
-// Even if post 123 belongs to another tenant, the query becomes:
-SELECT * FROM posts WHERE id = 123 AND tenant_id = 'current-tenant'
-// Result: 404 Not Found (not a security error message)
-```
-### 2. Validation on Write Operations
-The plugin validates tenant context on all write operations:
-```javascript
-// User tries to create a record with wrong tenant_id
-POST /api/posts
-{
-  "title": "Hacking attempt",
-  "tenant_id": "other-tenant"  // This will be rejected
-}
-// Error: Cannot set tenant_id to 'other-tenant' - must match current context
-```
-### 3. Security Logging
-Security violations are logged for monitoring:
-```javascript
-// When someone tries to access wrong tenant data
-log.error('Multihome security violation attempt', {
-  scopeName: 'posts',
-  recordId: 123,
-  recordMultihomeId: 'tenant-a',
-  contextMultihomeId: 'tenant-b'
-});
-```
-### 4. Fail-Safe Design
-If tenant context is missing and `requireAuth: true`:
-```javascript
-// No tenant context available
-GET /api/posts
-// Error: No multihome context available - cannot execute query
-```
-## Integration with Other Plugins
-### With JWT Auth Plugin
-The MultiHome plugin works seamlessly with JWT authentication:
-```javascript
-// JWT token contains tenant information
-{
-  "sub": "user123",
-  "email": "user@example.com",
-  "tenant_id": "acme-corp",
-  "exp": 1234567890
-}
-// MultiHome extractor uses the JWT claim
-await api.use(MultiHomePlugin, {
-  extractor: (request) => request.auth?.claims?.tenant_id
-});
-```
-### With Express Plugin
-The Express plugin provides the request object that MultiHome uses:
-```javascript
-// Express middleware sets up request
-app.use('/api', (req, res) => {
-  // MultiHome extractor receives the Express request object
-  // with headers, path, auth, etc.
-});
-```
-### With REST API Plugin
-MultiHome integrates at multiple points in the REST API lifecycle:
-1. **Before Schema Validation**: Sets tenant_id on new records
-2. **Before Data Operations**: Validates tenant access
-3. **During Query Building**: Adds WHERE clauses
-## API Reference
-### Configuration API
-```javascript
-// Access current configuration
-const config = api.multihome.getConfig();
-console.log(config);
-// {
-//   field: 'tenant_id',
-//   excludeResources: ['migrations'],
-//   requireAuth: true,
-//   allowMissing: false,
-//   hasCustomExtractor: true
-// }
-```
-### Variables
-The plugin sets these variables accessible via `api.vars.multihome`:
-- `field`: The tenant ID field name
-- `excludeResources`: Array of excluded resource names
-- `requireAuth`: Whether tenant context is required
-- `allowMissing`: Whether resources can omit the tenant field
-### Helpers
-- `helpers.extractMultihomeId(request)`: The configured extractor function
-### Hooks
-The plugin adds these hooks:
-| Hook | When | Purpose |
-|------|------|---------|
-| `transport:request` | Every request | Extract tenant ID from request |
-| `scope:added` | Resource creation | Validate tenant field exists |
-| `knexQueryFiltering` | Database queries | Add WHERE clause for tenant |
-| `beforeSchemaValidate` | Before validation | Set tenant_id on new records |
-| `beforeDataGet/Put/Patch/Delete` | Before operations | Additional security validation |
-## Troubleshooting
-### Common Issues
-#### 1. "No multihome context available"
-**Cause**: The extractor couldn't find a tenant ID in the request.
-**Solutions**:
-- Check your extractor function is returning a value
-- Verify the subdomain/header/token contains tenant information
-- Set `requireAuth: false` if some operations don't need tenant context
-#### 2. "Resource must have 'tenant_id' field in schema"
-**Cause**: A resource is missing the tenant field in its schema.
-**Solutions**:
-- Add the field to the schema
-- Add the resource to `excludeResources` if it's global
-- Set `allowMissing: true` if you have mixed resources
-#### 3. "Cannot set tenant_id to X - must match current context Y"
-**Cause**: Trying to set a different tenant_id than the current context.
-**Solution**: Don't include tenant_id in your requests - it's set automatically.
-#### 4. Queries returning no results
-**Cause**: Data exists but with different tenant_id.
-**Debugging**:
-```javascript
-// Check current tenant context
-api.on('transport:request', (context) => {
-  console.log('Current tenant:', context.auth?.multihome_id);
-});
-// Check query modifications
-api.on('knexQueryFiltering', (context) => {
-  console.log('Query SQL:', context.knexQuery.query.toString());
-});
-```
-### Debug Mode
-Enable detailed logging to troubleshoot:
-```javascript
-const api = new Api({
-  name: 'my-api',
-  logging: { level: 'trace' }
-});
-```
-## Best Practices
-### 1. Schema Design
-Always include the tenant field in your schemas:
-```javascript
-// Good
-api.addResource('orders', {
-  schema: {
-    order_number: { type: 'string', required: true },
-    total: { type: 'number', required: true },
-    tenant_id: { type: 'string', required: true } // Always include
-  }
-});
-```
-### 2. Consistent Field Naming
-Use the same tenant field name across all resources:
-```javascript
-// Configure once
-await api.use(MultiHomePlugin, { field: 'tenant_id' });
-// Use everywhere
-// ✓ Good: All resources use 'tenant_id'
-// ✗ Bad: Some use 'tenant_id', others use 'company_id'
-```
-### 3. Validation in Extractors
-Add validation to your extractor functions:
-```javascript
-extractor: (request) => {
-  const tenantId = request.headers['x-tenant-id'];
-  if (!tenantId) {
-    throw new Error('X-Tenant-ID header is required');
-  }
-  if (!/^[a-z0-9-]+$/.test(tenantId)) {
-    throw new Error('Invalid tenant ID format');
-  }
-  return tenantId;
-}
-```
-### 4. Migration Strategy
-When adding multi-tenancy to an existing application:
-1. Add the tenant field to all tables
-2. Populate existing data with a default tenant
-3. Enable the plugin with `allowMissing: true` initially
-4. Gradually update all resources
-5. Switch to `allowMissing: false` when complete
-### 5. Testing
-Test with multiple tenants:
-```javascript
-describe('Multi-tenancy', () => {
-  it('isolates data between tenants', async () => {
-    // Create data for tenant A
-    const resA = await fetch('https://tenant-a.app.com/api/posts', {
-      method: 'POST',
-      body: JSON.stringify({ title: 'Tenant A Post' })
-    });
-    // Try to access from tenant B
-    const resB = await fetch('https://tenant-b.app.com/api/posts/' + resA.id);
-    expect(resB.status).toBe(404); // Should not find
-  });
-});
-```
-### 6. Performance Considerations
-The tenant field should be indexed for performance:
-```sql
-CREATE INDEX idx_posts_tenant_id ON posts(tenant_id);
-CREATE INDEX idx_posts_tenant_status ON posts(tenant_id, status);
-```
-## Complete Example
-Here's a complete multi-tenant API setup:
-```javascript
-import { Api } from 'hooked-api';
-import { RestApiPlugin } from './plugins/core/rest-api-plugin.js';
-import { RestApiKnexPlugin } from './plugins/core/rest-api-knex-plugin.js';
-import { ExpressPlugin } from './plugins/core/connectors/express-plugin.js';
-import { JwtAuthPlugin } from './plugins/core/jwt-auth-plugin.js';
-import { MultiHomePlugin } from './plugins/core/multihome-plugin.js';
-import knex from 'knex';
-import express from 'express';
-// Initialize
-const app = express();
-const db = knex({
-  client: 'postgresql',
-  connection: process.env.DATABASE_URL
-});
-// Create API
-const api = new Api({
-  name: 'saas-api',
-  logging: { level: 'info' }
-});
-// Install plugins
-await api.use(RestApiPlugin);
-await api.use(RestApiKnexPlugin, { knex: db });
-await api.use(ExpressPlugin, { app });
-await api.use(JwtAuthPlugin, {
-  secret: process.env.JWT_SECRET
-});
-// Configure multi-tenancy
-await api.use(MultiHomePlugin, {
-  field: 'tenant_id',
-  excludeResources: ['system_health', 'public_content'],
-  requireAuth: true,
-  allowMissing: false,
-  extractor: (request) => {
-    // Try multiple sources
-    // 1. JWT token (preferred)
-    if (request.auth?.claims?.tenant_id) {
-      return request.auth.claims.tenant_id;
-    }
-    // 2. Subdomain (fallback)
-    const host = request.headers.host || '';
-    const subdomain = host.split('.')[0];
-    if (subdomain && !['www', 'api', 'app'].includes(subdomain)) {
-      return subdomain;
-    }
-    // 3. Header (API clients)
-    if (request.headers['x-tenant-id']) {
-      return request.headers['x-tenant-id'];
-    }
-    // No tenant found
-    throw new Error('Unable to determine tenant context');
-  }
-});
-// Define tenant-specific resources
-api.addResource('projects', {
-  schema: {
-    name: { type: 'string', required: true },
-    description: { type: 'string' },
-    status: { type: 'string', defaultTo: 'active' },
-    tenant_id: { type: 'string', required: true }
-  }
-});
-api.addResource('team_members', {
-  schema: {
-    email: { type: 'string', required: true },
-    name: { type: 'string', required: true },
-    role: { type: 'string', defaultTo: 'member' },
-    tenant_id: { type: 'string', required: true }
-  }
-});
-// Start server
-app.listen(3000, () => {
-  console.log('Multi-tenant API running on port 3000');
-}).on('error', (err) => {
-  console.error('Failed to start server:', err);
-  process.exit(1)
-});
-```
-Now your API automatically:
-- Extracts tenant ID from JWT tokens, subdomains, or headers
-- Filters all queries by tenant
-- Sets tenant_id on new records
-- Prevents cross-tenant data access
-- Logs security violations
-The MultiHome plugin makes multi-tenancy transparent to your application logic while ensuring complete data isolation.