We take security seriously at OpenCTEM. If you discover a security vulnerability, please follow responsible disclosure practices.

• Open a public GitHub issue for security vulnerabilities
• Disclose the vulnerability publicly before it has been addressed
• Exploit the vulnerability beyond what is necessary to demonstrate it

1. Email us directly at security@openctem.io with:

   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact assessment
   • Suggested fix (if any)

2. Use our bug bounty program (if available) through:

   • HackerOne (coming soon)

Browser                          Next.js Server                    Backend API
  |                                   |                                |
  |-- (1) Login (email/password) ---->|                                |
  |                                   |-- POST /api/v1/auth/login ---->|
  |                                   |<-- { refresh_token, tenants } -|
  |                                   |                                |
  |                                   |-- POST /api/v1/auth/token ---->|
  |                                   |<-- { access_token, exp } ------|
  |                                   |                                |
  |<-- Set-Cookie: auth_token (httpOnly, secure, sameSite=lax) --------|
  |<-- Set-Cookie: refresh_token (httpOnly, secure, sameSite=lax) -----|
  |<-- access_token (in JSON response body, stored in Zustand) --------|
  |                                   |                                |
  |-- API request /api/v1/findings -->|                                |
  |   (cookie sent automatically)     |-- reads httpOnly cookie ------>|
  |                                   |-- Authorization: Bearer JWT -->|
  |                                   |<-- JSON response --------------|
  |<-- JSON response (no token) ------|                                |

Key implementation details (src/stores/auth-store.ts):

• Access token stored exclusively in Zustand state. Never persisted to cookies, localStorage, or sessionStorage.
• JWT decoded client-side via atob() to extract user claims (sub, email, permissions, tenant_id, tenant_role). No signature verification on client -- verification is done server-side at the backend API.
• Zustand devtools disabled in production (enabled: process.env.NODE_ENV === 'development').

• Auto-refresh triggers TOKEN_REFRESH_BEFORE_EXPIRY seconds before expiration (default: 300s = 5 minutes).
• Calls POST /api/auth/refresh with credentials: 'include' (sends httpOnly cookie).
• Mutex-protected: isRefreshingToken flag prevents concurrent refresh attempts.
• Permanent failure flag: authPermanentlyFailed prevents infinite refresh loops. On failure, clears all auth state and redirects to login.
• Token size monitored: logs warning when JWT approaches 4KB cookie limit.

All client-side API requests go through the Next.js API proxy route (src/app/api/v1/[...path]/route.ts), not directly to the backend:

1. Browser sends request to /api/v1/* (same-origin, cookie sent automatically).
2. Proxy reads auth_token from httpOnly cookie.
3. Proxy forwards request to backend with Authorization: Bearer <token> header.
4. If 401: proxy auto-refreshes token and retries once.
5. Response returned to browser without exposing the token.

Benefits: Eliminates CORS issues, tokens never appear in client JavaScript for API calls, backend URL hidden from browser.

All auth cookies are set with:

httpOnly: true
secure: true (when NODE_ENV === 'production')
sameSite: 'lax'
path: '/'

Complete cookie inventory:

1. User submits credentials to Server Action (loginAction).
2. Server Action calls backend POST /api/v1/auth/login.
3. Backend returns refresh_token + list of tenant memberships.
4. If single tenant: exchanges refresh token for tenant-scoped access token via POST /api/v1/auth/token.
5. If multiple tenants: stores tenant list in non-httpOnly cookie for selection UI.
6. If zero tenants: redirects to team creation onboarding.
7. Access token returned in response body (stored in Zustand), refresh token set as httpOnly cookie.

logoutAction() clears ALL auth cookies (auth_token, refresh_token, app_tenant, app_user_info, app_pending_tenants) and redirects to /login.

• Supported providers: Google, GitHub, Microsoft.
• CSRF protection: Random state parameter stored in httpOnly oauth_state cookie, validated on callback.
• Token flow follows same httpOnly cookie pattern as local auth.

forgotPasswordAction() always returns { success: true } regardless of whether the email exists in the system.

• 150+ permissions defined in src/lib/permissions/constants.ts.
• Hierarchical format: {module}:{subfeature}:{action} (e.g., assets:groups:write).
• Permissions are the source of truth from the API -- no client-side bypass for Owner/Admin roles.

The PermissionProvider (src/context/permission-provider.tsx) keeps permissions in sync:

• Debounce: Minimum 5 seconds between API calls.
• ETag support: Conditional If-None-Match requests to reduce bandwidth.
• localStorage cache: Permissions cached for instant UI render on page reload. Cleared on logout via clearAllStoredPermissions().

// Hide element if user lacks permission
<Can permission="assets:write">
  <EditButton />
</Can>

// Show disabled element with tooltip
<Can permission="assets:delete" behavior="disable">
  <DeleteButton />
</Can>

• JWT contains tenant_id claim scoping all API requests.
• Backend enforces WHERE tenant_id = ? on all data queries.
• Permission cache keys include tenant ID to prevent cross-tenant data leaks.
• Team switching exchanges tokens via POST /api/auth/switch-team.

The Next.js 16 proxy (proxy.ts) uses handleAuth() from src/lib/middleware/auth.ts:

• All routes require authentication by default.
• Public routes explicitly whitelisted: /login, /register, /forgot-password, /reset-password, /verify-email, /auth/callback, /auth/error.
• API routes (/api/*) handled separately.
• Authenticated users redirected away from auth pages.

validateRedirectUrl() ensures redirect targets:

• Start with / (relative path) but not // (protocol-relative, which could redirect to external domains).
• Or match the NEXT_PUBLIC_APP_URL origin exactly.
• Falls back to /dashboard if validation fails.

The proxy checks for cookie existence only (not validity). JWT signature verification happens at the backend API layer. This keeps the proxy lightweight and avoids duplicating verification logic.

Configured in next.config.ts, applied to all routes via /:path*:

Known trade-offs:

• unsafe-eval and unsafe-inline in script-src are required by the Next.js compiler. Mitigated by strict frame-ancestors 'none' and base-uri 'self'. Nonce-based CSP should be explored in future versions.
• img-src https: allows images from any HTTPS source (needed for user avatars and external content).

For same-origin WebSocket connections, httpOnly cookies are sent automatically during the upgrade handshake. No additional token is needed.

For cross-origin connections (src/context/websocket-provider.tsx):

1. Client fetches token from /api/ws-token (authenticated endpoint, reads httpOnly cookie).
2. Token appended as query parameter: wss://api.example.com/ws?token=<jwt>.
3. Protocol auto-selects wss: for HTTPS origins, ws: for HTTP.

Trade-off: JWT appears in URL for cross-origin WebSocket (common pattern due to WebSocket API limitations). The /api/ws-token endpoint only returns the token to the same browser session that owns the httpOnly cookie.

Same pattern as WebSocket. Endpoint at /api/auth/sse-token returns access token for Server-Sent Events connections. Auto-refreshes if access token expired.

• OAuth flows: Protected via random state parameter stored in httpOnly cookie.
• API mutations: Protected by same-origin proxy pattern. All API calls go through /api/v1/* (same-origin), so browsers enforce same-origin policy automatically.
• CSRF token: generateCsrfToken() in src/lib/cookies-server.ts generates tokens stored in httpOnly, secure, sameSite=strict cookies. The proxy forwards x-csrf-token headers to the backend.

All forms use Zod schemas (src/features/*/schemas/) for:

• Client-side validation (immediate UX feedback via React Hook Form).
• Server-side validation (Server Actions re-validate before processing).

• strict: true in tsconfig.json -- no implicit any, strict null checks.
• no-explicit-any ESLint rule enforced (except test files).

Baked into the client bundle at build time. Safe to expose:

Never exposed to the browser:

validateEnv() in next.config.ts validates required variables at build time. Warns on missing optional variables. Skipped during Docker builds (CI=true).

File: Dockerfile

Runs on: push/PR to main/develop + weekly (Monday 00:00 UTC)

Automatically run on git commit:

• TypeScript type checking on all staged files.
• ESLint auto-fix on staged .ts/.tsx files.
• Prettier formatting on staged files.

• Weekly updates for npm, GitHub Actions, Docker base images.
• Grouped updates: React, Next.js, testing, linting, Tailwind, Radix UI, TypeScript.
• Major versions blocked by default (security updates still allowed).
• Review assigned to openctemio/security team.

A development-only auth bypass exists in src/lib/dev-auth.ts:

• Enabled only when NODE_ENV === 'development'.
• Uses hardcoded dev credentials (admin@openctem.io).
• Sets a dev_auth_token cookie (non-httpOnly) accepted by the middleware.
• Completely disabled in production via NODE_ENV guard.

The API error handler (src/lib/api/error-handler.ts) maps backend errors to user-friendly messages. Backend messages shorter than 100 characters and not containing internal markers are passed through. Sensitive errors (500s, auth failures) are replaced with generic messages.

1. Never commit secrets -- Use .env.local (gitignored), not .env.
2. Validate all inputs with Zod schemas in both client and server.
3. Use Server Components by default to reduce client-side attack surface.
4. Use window.location.href (not router.push) after auth changes to ensure cookies are picked up.
5. No any types -- Use unknown and narrow with type guards.
6. Run npm run validate before every commit (type-check + lint + format).

1. Never store tokens in localStorage or sessionStorage -- Use Zustand store (memory only).
2. Never use dangerouslySetInnerHTML without sanitization.
3. Never add NEXT_PUBLIC_ prefix to secret environment variables.
4. Never bypass the API proxy for authenticated requests (except file uploads which use XHR with in-memory token).
5. Never hardcode credentials outside of dev-only guarded code.

• Sensitive cookies: Always httpOnly: true, secure: true in production, sameSite: 'lax'.
• Client-accessible cookies: Only for non-sensitive data (locale, theme, tenant display info).
• The authTokenCookie.set() client-side method is deliberately blocked and logs an error.

• Nonce-based CSP to eliminate unsafe-inline/unsafe-eval
• Environment-conditional CSP connect-src (strip localhost in production)
• Upgrade CSRF token generation to crypto.randomBytes()
• Client-side rate limiting for login attempts (config exists at SECURITY_CONFIG.MAX_LOGIN_ATTEMPTS: 5 but not yet enforced)
• Subresource Integrity (SRI) for external resources

• OWASP Top 10 (actively addressed)
• CWE/SANS Top 25 (actively addressed)
• SOC 2 Type II (planned)
• ISO 27001 (planned)

• Security Team: security@openctem.io
• General Issues: https://github.com/openctemio/ui/issues