Secrets Management & Encryption

Supabase Vault for Tenant Secrets

All tenant secrets are stored in Supabase Vault, a Postgres extension that encrypts secrets at the database level. Secrets are scoped per workspace and never stored in public schema tables.

Secret Kinds

Each workspace can store the following secret types in Vault:

Secret Kind	Purpose
`meta-access-token`	Meta (WhatsApp Business API) access token for sending messages
`webhook-signing-secret`	Meta webhook payload signing secret for request verification
`meta-verify-token`	Meta webhook verification token
`openai-api-key`	OpenAI API key for AI draft generation
`anthropic-api-key`	Anthropic API key for Claude-based AI generation
`openrouter-api-key`	OpenRouter API key for multi-model AI routing

Vault Access Pattern

Secrets are read from Vault only at the point of use, scoped to the requesting workspace:

async function getWorkspaceSecret(
  workspaceId: string,
  kind: SecretKind
): Promise<string> {
  const { data, error } = await supabase.rpc('vault_read_secret', {
    p_workspace_id: workspaceId,
    p_kind: kind,
  });

  if (error || !data) throw new SecretNotFoundError(kind);
  return data.secret_value;
}

Secrets from workspace A are structurally inaccessible to workspace B — the vault read function is parameterized by workspace ID, which is always derived from the authenticated session.

No Environment Variable Fallback in Production

Environment variable fallbacks for secrets are gated to non-production environments only:

async function resolveMetaToken(workspaceId: string): Promise<string> {
  // Always try Vault first
  const vaultSecret = await getWorkspaceSecret(workspaceId, 'meta-access-token')
    .catch(() => null);

  if (vaultSecret) return vaultSecret;

  // Fallback only permitted outside production
  if (process.env.NODE_ENV !== 'production' && process.env.META_ACCESS_TOKEN) {
    return process.env.META_ACCESS_TOKEN;
  }

  throw new ConfigurationError('No Meta access token configured for this workspace');
}

This ensures that a misconfigured production deployment will fail loudly rather than silently fall back to a shared credential.

In production, if Vault returns no secret for a workspace, the operation fails with an error. There is no global fallback credential that could inadvertently be used by multiple tenants.

API Key Storage

API keys are never stored in plaintext. The storage scheme:

Generation: A cryptographically random token is generated
Hashing: The token is hashed with SHA-256 before database storage
Prefix: The first 8 characters of the raw token are stored separately for display identification
Display: The full raw token is shown to the user exactly once at creation time

import { createHash, randomBytes } from 'crypto';

function generateApiKey() {
  const raw = randomBytes(32).toString('hex'); // 64-char hex string
  const hash = createHash('sha256').update(raw).digest('hex');
  const prefix = raw.slice(0, 8);
  return { raw, hash, prefix };
}

Timing-Safe Validation

Key validation uses crypto.timingSafeEqual to prevent timing oracle attacks:

import { timingSafeEqual, createHash } from 'crypto';

function isValidApiKey(providedRaw: string, storedHash: string): boolean {
  const providedHash = createHash('sha256').update(providedRaw).digest('hex');
  const a = Buffer.from(providedHash, 'hex');
  const b = Buffer.from(storedHash, 'hex');

  // Length check must not short-circuit before timingSafeEqual
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Security Headers

All HTTP responses from the Switchbord application include the following security headers:

Content Security Policy

Content-Security-Policy: default-src 'self';
  script-src 'self' 'nonce-{nonce}';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' https://*.supabase.co wss://*.supabase.co;
  frame-ancestors 'none';

HTTP Strict Transport Security

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

The preload directive submits the domain to browser HSTS preload lists, ensuring HTTPS-only connections even on first visit.

Additional Headers

Header	Value	Purpose
`X-Frame-Options`	`DENY`	Prevents clickjacking attacks
`X-Content-Type-Options`	`nosniff`	Prevents MIME-type sniffing
`Referrer-Policy`	`strict-origin-when-cross-origin`	Controls referrer information
`Permissions-Policy`	`camera=(), microphone=(), geolocation=()`	Disables unnecessary browser APIs

CORS Policy

CORS is restricted to an explicit allowlist of known origins:

const ALLOWED_ORIGINS = [
  'https://app.switchbord.ai',
  ...(process.env.NODE_ENV !== 'production' ? ['http://localhost:3000'] : []),
];

function corsMiddleware(req: Request): Response | null {
  const origin = req.headers.get('Origin');
  if (origin && !ALLOWED_ORIGINS.includes(origin)) {
    return new Response('Forbidden', { status: 403 });
  }
  return null; // proceed
}

CORS restrictions prevent browser-based cross-origin requests from unauthorized domains. They do not prevent direct API calls (e.g., from curl or server-to-server). API authentication is the primary access control.

Encryption at Rest

Supabase provides transparent disk encryption for all data stored in its managed PostgreSQL instances. This covers the contacts, messages, workspace_members, audit_logs, and all other tables. Planned enhancement (BORD-171): Column-level encryption for PII fields (phone numbers, names, message bodies) using Supabase’s pgsodium extension. This would provide application-level encryption in addition to disk-level encryption, protecting against scenarios where database credentials are compromised.

TLS in Transit

All connections to and from Switchbord components are encrypted using TLS:

Vercel (web/API): TLS 1.2+ enforced by Vercel’s edge network
Supabase: TLS required for all database and API connections
Railway (worker): TLS enforced for all outbound HTTP calls
Meta Cloud API: All WhatsApp API calls made over HTTPS
AI providers: All API calls to OpenAI, Anthropic, OpenRouter made over HTTPS

Open Redirect Protection

The auth callback endpoint validates the next redirect parameter to prevent open redirect attacks:

function isSafeRedirect(url: string): boolean {
  // Allow relative paths
  if (url.startsWith('/') && !url.startsWith('//')) return true;

  // Allow known origins
  const allowedOrigins = ['https://app.switchbord.ai'];
  try {
    const parsed = new URL(url);
    return allowedOrigins.some(origin => parsed.origin === origin);
  } catch {
    return false;
  }
}

// In auth callback
const next = searchParams.get('next') ?? '/';
const redirectTo = isSafeRedirect(next) ? next : '/';

Input Validation

All key API request bodies are validated with Zod schemas before processing:

const CreateContactSchema = z.object({
  phoneNumber: z.string().regex(/^\+[1-9]\d{1,14}$/),
  name: z.string().min(1).max(255).optional(),
  customFields: z.record(z.string()).optional(),
});

export async function POST(req: Request) {
  const body = await req.json();
  const parsed = CreateContactSchema.safeParse(body);

  if (!parsed.success) {
    return Response.json({ error: 'Invalid request' }, { status: 400 });
    // Zod errors are logged server-side but not returned to clients
  }
  // ...
}

Error responses are sanitized — raw Supabase or database errors are never returned to clients.

Compliance Mapping

Standard	Control	Implementation
ISO 27001	A.10.1 — Cryptographic controls	SHA-256 API key hashing, TLS in transit, Vault encryption
ISO 27001	A.13.1 — Network security management	CORS allowlist, security headers
ISO 27001	A.13.2 — Information transfer	TLS enforced for all connections
ISO 27001	A.14.2 — Security in development	Input validation (Zod), output sanitization
GDPR	Art.32 — Security of processing	Encryption at rest and in transit, access controls
HIPAA	§164.312(a)(2)(iv) — Encryption and decryption	TLS in transit, Vault encryption at rest
HIPAA	§164.312(e)(2)(ii) — Encryption in transit	TLS enforced on all external connections
SOC 2	CC6.1 — Logical access controls	API key hashing, timing-safe comparison
SOC 2	CC6.7 — Data in transit and at rest	TLS + disk encryption + planned column-level encryption

For the full compliance control mapping, see the Compliance Matrix.

Get Started

Features

WhatsApp

Guides

Contributing

Platform

Operations

Security & Compliance

Secrets Management & Encryption

Supabase Vault for Tenant Secrets

Secret Kinds

Vault Access Pattern

No Environment Variable Fallback in Production

API Key Storage

Timing-Safe Validation

Security Headers

Content Security Policy

HTTP Strict Transport Security

Additional Headers

CORS Policy

Encryption at Rest

TLS in Transit

Open Redirect Protection

Input Validation

Compliance Mapping

​Supabase Vault for Tenant Secrets

​Secret Kinds

​Vault Access Pattern

​No Environment Variable Fallback in Production

​API Key Storage

​Timing-Safe Validation

​Security Headers

​Content Security Policy

​HTTP Strict Transport Security

​Additional Headers

​CORS Policy

​Encryption at Rest

​TLS in Transit

​Open Redirect Protection

​Input Validation

​Compliance Mapping

Supabase Vault for Tenant Secrets

Secret Kinds

Vault Access Pattern

No Environment Variable Fallback in Production

API Key Storage

Timing-Safe Validation

Security Headers

Content Security Policy

HTTP Strict Transport Security

Additional Headers

CORS Policy

Encryption at Rest

TLS in Transit

Open Redirect Protection

Input Validation

Compliance Mapping