Security

Terra uses defense-in-depth: multiple layers of protection with fail-secure defaults.

Authentication

Sessions are encrypted JWT cookies via WorkOS OAuth. The app refuses to start without WORKOS_COOKIE_PASSWORD:

// src/middleware.ts — fail-secure on missing config
if (!cookiePassword) {
  throw new Error("WORKOS_COOKIE_PASSWORD is required");
}

If decryption fails or the role is unrecognized, the user defaults to "applicant" — the lowest privilege:

// src/middleware.ts — role validation (inline checks, fail-secure)
if (
  !role ||
  (role !== "super_admin" &&
    role !== "admin" &&
    role !== "editor" &&
    role !== "viewer" &&
    role !== "user" &&
    role !== "applicant")
) {
  session.user.role = "applicant"; // Fail-secure: unknown role gets minimum access
}

CSP headers use a per-request nonce (16 random bytes) for script tags. frame-ancestors: 'self' prevents clickjacking. Tests: 25 cases in src/lib/__tests__/auth-guards.test.ts

pnpm --dir apps/terra test -- -t "Auth Guards"

What the tests prove

Missing or malformed sessions throw UNAUTHENTICATED - Non-admin roles get UNAUTHORIZED on admin-only functions - admin cannot call super_admin-only functions - Nonexistent forms return NOT_FOUND - withAdminAuth / withFormAuth wrappers block unauthorized actions before they execute

Try to break it: Tamper with the wos-session cookie in the browser — decryption should fail and redirect to /login. Navigate to /admin while logged out — should redirect.

Authorization (RBAC)

Two layers checked together: global role sets the ceiling, form role sets the grant. The critical invariant: a global viewer cannot edit a form even if they hold owner at the form level.

// src/app/actions/team.ts — canEditForm()
const systemRole = await getSystemRole(userId);

if (systemRole === "super_admin" || systemRole === "admin") return true;

const formRole = await getUserFormRole(userId, formId);

// Global viewer caps everything to read-only
if (systemRole === "viewer") return false;

// Global editor can edit assigned forms
if (systemRole === "editor") return true;

return formRole === "owner" || formRole === "editor";

Tests: 38 cases across 4 files

pnpm --dir apps/terra test -- -t "Team Permissions"
pnpm --dir apps/terra test -- -t "Permission System"
pnpm --dir apps/terra test -- -t "submission-management"
pnpm --dir apps/terra test -- -t "system action authorization"

What the tests prove

Super admins bypass all form-level checks - Global viewer overrides form owner (read-only cap) - Global editor overrides form viewer (can edit assigned forms) - Viewers cannot bulk-modify submissions - Scoped users with no assigned forms see nothing - Non-admins cannot list users, invite admins, or change roles - Last owner of a form cannot be removed or demoted

Try to break it: Log in as a viewer, call a mutation server action directly (e.g., bulkMarkAsTest). It should return { success: false }. Try removing the last owner of a form — the system should reject it.

Migration boundary: canEditForm() has a backwards-compat fallback that returns true when the program_members table doesn’t exist. Review team.ts lines 110-122 to determine if this is still needed.

Input Validation

Three layers protect file paths:

// Layer 1: Sanitize the filename
const safe = cleanFileName("../../evil.exe"); // → "evil.exe"

// Layer 2: Build a safe storage path
const path = buildSafeStoragePath(formId, fileId, safe);
// → "form-123/file-456/evil.exe"

// Layer 3: Final validation (throws on traversal, null bytes, hidden files)
sanitizeStoragePath(path);

Redirect safety prevents open redirects after login:

// src/lib/security.ts — blocks //evil.com, javascript:, data:, encoded variants
getSafeRedirectPath("//evil.com"); // → "/"
getSafeRedirectPath("javascript:alert"); // → "/"

// Defense-in-depth: same-origin check catches anything getSafeRedirectPath misses
const dest = createSafeInternalRedirect(path, baseUrl);
if (dest.origin !== origin) redirect("/"); // CRITICAL log if this ever fires

Tests: 72 cases in src/lib/__tests__/security.test.ts, 15 in files-security.test.ts, 11 in import-security.test.ts

pnpm --dir apps/terra test -- -t "Path Traversal"
pnpm --dir apps/terra test -- -t "Open Redirect"
pnpm --dir apps/terra test -- -t "File Security"
pnpm --dir apps/terra test -- -t "Import Security"

What the tests prove

Path traversal: ../, ..\\, null bytes, URL-encoded, double-encoded, mixed slashes, bucket escape
Open redirect: //evil.com, javascript:, data:, backslash, encoded variants all return /
File upload: .exe rejected, MIME mismatch caught, SVG with <script> detected, PDF with JS detected
File operations: Cross-form file access blocked, path traversal on delete blocked, super_admin bypass works
Import: User ID comes from session (not request), cannot impersonate another user, max 8 images / 10MB PDF

Rate Limiting

// src/lib/rate-limit.ts
const LIMITS = {
  formSubmission: { limit: 30, window: 60, key: "per-IP" },
  statusLookup: { limit: 10, window: 60, key: "per-IP" }, // Stricter: prevents enumeration
  webhook: { limit: 500, window: 60, key: "global" },
};

If Redis (Upstash) is unavailable:

Production: Fail closed — deny all requests
Development: Fail open — allow all requests

pnpm --dir apps/terra test -- -t "Rate Limiting"

What the tests prove (20+ cases)

Rate limit values documented: 30/min submissions, 10/min status, 500/min webhooks - Production fails closed when Redis is down - Development fails open
Status lookups are stricter than submissions (enumeration prevention) - Client IP extracted correctly from x-forwarded-for, cf-connecting-ip, x-real-ip

Webhook Security

Outbound webhooks are signed with HMAC-SHA256 and include a timestamp for replay prevention:

// Headers sent with every webhook delivery
{
  "X-Terra-Signature": hmac("sha256", secret, body),
  "X-Terra-Event": "submission.created",
  "X-Terra-Timestamp": "1704000000"
}

// Receiver verifies: |now - timestamp| <= 5 minutes

Webhook failures are fire-and-forget — they don’t block the submission. The async queue retries up to 5 times with exponential backoff.

pnpm --dir apps/terra test -- -t "Webhook"
pnpm --dir apps/terra test -- -t "webhook-security"

What the tests prove (22 cases)

Auth enforced on all webhook operations (get, save, regenerate, delete) - Invalid URLs rejected - Secrets are 64 chars (32 bytes hex), regeneration produces a different secret - HMAC signatures are deterministic (same input → same output) - Different payloads/secrets produce different signatures - Unsigned webhooks blocked in production - Timestamp freshness enforced (5-min window) - Webhook failure (500, network error) doesn’t throw — just logs

Data Protection

PII encryption and audit logging

Test Coverage

Full test inventory

Foundation

Core Systems

Features

Integrations

Production Review

Operations

Reference

Security

Security

Authentication

Authorization (RBAC)

Input Validation

Rate Limiting

Webhook Security

Data Protection

Test Coverage

​Security

​Authentication

​Authorization (RBAC)

​Input Validation

​Rate Limiting

​Webhook Security

Data Protection

Test Coverage

Security

Authentication

Authorization (RBAC)

Input Validation

Rate Limiting

Webhook Security