SuperAdmin Manual

1. Introduction & Role Overview

The SuperAdmin is the highest-privilege role in eTrustPortal. There are two SuperAdmin tiers:

Owner — the primary platform operator. Full access to all tabs including Admin Users management, Platform Settings, and all organization data. Typically the system administrator or CTO of the entity running the eTrustPortal instance.

SuperAdmin — elevated operational access. Can manage organizations and view platform settings but cannot manage other SuperAdmin users. Suitable for senior operations staff who need to support tenants without full platform control.

As a SuperAdmin you are responsible for: provisioning and managing tenant organizations (accounting firms), managing SuperAdmin user accounts, configuring platform-wide settings (themes, AI keys, email), monitoring system health, and ensuring the security and integrity of all tenant data.

2. Accessing the SuperAdmin Portal

2.1 Login

Navigate to /superadmin.html. Enter your email and password, then your TOTP multi-factor authentication code. SuperAdmin MFA is mandatory and cannot be disabled. If you lose access to your authenticator app, reset MFA via direct database intervention (see Section 14.3).

2.2 First-Time Setup

On a fresh installation, the first SuperAdmin account is seeded from SA_EMAIL and SA_PASS in your .env file. After first login, immediately:

1. Change the seeded password to something strong and unique
2. Set up MFA (you will be prompted automatically)
3. Remove or rotate the SA_PASS environment variable — it is no longer needed

2.3 Session Behaviour

SuperAdmin sessions expire after 8 hours. Sessions are bound to the originating IP address as an additional security measure. Logging in from a different IP will require re-authentication.

2.4 Role-Based Tab Visibility

The Admin Users tab is only visible to Owner-role SuperAdmins. Standard SuperAdmin users see Organizations, Platform Settings, and My Account only.

3. Organizations Tab

Your primary workspace for managing tenant accounts (accounting firms).

3.1 Organizations List

Table columns: Organization Name, Slug (URL identifier), Plan, Status (Active/Suspended), Created Date, and Actions. Real-time search filter by name.

3.2 Creating a New Organization

Click + New Organization. Required fields:

• Organization Name — display name of the accounting firm (e.g., "Smith & Jones Accountants")
• Slug — unique URL-safe identifier (e.g., "smith-jones"). Lowercase, alphanumeric, hyphens allowed. Cannot be changed after creation.
• Admin Email — the first administrator's email; a welcome email is sent with a set-password link
• Admin Name — display name for the first admin user
• Plan — Free, Starter, Professional, or Enterprise

On save the system creates the tenant record, creates the first admin account, sends the welcome email, and provisions the tenant's Vault transit key for document encryption.

3.3 Viewing Organization Details

Overview: name, slug, plan, status, storage usage, client/document/user counts. Users: all staff/admin users with name, email, role, last login, MFA status. Documents: 10 most recent uploads. Activity: recent audit log entries. This view is read-only.

3.4 Editing an Organization

Click ✏️ Edit to change Organization Name, Plan, Status (Active/Suspended), or internal Notes. The slug cannot be changed after creation.

3.5 Suspending an Organization

Setting status to Suspended immediately prevents all users of that tenant from logging in and invalidates existing sessions. Data is preserved intact. Use for non-payment, policy violations, or security investigations. Reactivate by setting status back to Active.

3.6 Deleting an Organization

3.7 No Impersonation by Design

SuperAdmins cannot log in as tenant admins — there is no impersonation feature, protecting tenant privacy. To investigate a tenant issue, use the Organization detail view's read-only audit log and document sub-tables.

4. Admin Users Tab

Visible to Owner-role SuperAdmins only. Manages SuperAdmin-level user accounts.

4.1 Inviting a New SuperAdmin

Click + Invite Admin. Enter the invitee's email and select their role. Owner — full platform access; use sparingly (ideally only one or two Owner accounts). SuperAdmin — operational access only, cannot manage other SuperAdmin users. The invitee receives an email to set their password and configure MFA.

4.2 Resetting MFA for a SuperAdmin

Click Reset MFA on a user's account to clear their MFA secret. On their next login they will be forced through the MFA setup flow again. Use this when a SuperAdmin has lost their authenticator app.

4.3 Deactivating / Deleting

Deactivate — immediately revokes access; account remains for audit trail purposes; reactivate by clicking Activate. Delete — permanently removes the account; audit trail entries remain intact. You cannot delete your own account.

5. Platform Settings Tab

Controls global configuration for the entire eTrustPortal instance.

5.1 AI Configuration

Enter your OpenAI API Key to enable all 22 AI features across all tenant portals. The key is stored encrypted and shown as •••••••• in the UI. If blank, all AI features are gracefully disabled — AI buttons appear but show "AI not configured" when used. See Section 7 for full AI setup details.

5.2 Email Configuration

SMTP Host (e.g., smtp.sendgrid.net), SMTP Port (587 for STARTTLS, 465 for SSL), SMTP Username, SMTP Password (stored encrypted), From Address (must be a verified sender), From Name. Use Send Test Email after saving to confirm delivery.

5.3 Theme Management

Six built-in themes: Dark Navy (default), Light, Ocean Blue, Forest Green, Warm Slate, and Purple Night. Set the Default Theme for new tenants. Create a Custom Theme via JSON colour map with fields: bg_base, bg_surface, bg_elevated, border, text_primary, text_secondary, text_muted, sidebar_bg. A live preview is shown before saving.

5.4 Feature Flags

Toggle platform-wide features: E-Signatures (Internal), DocuSign Integration, AdobeSign Integration, Accounting Integrations (QuickBooks/Xero/Sage), AI Features (master on/off), and Client Self-Registration.

5.5 Storage Quotas by Plan

6. My Account Tab

Profile: Update display name and email (changing email changes your login credential). Password Change: Enter current password then new password twice. MFA Management: Click Reset MFA to reconfigure your authenticator — you must enter your current MFA code to confirm. Activity Log: Last 50 login events and actions: IP addresses, timestamps, action types.

7. AI Configuration

7.1 Obtaining an OpenAI API Key

1. Sign up or log in at platform.openai.com
2. Navigate to API Keys in the left sidebar
3. Click + Create new secret key, name it (e.g., "eTrustPortal Production")
4. Copy the key immediately — it is only shown once
5. Set up billing and ensure your payment method and credit balance are configured

7.2 Model Selection

The default model is gpt-4o-mini, providing an excellent balance of capability and cost. Configured in server/services/ai.js — edit the MODEL constant to change it.

7.3 Cost Estimates (gpt-4o-mini)

Monitor usage at platform.openai.com/usage. Set a monthly spend limit in OpenAI billing settings as a safety net.

8. Security Architecture

8.1 Authentication Stack

Password Hashing: bcrypt with cost factor 12. Session Tokens: 32-byte cryptographically random tokens stored server-side in the sessions table; transmitted via HTTP-only, Secure, SameSite=Strict cookies. MFA: TOTP per RFC 6238 with 32-byte base32 secrets. JWT: Not used — traditional server-side sessions for security.

8.2 Multi-Tenancy Isolation

Every API endpoint is protected by requireTenant middleware, verifying the authenticated user belongs to the tenant being accessed. The tenant ID is stored server-side in the session (never in a cookie or URL parameter), making it impossible to spoof.

8.3 Document Encryption (Two-Layer)

Layer 1 — DEK: Each document is encrypted with a unique AES-256-GCM key. Encrypted ciphertext and IV are stored in the database/file system. Layer 2 — KEK: The DEK is encrypted ("wrapped") using HashiCorp Vault's Transit engine. The wrapped DEK is stored alongside the document — the plaintext DEK never exists in persistent storage.

Decryption flow: Server sends wrapped DEK to Vault → Vault returns plaintext DEK → server decrypts document → streams plaintext to authenticated user → immediately discards DEK from memory. Even if the database is compromised, documents cannot be decrypted without Vault access.

8.4 Required Vault Environment Variables

VAULT_ADDR=https://your-vault-instance:8200
VAULT_TOKEN=your-vault-policy-token
VAULT_TRANSIT_KEY=etrustportal-doc-key

The Vault token must have a policy allowing transit/encrypt/* and transit/decrypt/* on the configured key path. In production use a renewable token with short TTL and Vault Agent for automatic renewal.

8.5 RBAC Summary

9. Database & Schema Management

9.1 Initial Setup

psql -U postgres -d etrustportal -f server/schema.pg.sql

The schema uses CREATE TABLE IF NOT EXISTS and ALTER TABLE ... ADD COLUMN IF NOT EXISTS throughout, making it safe to re-run against an existing database for incremental migrations.

9.2 Environment Variables

DB_HOST=localhost
DB_PORT=5432
DB_NAME=etrustportal
DB_USER=etrustportal_app
DB_PASS=your-secure-password

The database user should have minimum required privileges: SELECT, INSERT, UPDATE, DELETE on application tables. It should not have CREATE, DROP, or superuser privileges.

9.3 Key Tables

9.4 Schema Migrations

Always write idempotent SQL using IF NOT EXISTS / IF EXISTS patterns:

ALTER TABLE tenants ADD COLUMN IF NOT EXISTS new_feature_flag BOOLEAN DEFAULT FALSE;
CREATE INDEX IF NOT EXISTS idx_documents_tenant ON documents(tenant_id);

9.5 Audit Log Maintenance

The audit_log table grows unboundedly. Implement a retention policy — export records to CSV or a data warehouse first (regulatory requirements typically mandate 6–7 years), then archive:

-- Archive logs older than 2 years after exporting
DELETE FROM audit_log WHERE created_at < NOW() - INTERVAL '2 years';

10. Vault & Encryption Management

10.1 Vault in Development

vault server -dev -dev-root-token-id=dev-token
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=dev-token
vault secrets enable transit
vault write -f transit/keys/etrustportal-doc-key

10.2 Vault in Production Requirements

• TLS enabled — VAULT_ADDR must use https://
• Auto-unseal configured (AWS KMS, GCP Cloud KMS, or Azure Key Vault)
• Audit logging enabled to a persistent backend
• Token TTL set short (e.g., 24h) with automatic renewal via Vault Agent
• Transit key set to exportable=false — keys cannot be extracted from Vault
• Separate policy for eTrustPortal with minimum required capabilities

10.3 Key Rotation

vault write -f transit/keys/etrustportal-doc-key/rotate

After rotation, new encryptions use the new key version. Existing documents can still be decrypted as Vault retains all previous key versions. Rotate annually at minimum, or immediately after a suspected compromise.

10.4 If Vault is Unavailable

11. Monitoring & Operations

11.1 Application Logs

The Node.js server writes structured logs to stdout. Key log prefixes to monitor:

• [AUTH] — login successes and failures; watch for brute force patterns
• [VAULT] — encryption/decryption operations and errors
• [AI] — AI API calls, latency, and errors
• [ERROR] — uncaught exceptions and 500 responses
• [EMAIL] — email send successes and failures

11.2 Health Check Endpoint

GET /api/health — use in load balancer health checks and uptime monitoring:

{
  "status": "ok",
  "db": "ok",
  "uptime": 123456,
  "ts": "2025-01-01T00:00:00.000Z"
}

11.3 Database Monitoring

Monitor: connection pool utilisation (default pool: 10), query execution time (flag queries over 1 second), table sizes (audit_log and documents grow continuously), index hit rates (should be >99%), replication lag (if using read replicas).

11.4 Storage Monitoring

Set up alerts when storage utilisation exceeds 70% and 90% of available disk. The storage path is configured via the STORAGE_PATH environment variable. Documents are stored as encrypted binary files.

12. Scaling & Performance

12.1 Horizontal Scaling

eTrustPortal is stateless at the application layer (sessions stored in PostgreSQL, files in shared storage). To scale horizontally:

1. Run multiple Node.js instances behind a load balancer (FortiGate, nginx, etc.)
2. All instances share the same PostgreSQL database
3. All instances share the same file storage volume (NFS, S3, or similar)
4. All instances can reach the same Vault instance
5. Use DB-backed sessions (default) — robust across instances without sticky sessions

12.2 Database Scaling

For high-load deployments: use PostgreSQL with read replicas for reporting queries, add PgBouncer connection pooling between app and database, index the most-queried columns (tenant_id, user_id, created_at), consider partitioning the audit_log table by month.

12.3 AI Scaling

OpenAI API calls are made synchronously. For large deployments: move AI calls to a background job queue (Bull/BullMQ with Redis), return a job ID immediately and poll for results, implement per-tenant rate limiting, cache common AI responses (e.g., document summaries).

12.4 Document Storage Scaling

For very high document volumes, migrate from local disk to object storage (AWS S3, Google Cloud Storage, Azure Blob Storage, or MinIO). The document storage layer is abstracted in server/services/document-processor.js.

13. Backup & Disaster Recovery

13.1 What Must Be Backed Up

1. PostgreSQL database — all application data
2. Document storage — encrypted document files
3. Vault data — transit encryption keys (most critical — without these, documents cannot be decrypted even with the database and files)
4. Environment variables / secrets — your .env file or secrets manager contents

13.2 Database Backup

# Daily automated backup
pg_dump -U etrustportal_app -d etrustportal | gzip > /backups/db/etrustportal_$(date +%Y%m%d).sql.gz

# Verify backup
zcat /backups/db/etrustportal_$(date +%Y%m%d).sql.gz | head -20

Retain daily backups for 30 days, weekly for 12 weeks, monthly for 7 years (to meet accounting record-keeping requirements).

13.3 Vault Backup

vault operator raft snapshot save /backups/vault/vault_$(date +%Y%m%d).snap

Vault snapshots must be taken at least daily. Without a valid Vault backup, you cannot decrypt any documents even with the database restored.

13.4 Recovery Procedure

1. Provision new server infrastructure
2. Restore PostgreSQL: zcat backup.sql.gz | psql -U etrustportal_app -d etrustportal
3. Restore Vault: vault operator raft snapshot restore vault.snap
4. Restore document storage files to configured STORAGE_PATH
5. Restore .env configuration
6. Start application: npm start
7. Verify health: curl https://your-domain.com/api/health
8. Test document download end-to-end to confirm decryption works

Target RTO: 2 hours with prepared runbooks. Target RPO: 24 hours with daily backups; 1 hour with continuous WAL archiving.

14. Troubleshooting

14.1 Organisation Cannot Log In

Check organization status is Active (not Suspended) in the Organizations tab. If Active but login still fails, use the Organization detail view to verify the user exists and their last login date. Advise admin to reset password via Forgot Password.

14.2 Document Upload/Download Failing

500 errors on document operations usually indicate Vault connectivity issues. Verify Vault is running: curl $VAULT_ADDR/v1/sys/health. Check token has not expired: vault token lookup. If expired, generate a new token, update the environment variable, and restart the application.

14.3 MFA Recovery

If a SuperAdmin has lost access to their authenticator app, direct database intervention is required:

-- Find the user
SELECT id, email, mfa_secret FROM users WHERE email = 'admin@example.com';

-- Clear MFA secret (user will set up new MFA on next login)
UPDATE users SET mfa_secret = NULL, mfa_enabled = FALSE WHERE email = 'admin@example.com';

Only do this after verifying the user's identity through a secure out-of-band channel.

14.4 Email Not Sending

1. Platform Settings → Email Configuration — verify all SMTP fields
2. Click Send Test Email — check SuperAdmin mailbox and spam
3. Check application logs for [EMAIL] SMTP errors
4. Verify SMTP provider's dashboard for send activity and bounces
5. Confirm the FROM address is verified with your email provider

14.5 AI Features Not Working

Check API key is present in Platform Settings → AI Configuration. Log into platform.openai.com and verify the key is active with positive credit balance. Check logs for [AI] errors: 429 (rate limit), 401 (invalid key), 500 (OpenAI outage). Test the key: curl https://api.openai.com/v1/models -H "Authorization: Bearer YOUR_KEY"

14.6 Platform is Slow

1. GET /api/health — check all services show connected
2. Database — look for slow queries (log_min_duration_statement = 1000)
3. Server resources — CPU, memory, disk I/O
4. Vault response time — Vault adds latency to every document operation
5. OpenAI latency — AI features can add 1–5 seconds per request
6. Consider horizontal scaling (Section 12.1) if single-server limits are reached

14.7 Recovering a Deleted Organization

Deleted organizations cannot be recovered within the application. If you have a recent database backup: restore to a temporary database, export the organization's data, re-create manually or via SQL import, then have users reset their passwords. This is why typing the slug is required before deletion.

15. SuperAdmin Checklist

15.1 Initial Deployment

• PostgreSQL instance running and accessible
• Database created and schema applied (schema.pg.sql)
• HashiCorp Vault running and transit engine enabled
• Transit key created for document encryption
• All required environment variables set (see README.md)
• Application started: npm start
• Health check returns all green: GET /api/health
• First SuperAdmin account accessible (using seeded SA_EMAIL/SA_PASS)
• Default password changed and MFA configured
• SA_PASS removed from environment
• SMTP configuration set and test email received
• OpenAI API key entered (if AI features required)
• SSL/TLS certificate installed on web server / load balancer
• Automated database backups scheduled
• Automated Vault snapshot backups scheduled
• Health check monitoring and uptime alerting configured
• Log aggregation configured

15.2 New Tenant Onboarding

• Organization created with correct name and slug
• Correct plan assigned
• First admin account created — invite email sent
• Admin confirmed receipt and set password
• Admin completed MFA setup
• Admin confirmed portal access is working
• Admin briefed on Settings → Integrations
• Admin given a copy of the Administrator Manual

15.3 Monthly Operations

• Review audit log for anomalous activity across all tenants
• Check storage utilisation per tenant
• Review OpenAI API usage and costs
• Verify all tenants' subscription plans are current
• Test backup restoration (restore to test environment quarterly)
• Review Vault token expiry and renew if needed
• Review SuperAdmin user list — remove inactive accounts
• Apply any pending OS or Node.js security patches