Tenancy Architecture

ThreatWeaver supports two deployment modes controlled by the DEPLOYMENT_MODE environment variable. Both modes use the same codebase and API surface — the difference is entirely in how data is isolated between tenants.

The backend enforces tenancy through a two-middleware chain (resolveTenant → setTenantSchema) that runs on every authenticated request. This chain reads the deployment mode once at startup and either fast-paths to a static context (dedicated) or resolves per-request context from a JWT claim (SaaS).

---

Deployment Modes

Mode	DEPLOYMENT_MODE value	Who uses it	Schema strategy
Dedicated (Single-Tenant)	dedicated	Self-hosted, enterprise on-prem	public schema — all data in one schema
SaaS (Multi-Tenant)	saas	Cloud-hosted, BluCypher managed	Per-tenant schema — each tenant gets tenant_{id}

---

Single-Tenant Architecture (Dedicated Mode)

How it works

In dedicated mode, the platform runs for a single customer. All data lives in the PostgreSQL public schema. No schema switching happens per request — the resolveTenant middleware builds a static TenantContext once at server startup and reuses it for every request.

DEPLOYMENT_MODE=dedicated
         │
         ▼
resolveTenant middleware (startup)
  → builds static TenantContext once from env vars:
      tenantId:    "dedicated-{DEDICATED_TENANT_SLUG}"
      tenantSlug:  "{DEDICATED_TENANT_SLUG}"
      tenantPlan:  "{DEDICATED_TENANT_PLAN}"
      schemaName:  "public"
      planLimits:  { requestsPerMinute: 2000, requestsPerDay: 200000,
                     maxUsers: 500, maxAgents: 100 }
  → req.tenantContext = dedicatedContext  (same object every request)
         │
         ▼
setTenantSchema middleware
  → detects req.tenantContext.schemaName === 'public'
  → SKIPS QueryRunner creation entirely (no search_path needed)
  → calls next() immediately
         │
         ▼
Route Handler
  → TypeORM uses AppDataSource connection directly
  → All queries run against the public schema
  → No per-request overhead from schema switching

Database schema layout (dedicated)

PostgreSQL instance
└── public (single schema, all tables here)
    ├── users
    ├── assets
    ├── vulnerabilities
    ├── findings
    ├── assessments
    ├── dashboard_widgets
    ├── roles / permissions
    ├── settings
    ├── agent_configs
    ├── scan_sessions
    ├── audit_logs
    └── ... (134 total entity files)

Configuration

DEPLOYMENT_MODE=dedicated
DEDICATED_TENANT_SLUG=your-company
DEDICATED_TENANT_PLAN=enterprise

Isolation model

• No inter-tenant isolation — single company owns all data
• admin and superadmin roles have full access to all records
• tenant_user_routing, tenant_entitlements, and tenant_memberships tables are not consulted at runtime
• Rate limits are enforced per the plan defaults in TenantContext.planLimits

---

Multi-Tenant Architecture (SaaS Mode)

How it works

In SaaS mode, each customer (tenant) gets a dedicated PostgreSQL schema. The schema name is resolved per-request from the tenantId claim in the JWT token. The resolution chain is: JWT → Redis cache → TLM API → local routing table fallback.

DEPLOYMENT_MODE=saas
         │
JWT contains tenantId (e.g., "cust_abc123")  ← set by authenticate() middleware
         │
         ▼
resolveTenant middleware
  → check Redis cache (tw:tenant:customer:{tenantId})
  │
  ├─ CACHE HIT → deserialize TenantContext
  │     → if status === 'suspended' → 403 Tenant account suspended
  │     → req.tenantContext = cachedContext
  │
  └─ CACHE MISS → call TLM API:
        GET /api/customers/{tenantId}/tenant-context
        headers: Bearer service-token  (or X-Vendor-Key fallback)
        timeout: 5 000 ms
        │
        ├─ 404 → 404 Tenant not found
        ├─ non-2xx → fallback to local tenant_user_routing table
        └─ 200 → build TenantContext from response:
              { tenantId, tenantSlug, tenantPlan,
                schemaName: data.schemaName,
                licenseJti, planLimits, status,
                allowedModules, maxUsers }
              → cache for tenantCacheTtl seconds (default 300s)
              → if status === 'suspended' → 403
              → req.tenantContext = resolvedContext
         │
         ▼
setTenantSchema middleware
  → call schemaManager.createTenantQueryRunner(schemaName)
      ├─ validates schemaName against /^[a-zA-Z_][a-zA-Z0-9_-]{0,62}$/
      ├─ dataSource.createQueryRunner()
      ├─ queryRunner.connect()
      └─ execute: SET search_path TO "tenant_abc123", public
  → execute: SELECT set_config('app.current_tenant_id', tenantId, false)
  → register cleanup on res.on('finish') + res.on('close'):
      cleanup: set_config('app.current_tenant_id', '', false)
               SET search_path TO public
               queryRunner.release()
  → tenantStorage.run({ entityManager: queryRunner.manager, tenantContext }, () => next())
         │
         ▼
Route Handler / Service Layer
  → getTenantAwareRepository() calls tenantStorage.getStore()
  → returns queryRunner.manager (scoped to tenant_abc123)
  → All TypeORM queries automatically resolve to tenant_abc123 schema
  → Completely isolated from other tenants
         │
         ▼
Response finish / connection close:
  → QueryRunner cleanup fires (idempotent, double-release protected)
  → app.current_tenant_id GUC cleared
  → search_path reset to public
  → QueryRunner released back to connection pool

Schema isolation diagram

Tables in public schema (cross-tenant)

These tables exist in the public schema and are readable regardless of the active tenant:

Table	Purpose
tenant_user_routing	Maps customer_id → schema_name for local fallback resolution
tenant_entitlements	Per-tenant plan, allowed modules, max users, plan limits
tenant_memberships	Tenant lifecycle status: active, suspended, deprovisioned

Tables in tenant schema (per-tenant isolated)

Every other table lives inside the tenant's own schema. No cross-tenant query is possible without explicitly switching schemas. Tables include (but are not limited to):

users, roles, permissions, assets, asset_groups, vulnerabilities, findings, assessments, scan_sessions, agent_configs, dashboard_widgets, report_templates, compliance_frameworks, audit_logs, settings, sla_policy_config, vfp_policy_config, proxy_config, ai_providers, ai_prompt_templates, sensitive_data_patterns, webhook_receivers, and more.

Total entity files: 134

---

Request-Level Isolation

Every authenticated API request goes through this isolation chain:

Defense in depth

ThreatWeaver applies three independent isolation mechanisms in SaaS mode:

1. PostgreSQL search_path — Primary isolation. SET search_path TO "tenant_{id}", public ensures TypeORM cannot accidentally reference another tenant's tables. All unqualified table names resolve to the tenant schema.

2. Row-Level Security GUC — SELECT set_config('app.current_tenant_id', tenantId, false) sets a session-level GUC. PostgreSQL RLS policies can reference current_setting('app.current_tenant_id') for an additional, independent enforcement layer. The is_local=false flag means it persists for the lifetime of the connection — it is explicitly cleared in releaseTenantQueryRunner before the connection returns to the pool.

3. AsyncLocalStorage context — The tenant's EntityManager is bound to the request's async context via Node.js AsyncLocalStorage. Service code calls getTenantAwareRepository(Entity) which retrieves the tenant-scoped manager without needing req passed down the call stack. This prevents accidental use of the default AppDataSource connection.

---

Tenant Provisioning Flow

When a new tenant is created in SaaS mode, the following sequence runs:

The seed process is idempotent — it is safe to run seedTenantDefaults again on a schema that already has partial data. Each seed step checks for existence before inserting.

Multi-tenant module files: index.ts, rls-setup.ts, schema-manager.ts, tenant-context.ts, tenant-local-storage.ts, tenant-repository.ts, tenant-seed.ts

---

Switching Between Modes

To switch from dedicated to SaaS mode:

1. Set DEPLOYMENT_MODE=saas in environment variables
2. Run npm run migrate:dev — this creates tenant_user_routing, tenant_entitlements, and tenant_memberships tables in the public schema
3. Provision the first tenant via TLM
4. Existing data in the public schema does not auto-migrate to a tenant schema — a manual schema move is required

To switch from SaaS back to dedicated:

1. Set DEPLOYMENT_MODE=dedicated along with DEDICATED_TENANT_SLUG and DEDICATED_TENANT_PLAN
2. Ensure data exists in public schema (run migration scripts)
3. Redis cache entries for tenant contexts will be ignored — no cleanup needed

---

Security Considerations

Concern	Mitigation
Schema name injection	SchemaManager.createTenantQueryRunner validates against /^[a-zA-Z_][a-zA-Z0-9_-]{0,62}$/ before any query
TenantContext source	schemaName comes from TLM (server-side, validated at provisioning) — never from user input
Suspended tenant access	Blocked with 403 Tenant account suspended immediately after JWT verification, before schema is set
Deprovisioned tenant	410 Gone — blocked in local DB fallback path
GUC context bleed	app.current_tenant_id explicitly cleared in releaseTenantQueryRunner using set_config('app.current_tenant_id', '', false) before connection returns to pool
Connection pool pollution	SET search_path TO public executed in cleanup before pool return — stale search_path cannot carry into a future request
Double release	released flag in closure prevents double-release on both res.finish and res.close events
Non-tenant routes	Routes without a JWT (login, health check, internal) have req.tenantContext = undefined — setTenantSchema skips entirely

---

Related Documentation

• Deployment Models — single vs multi-tenant deployment options
• Auth Deep Dive — JWT structure and tenant claims
• Request Flows — full middleware chain walkthrough
• Environment Variables — DEPLOYMENT_MODE, DEDICATED_TENANT_SLUG, TLM_BASE_URL
• Multi-Tenant Architecture Diagram — visual diagram