Security Model

This page documents the layered defenses that protect the workspace and the data behind it. For the live permission grid see Workspace → RBAC; for the audit log catalog see Audit Log.

Defense in depth#

┌─────────────────────────────────────────────────────────────────┐
│  Edge:  Clerk session check + email domain allowlist            │  apps/workspace/proxy.ts
├─────────────────────────────────────────────────────────────────┤
│  Layout: re-check allowlist, fetch RBAC roles, hide UI          │  app/(workspace)/layout.tsx
├─────────────────────────────────────────────────────────────────┤
│  Route handler: checkRole(<permission>) before any side-effect  │  app/api/**/route.ts
├─────────────────────────────────────────────────────────────────┤
│  Zod schemas: validate body/query before touching the DB        │  lib/utils/validation
├─────────────────────────────────────────────────────────────────┤
│  Audit log: every mutation writes to MongoDB `audit_logs`       │  lib/security/audit
└─────────────────────────────────────────────────────────────────┘

If any layer fails open, the next one still catches it.

Authentication#

• Clerk is the single identity provider. Sessions are HTTP-only cookies issued by Clerk.
• For SSO across matters.ai ↔ workspace.matters.ai, the Clerk session cookie's Domain must be set to .matters.ai in the Clerk dashboard.
• 2FA is supported via Clerk; enforcement for sensitive operations is opt-in per route.

Email domain allowlist#

@matters/auth's isAllowedEmail() (canonical source: packages/auth/src/email-allowlist.ts) is the primary gate on workspace access. Only addresses ending in one of ALLOWED_EMAIL_DOMAINS may access protected routes — even with a valid Clerk session.

Adding a domain is a security review item: it grants every Clerk user at that domain access to internal data. Never broaden the list without a written reason and a sign-off.

RBAC#

org:super_admin is in PROTECTED_ROLES and cannot be combined with other roles. Roles live in Clerk's publicMetadata.role (the primary role) plus publicMetadata.additionalRoles (an array of extra roles) — there is no publicMetadata.roles field (Clerk Organisations replaces this scheme once migrated).

Cross-origin policy (CORS + Origin enforcement)#

The Matters surface is a federation of seven hosts, all under matters.ai. Public APIs at the root Next.js app (/api/demo-form, /api/whitepapers/submit, /api/datasheets/submit) accept calls from exactly that set — never from arbitrary origins.

The canonical list is PROD_ORIGINS in lib/cors.ts. In non-production, http://localhost:* and http://127.0.0.1:* are also accepted (regex-matched). For one-off preview/staging origins, set NEXT_PUBLIC_EXTRA_ALLOWED_ORIGIN in the Vercel project.

Two-layer enforcement#

CORS is browser-only — curl ignores it entirely. So we pair the Access-Control-Allow-Origin header with explicit server-side origin enforcement:

// lib/cors.ts
export function requireMattersOrigin(request: NextRequest): NextResponse | null {
  const origin = request.headers.get("origin");
  const referer = request.headers.get("referer");
  if (origin)  return isAllowedOrigin(origin) ? null : forbidden();
  if (referer) return isAllowedOrigin(new URL(referer).origin) ? null : forbidden();
  return forbidden();  // no Origin and no Referer → reject
}

Public mutation routes call this first:

export async function POST(req: NextRequest) {
  const blocked = requireMattersOrigin(req);
  if (blocked) return blocked;
  // … handler
}

A failed origin check returns 403 Forbidden with body { "error": "Forbidden", "reason": "cross_origin_blocked" }. Receivers should treat this as a hard 403, not a retry.

Same-origin gotcha#

Even same-origin requests must pass the allow-list — because requireMattersOrigin checks the calling origin string, not whether origin equals host. So adding a new Matters surface without adding it to PROD_ORIGINS will silently break its own fetch() calls from the browser. This happened once: beta.web.matters.ai was deployed before it was added to the list, and its own demo form started returning cross_origin_blocked. Fix: extend PROD_ORIGINS.

When you add a new Matters subdomain#

1. Add https://<sub>.matters.ai to PROD_ORIGINS in lib/cors.ts.
2. If the new subdomain also exposes public APIs that other Matters surfaces will call, mirror the allow-list in that app's own CORS helper (today only the root app uses requireMattersOrigin; other apps gate via Clerk).
3. Re-deploy the root app so the new origin actually starts working as a caller.

Threat model — known closed gaps#

Threat model — open gaps tracked in PROD_CHECKLIST.md#

• CSRF tokens not enforced on workspace mutations. Mitigated today by Clerk session cookie + same-site policy; verify cookie attributes before public launch.
• Rate limiting is implemented (lib/security/rate-limit.ts) but not yet applied to every high-risk mutation route. Top priorities: bulk-invite, export, sync-salesforce.
• Audit logging covers ~8% of mutation routes. Target: 100% before deploy.
• lib/api/wrapper.ts has a TODO for requireAuth; either finish or delete.

Secrets#

• Server secrets are loaded by Next.js from .env.local and .env.secrets (gitignored).
• The canonical schema is packages/lib/src/config/env.ts — a single Zod-validated object that validates on boot. Missing required vars cause loud startup failures, not silent runtime ones.
• Production secrets live in Vercel project env vars. Rotation steps and ownership are tracked in the on-call runbook (Operations → Runbooks).

Reporting a vulnerability#

If you find something exploitable, do not open a public issue. Email security@matters.ai with a description and (if you can) a proof-of-concept. We acknowledge within 24 hours and ship a patch within 7 days for anything we can reproduce.