Skip to main content

Multi-Tenant Cloud Operator Guide

Safely operate nSelf Cloud with tenant isolation, monitoring, and abuse handling

This guide covers operating nSelf Cloud as a multi-tenant SaaS platform. nSelf ships two distinct and mutually exclusive isolation mechanisms — confusing them causes data leaks across paying customers.

Isolation Models

Convention A: Multi-App Within One Deploy

source_account_id TEXT NOT NULL DEFAULT 'primary' separates independent consumer apps (Unity, Veterans, Flock) within a single nSelf stack.

Convention B: Cloud Multi-Tenancy (This Guide)

tenant_id UUID separates paying Cloud customers. This is your operator concern.

The Wall: Never use source_account_id for Cloud customers. Never use tenant_id for multi-app. Data leaks occur at the boundary.

1. Tenant Isolation Model

RLS + Row Filters (Hard Rule)

Every np_cloud_* and cost-tracking table uses tenant_id UUID with:

CREATE POLICY tenant_scoped ON np_cloud_instances
  FOR SELECT
  USING (tenant_id = current_setting('app.tenant_id', true)::uuid);

Hasura enforces the same boundary via metadata permission:

{"tenant_id": {"_eq": "X-Hasura-Tenant-Id"}}

Check before deploying: nself doctor --deep runs check PERM-RLS-01. Zero violations = safe.

2. Safely Isolating Tenants

On Signup

nself tenant create \
  --name "acme-corp" \
  --email "billing@acme.com" \
  --plan "cloud-standard"

Returns: tenant_id UUID. Store this in np_cloud_tenants.id.

Per-Request Header

Every API call from the tenant sets:

X-Hasura-Tenant-Id: <tenant_id>

Hasura’s permission system blocks cross-tenant queries at the GraphQL layer. RLS blocks at the SQL layer. Defense in depth.

Audit Logging

Every nself_audit_log entry includes tenant_id for post-incident forensics.

3. Cross-Tenant Resource Monitoring

Metering Tables

  • np_cloud_billing_events — append-only ledger (immutable)
  • np_ai_usage_rollup — per-tenant AI token counts
  • np_claw_cost_events — per-tenant Claw usage metrics

Query by tenant:

SELECT SUM(tokens_used) FROM np_ai_usage_rollup
  WHERE tenant_id = $1 AND created_at > now() - interval '1 month';

Dashboard Views

cloud.nself.org shows each tenant:

  • Current month spend
  • Usage by plugin (ai, mux, voice, etc.)
  • Instance uptime / resource utilization
  • Projected overage fees

4. Abuse Handling

Rate Limit Enforcement

Tenant-scoped limits via Redis:

tenant:<id>:api_calls:5m → max 10,000 reqs/5min
tenant:<id>:api_calls:1h → max 100,000 reqs/hour

Exceeded → HTTP 429 + email alert to ops.

Suspend Flow

  1. Alert triggered — anomaly detection on token usage (10x+ normal)
  2. Investigation — review audit log + confirm abuse (not legitimate spike)
  3. Suspend — set np_cloud_tenants.status = 'suspended'
  4. Notify tenant — email with reason + remediation path
  5. Unblock after fix — tenant submits appeal or usage normalizes

Terminate Flow

  • Involuntary (repeated abuse): status = 'terminated' + archive all instances + wipe data after 30d grace period
  • Voluntary (user cancellation): status = 'canceled' + keep backups 90d

5. Tenant Credential Rotation

API Keys

nself cloud rotation --tenant acme-corp --type api-key

Returns new key, invalidates old (grace period 24h for client rotation).

Database Passwords

nself cloud rotation --tenant acme-corp --type db-password

Updates np_cloud_instances.db_password, tenant receives new DATABASE_URL via email.

SSL Certificates

Automatic renewal via Let’s Encrypt. Manual force-renew:

nself cloud rotation --tenant acme-corp --type ssl-cert

6. Audit Log Review

Per-Tenant Audit Trail

SELECT action, actor, created_at FROM np_auditlog_events
  WHERE tenant_id = $1
  ORDER BY created_at DESC
  LIMIT 100;

Actions logged: instance create/delete, plugin install, credential rotation, password change, billing method update.

Forensics Workflow

Post-incident (data leak suspicion):

  1. Query audit log for tenant + time window
  2. Cross-ref with RLS policies and Hasura permissions at that time
  3. Verify no policy gaps existed
  4. File PCI to nSelf codebase: security finding + patch recommendation

Cross-References

  • Architecture: Multi-Tenant Conventions Wall — decision tree + data leak prevention
  • CLI Reference: nself tenant --help and nself cloud --help
  • Database: np_cloud_tenants, np_cloud_instances, np_cloud_billing_events in web/backend migrations
  • RLS Checks: nself doctor --deep — PERM-RLS-01 validates Hasura row filters