This document covers the security protection design in Kolya BR Proxy, including AWS WAF (rate limiting and managed rule sets at the ALB layer), Cross-Origin Resource Sharing (CORS), Cross-Site Request Forgery (CSRF) protection, API token hashing, refresh token hardening, and JWT library choices — how these attacks work, why an API gateway must defend against them, and the specific implementation in this project.

Kolya BR Proxy serves two types of clients:

1. API clients (Cline, Cursor, OpenAI SDK) — Call /v1/* endpoints with Bearer Tokens
2. Browser clients (Vue admin dashboard) — Call /admin/* endpoints with JWT (Bearer Token)

This project uses a hybrid authentication approach: access tokens are stored in localStorage and sent via Authorization: Bearer <token> headers, while refresh tokens are stored in HttpOnly cookies (kbr_refresh_token, Path=/admin/auth, SameSite=None; Secure) to prevent XSS theft of long-lived credentials. The OAuth login flow also uses PKCE (Proof Key for Code Exchange, S256) to prevent authorization code interception attacks.

This project implements full CORS and CSRF protection for the following reasons:

• Defense in Depth — Security should never rely on a single mechanism. The HttpOnly cookie for refresh tokens requires proper CSRF protection
• Origin validation blocks cross-origin requests from unauthorized domains regardless of the authentication method
• Security response headers prevent clickjacking, MIME sniffing, XSS, and other browser-side attacks
• Industry best practice — OWASP recommends these protections for all web APIs regardless of the current authentication scheme

The browser's Same-Origin Policy blocks web pages from making requests to a different origin (protocol + domain + port) by default. CORS is a set of HTTP headers that allow servers to declare which external origins may access their resources.

The frontend and backend in this project run on different origins, a typical cross-origin architecture:

Per the browser's Same-Origin Policy, if any of protocol, domain, or port differs, the request is cross-origin. Every request from the admin dashboard to the backend API is a cross-origin request. If the backend does not configure a CORS allowlist, the browser blocks all API calls from the frontend, and the admin dashboard cannot function at all.

CORS configuration is therefore a fundamental requirement for this project — not an optional security hardening measure, but a prerequisite for the separated frontend/backend architecture to work.

However, misconfigured CORS is equally dangerous:

• Access-Control-Allow-Origin: * — Any website can read API responses, potentially leaking sensitive data
• Overly broad allowlists — Attackers can leverage permitted domains to launch attacks

The correct approach is to only allow your own frontend domain and reject all other origins.

1. Admin logs into the Kolya BR Proxy dashboard (browser holds JWT)
2. Admin opens attacker's malicious site evil.com in a new tab
3. evil.com's JavaScript sends a GET request to https://api.kbp.kolya.fun/admin/tokens
4. If CORS is configured as *, the browser allows evil.com to read the response
5. Attacker obtains the full API Token list

Configuration entry: backend/main.py

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.get_allowed_origins(),  # Strict allowlist
    allow_credentials=True,                         # Allow credentials
    allow_methods=["*"],
    allow_headers=["*"],
)

Preflight reliability: SecurityMiddleware handles OPTIONS requests directly — returning CORS headers without calling call_next(). This prevents intermittent header loss that can occur when BaseHTTPMiddleware passes preflight requests through the full middleware chain. The CORS headers on preflight responses are thus guaranteed regardless of inner middleware behavior.

Per-environment policy:

Wildcard validation (backend/app/core/config.py):

@validator("ALLOWED_ORIGINS")
def validate_allowed_origins(cls, v, values):
    env = os.getenv("KBR_ENV", "non-prod")
    if v == "*" and env != "local":
        raise ValueError(
            f"Wildcard CORS origins ('*') not allowed in {env} environment. "
            "Only KBR_ENV=local supports '*'."
        )
    return v

CSRF attacks exploit the browser's automatic cookie-sending behavior to make authenticated users unknowingly submit requests to a target site. Unlike CORS, CSRF does not need to read the response — the damage is done simply by the request being executed.

This is a common misconception. CORS only controls whether the browser allows reading the response, not whether the request is sent:

For this project's JSON API, the CORS preflight mechanism provides some protection. But relying on CORS alone is insufficient:

• CORS policies can be misconfigured
• Browser behavior varies in edge cases
• Defense-in-depth requires multiple layers

This project stores refresh tokens in HttpOnly cookies (kbr_refresh_token, Path=/admin/auth), which means the browser automatically attaches them to matching requests. This makes CSRF protection directly relevant:

1. Admin is logged into the Kolya BR Proxy dashboard (browser holds HttpOnly refresh token cookie)
2. Admin opens a malicious page evil.com in another tab
3. evil.com submits a hidden form POST to https://api.kbp.kolya.fun/admin/auth/refresh
   (Content-Type: application/x-www-form-urlencoded, bypasses CORS preflight)
4. Browser automatically attaches the kbr_refresh_token cookie
5. Without CSRF protection, the server would issue a new access token to the attacker

The three-layer CSRF defense (Origin validation + Referer check + custom header requirement) prevents this attack. Additionally, the cookie is scoped to Path=/admin/auth, limiting the attack surface to auth endpoints only. Access tokens are stored in localStorage and sent via Authorization: Bearer headers, which browsers never attach automatically.

Implementation file: backend/app/middleware/security.py — SecurityMiddleware

This project uses a three-layer defense strategy:

For all state-changing operations (POST, PUT, DELETE, PATCH), verify the Origin header against the allowlist:

if origin and not self._is_origin_allowed(origin):
    # 403 Forbidden - Origin not allowed

• Browsers automatically include the Origin header on cross-origin requests, and JavaScript cannot forge it
• Requests from unlisted origins are immediately rejected

Verify the origin in the Referer header is legitimate:

if self.enforce_referer and not self._validate_referer(request):
    # 403 Forbidden - Invalid referer

• Disabled by default (enforce_referer=False) as some clients do not send Referer
• Can be enabled as an additional security layer

Require browser requests to include either X-Requested-With or Authorization:

if self.require_custom_header and origin:
    has_auth_header = request.headers.get("authorization")
    has_custom_header = request.headers.get("x-requested-with")
    if not has_auth_header and not has_custom_header:
        # 403 Forbidden - Missing CSRF protection header

Why does this prevent CSRF?

• HTML forms and <img> tags cannot set custom HTTP headers
• Only JavaScript's XMLHttpRequest or fetch can add custom headers
• Cross-origin JavaScript requests trigger CORS preflight, which is blocked by the origin allowlist

Frontend counterpart (frontend/src/boot/axios.ts):

const api = axios.create({
  headers: {
    'X-Requested-With': 'XMLHttpRequest',  // CSRF protection
  },
});

The following requests bypass CSRF checks:

The SecurityMiddleware described above protects general API requests from CSRF. However, the OAuth login flow has a unique attack surface — the OAuth callback endpoint.

In the OAuth Authorization Code flow, after the user completes authentication at a third party (Microsoft / Cognito), they are redirected back to this project's callback endpoint with a code parameter. If an attacker can craft a malicious callback URL and trick a user into clicking it, they can:

• Login CSRF: Bind the victim's session to the attacker's account
• Authorization code injection: Replace the victim's code with one obtained by the attacker, hijacking the user's account

1. Attacker initiates OAuth login and obtains a valid authorization code
2. Attacker crafts a callback URL:
   https://api.kbp.kolya.fun/admin/auth/cognito/callback?code=ATTACKER_CODE&state=...
3. Attacker tricks the victim (a logged-in admin) into clicking the link
4. Without state validation, the server accepts the attacker's code
5. The victim's browser session is bound to the attacker's OAuth identity

Key files:

• backend/app/services/oauth.py — OAuthService (state generation and validation)
• backend/app/models/oauth_state.py — OAuthState (database model)
• backend/app/api/admin/endpoints/auth.py — Login and callback endpoints

1. User clicks login → /admin/auth/cognito/login
   │
   ├── Generate state = secrets.token_urlsafe(32)  (cryptographically secure random)
   ├── Store in database oauth_states table (with provider, expires_at)
   └── Return authorization_url (includes state parameter)

2. User completes auth at Cognito/Microsoft → redirected to callback
   │
   ├── /admin/auth/cognito/callback?code=xxx&state=yyy
   │
   ├── Validate state:
   │   ├── Database lookup: state value + provider must match
   │   ├── Expiry check: valid for 10 minutes after creation
   │   ├── One-time use: deleted from database immediately after validation
   │   └── Any check fails → 403 Forbidden
   │
   └── State validated → exchange code for token → login success

Generate state (backend/app/services/oauth.py):

async def generate_state(self, provider: str) -> tuple[str, str]:
    state = secrets.token_urlsafe(32)
    code_verifier = secrets.token_urlsafe(96)  # PKCE
    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
    oauth_state = OAuthState(state=state, provider=provider, code_verifier=code_verifier)
    self.db.add(oauth_state)
    await self.db.commit()
    return state, code_challenge

Validate state (backend/app/services/oauth.py):

async def validate_state(self, state: str, provider: str) -> tuple[bool, str | None]:
    # Query database
    query = select(OAuthState).where(
        OAuthState.state == state, OAuthState.provider == provider
    )
    oauth_state = result.scalar_one_or_none()

    if not oauth_state or oauth_state.is_expired():
        return False, None

    code_verifier = oauth_state.code_verifier  # PKCE
    # One-time use: delete after validation
    await self.db.delete(oauth_state)
    await self.db.commit()
    return True, code_verifier

Callback endpoint validation (backend/app/api/admin/endpoints/auth.py):

# Both Microsoft and Cognito callbacks perform the same validation
is_valid, code_verifier = await oauth_state_service.validate_state(state, "cognito")
if not is_valid:
    raise HTTPException(
        status_code=status.HTTP_403_FORBIDDEN,
        detail="Invalid or expired state parameter",
    )
# code_verifier is passed to the token exchange request

PKCE is an OAuth 2.1 best practice that prevents authorization code interception attacks. Even if an attacker intercepts the authorization code (e.g., via a malicious browser extension or redirect), they cannot exchange it for tokens without the code_verifier.

This project uses the S256 challenge method. The entire PKCE flow is handled server-side — the frontend does not need to participate.

Since the backend handles both the authorization URL construction and the token exchange, the code_verifier is stored server-side in the oauth_states database table (alongside the CSRF state parameter). This means the frontend requires zero changes for PKCE support.

Refresh tokens are long-lived (7 days) credentials. Storing them in localStorage exposes them to XSS attacks — any injected JavaScript can read localStorage and exfiltrate the token. HttpOnly cookies cannot be accessed by JavaScript (document.cookie returns nothing), providing a strong defense against XSS theft.

The frontend (kbp.kolya.fun) and backend (api.kbp.kolya.fun) are on different subdomains. This requires:

• SameSite=None; Secure on the cookie (browsers require Secure when SameSite=None)
• withCredentials: true on the Axios client (to send cookies cross-origin)
• allow_credentials=True in CORS configuration (already in place)

For local development over HTTP, the cookie uses SameSite=Lax since SameSite=None requires HTTPS.

• Set cookie: backend/app/core/cookies.py — set_refresh_token_cookie()
• Read cookie: backend/app/core/cookies.py — get_refresh_token_from_cookie()
• Clear cookie: backend/app/core/cookies.py — clear_refresh_token_cookie()
• Backward compatibility: The /admin/auth/refresh and /admin/auth/revoke endpoints accept refresh tokens from both cookies (preferred) and request body (legacy)

In addition to CORS and CSRF protection, SecurityMiddleware adds security headers to every response:

The application-layer SecurityMiddleware protects against CORS/CSRF attacks, but it cannot defend against volumetric abuse — high-frequency requests that overwhelm backend resources. Rate limiting at the application layer requires additional infrastructure (e.g., Redis for distributed counters) and still consumes Pod resources for every request.

AWS WAF operates at the ALB layer, intercepting malicious traffic before it reaches EKS Pods:

Client → (Optional Global Accelerator) → ALB + WAF → EKS Pod
                                           │
                                           ├── Rate limit exceeded? → 403 (blocked at ALB)
                                           ├── Known bad input? → 403 (blocked at ALB)
                                           └── Passed all rules → Forward to Pod

Advantages over application-layer rate limiting:

The WAF WebACL contains five rules, evaluated in priority order:

Rule evaluation logic:

• Rules are evaluated from lowest to highest priority number
• Path-scoped rate limits (auth, chat) are checked first so they can enforce tighter limits on sensitive endpoints
• AWS Managed Rules catch known attack patterns (SQLi, XSS, Log4j, etc.) regardless of rate
• The global rate limit acts as a catch-all for any IP exceeding overall thresholds
• Default action is Allow — only requests matching a rule's condition are blocked

Certain rules in AWSManagedRulesCommonRuleSet produce false positives on legitimate LLM API traffic. The following rules are overridden to Count (log only, no block) via rule_action_override:

Security assurance: The /v1/chat/completions path is protected by Bearer Token authentication + IP rate limiting (300 req / 5 min). Downgrading these rules does not reduce actual security but prevents false-positive blocking of normal LLM traffic.

Excluded rules still operate in Count mode, so their trigger frequency can be monitored in CloudWatch metrics. If anomalous patterns are detected, they can be restored to Block at any time.

The WAF WebACL is associated with two ALBs (created by Kubernetes ALB Controller, discovered by name via Terraform data "aws_lb"):

Terraform module: iac/modules/waf/

Root module variables (iac/variables.tf):

All rules have CloudWatch metrics enabled (cloudwatch_metrics_enabled = true) and request sampling (sampled_requests_enabled = true). Metrics are available in the AWS WAF Console and CloudWatch under the following metric names:

• kbr-proxy-rate-limit-auth
• kbr-proxy-rate-limit-chat
• kbr-proxy-aws-managed-common
• kbr-proxy-aws-managed-bad-inputs
• kbr-proxy-rate-limit-global
• kbr-proxy-waf-<workspace> (WebACL-level default metric)

Browser Request → ALB + WAF → SecurityMiddleware → CORS Middleware → Route Handler
                    │                │
                    │                ├── /health/* → Skip checks, pass through
                    │                ├── OPTIONS → Skip checks (CORS preflight)
                    │                ├── GET/HEAD → Skip CSRF checks, add security headers
                    │                └── POST/PUT/DELETE/PATCH
                    │                      │
                    │                      ├── 1. Origin not in allowlist? → 403
                    │                      ├── 2. Invalid Referer? (if enabled) → 403
                    │                      ├── 3. Browser request missing Authorization and X-Requested-With? → 403
                    │                      └── All passed → Add security headers → Continue processing
                    │
                    ├── Rate limit exceeded? → 403 (blocked at ALB, never reaches Pod)
                    ├── Matches AWS Managed Rule? → 403 (blocked at ALB)
                    └── Passed all WAF rules → Forward to Pod

API Client Request (no Origin header) → ALB + WAF → SecurityMiddleware → Route Handler
                                           │               │
                                           │               └── No Origin → Skip CSRF checks
                                           │                    → Bearer Token validated at route layer
                                           │
                                           └── WAF rules apply equally to API clients

Secrets are managed through AWS Secrets Manager with External Secrets Operator (ESO) syncing them into Kubernetes. This replaces local secrets.yaml files and ensures secrets never exist in version control.

deploy-all.sh
  ├── aws secretsmanager put-secret-value  →  AWS Secrets Manager
  │                                              (single source of truth)
  │
  └── kubectl apply ExternalSecret CRDs
        ↓
      External Secrets Operator (ESO)
        ├── Authenticates via Pod Identity (no static AWS creds)
        ├── Reads secrets from AWS Secrets Manager
        ├── Creates/updates Kubernetes Secrets (refreshInterval: 1h)
        └── Backend Pods consume secrets via envFrom / env references

API tokens are hashed before storage using plain SHA256 (hashlib.sha256). The hash is deterministic (same input always produces the same output), so it is indexed in the database for O(1) lookup by hash.

The hashing scheme serves two purposes:

1. Secure storage — Even if the database is compromised, the original tokens cannot be recovered from the hashes
2. Fast lookup — The deterministic hash is indexed in the database for O(1) lookup

Additionally, tokens are encrypted with Fernet (AES-128-CBC) using a key derived from JWT_SECRET_KEY. This allows administrators to retrieve the original token value when needed (e.g., for display in the admin dashboard), while the hash is used for authentication lookups.

Plain SHA256 is fast, which means an attacker with a leaked database could brute-force token hashes quickly. However, API tokens are generated with high entropy (secrets.token_urlsafe(32), 256 bits), making brute-force infeasible regardless of hash speed. The Fernet-encrypted token provides a second layer of protection requiring JWT_SECRET_KEY to decrypt.

Note: This is distinct from refresh token hashing, which uses PBKDF2-HMAC-SHA256 with 100,000 iterations (see Refresh Token Security Hardening below).

• backend/app/core/security.py — hash_token(), verify_token(), encrypt_token(), decrypt_token()
• backend/app/core/redis.py — RedisCache wrapper with JSON serialization and graceful degradation
• backend/app/services/token.py — Token creation and validation service
• backend/app/services/token_cache.py — CachedTokenService with Redis cache (TTL 300s) and DB fallback

When a token is deleted via DELETE /admin/tokens/{token_id}, three layers ensure it is immediately blocked from API access:

The token is soft-deleted (is_deleted = true) to preserve historical usage data for reporting, but is_active = false is the authoritative gate for API access.

Super admins need to export all API keys (including plaintext values) for audit or migration purposes. However, plaintext keys must never appear in any XHR/JSON response — even if an attacker monitors DevTools Network tab, browser extensions intercept responses, or XSS scripts read JavaScript variables, they cannot obtain key values.

The export uses browser-native navigation (window.open()) instead of XHR/fetch:

┌─────────────┐         XHR/fetch           ┌──────────┐
│   Frontend  │  ◄──────────────────────►   │  Backend │
│             │   key_prefix only (no key)  │          │
└─────────────┘                             └──────────┘

┌─────────────┐      window.open (HTTPS)     ┌──────────┐
│   Browser   │  ─────── download CSV ────►  │  Backend │
│  Download   │  ◄─── Content-Disposition ── │ decrypt  │
│  Manager    │    file saved to disk,       └──────────┘
└─────────────┘    never enters JS runtime

1. Normal API interaction (XHR/fetch) — GET /admin/tokens returns TokenResponse with only key_prefix: "sk-ant-api03". The full key value is never included in any JSON response.

2. CSV export (window.open()) — Only GET /admin/tokens/export/keys calls decrypt_token() to retrieve plaintext values. The response is a Content-Disposition: attachment file download that the browser saves directly to disk without passing through the JavaScript runtime.

• backend/app/api/admin/endpoints/tokens.py — export_keys_csv() endpoint
• frontend/src/pages/DashboardPage.vue — exportKeys() function using window.open()

Refresh tokens (JWT strings) are hashed with PBKDF2-HMAC-SHA256 using 100,000 iterations before storage. This was increased from 1 iteration to 100,000 to provide meaningful resistance against offline brute-force attacks if the database is compromised.

The hash is deterministic and keyed with JWT_SECRET_KEY, allowing efficient lookup while preventing offline attacks without the server secret.

Refresh token rotation (issuing a new refresh token and invalidating the old one) uses row-level locking (SELECT ... FOR UPDATE) to prevent race conditions. Without this, concurrent requests using the same refresh token could both succeed, creating duplicate active tokens and breaking the rotation chain.

The locking ensures that only one concurrent request can rotate a given refresh token — subsequent requests using the same token see it as already consumed and are rejected.

• backend/app/core/security.py — hash_refresh_token()
• backend/app/api/admin/endpoints/auth.py — Refresh endpoint with row-level locking

The project migrated from python-jose to PyJWT for JWT encoding and decoding. The primary reasons:

The migration was a drop-in replacement at the API level. The project enforces an algorithm whitelist (HS256, HS384, HS512) to prevent algorithm confusion attacks, regardless of library.

• backend/app/core/security.py — JWT encoding/decoding with PyJWT (import jwt)

The system implements two-tier RBAC via the role and permissions fields on the User model:

Admin users have a permissions JSON field that controls access to specific resource types:

Permission value rules:

• true or "all": full access to all resources of that type
• Array of UUIDs: access only to those specific resources (only manage_api_keys, manage_teams, manage_models support resource-level scoping)
• false or missing: no access (403)
• Special case: when permissions is null or empty {}, the admin has full access to all business operations (no restrictions applied). Once any key is set in permissions, unset keys are treated as denied

When KBR_MICROSOFT_ENABLE_GROUP_SYNC=true, user roles and permissions are resolved from Azure AD security group membership instead of being set manually. See OAuth Setup — Entra ID Group Sync for configuration details.

Microsoft OAuth callback
  │
  ├─ No group mappings exist AND no Microsoft users in DB?
  │    → Bootstrap: grant super_admin to this first user
  │
  ├─ No group mappings exist BUT Microsoft users already exist?
  │    → Reject with 403 "Group mappings not configured"
  │
  ├─ Group mappings exist → call Graph API /me/memberOf
  │    │
  │    ├─ Graph API error (network, 401, 429, 500)?
  │    │    → Fail closed: reject with 503 "Unable to verify group membership"
  │    │
  │    ├─ User groups match a mapping?
  │    │    → Use the highest-priority mapping's role + permissions
  │    │
  │    └─ User groups don't match any mapping?
  │         → Reject with 403 "Not authorized"
  │
  └─ Apply resolved role/permissions to user record (overwrite on every login)

1. Fail closed on Graph API errors — If the Graph API call to /me/memberOf fails for any reason, login is rejected with HTTP 503. This prevents stale elevated permissions from persisting when group membership cannot be verified.

2. Bootstrap is single-use — Only the very first Microsoft user (when no Microsoft users exist in the DB AND no group mappings are configured) receives automatic super_admin. All subsequent users are rejected until the first admin creates group mappings via the Entra Groups page.

3. Every login syncs permissions — The role and permissions are overwritten on every successful login based on the current group mapping. If a user is moved between Entra groups, their KBP permissions update on next login. There is no way to manually override a Microsoft user's role when group sync is active.

4. Cognito users are unaffected — Group sync only applies to Microsoft OAuth users. Cognito users continue to be managed manually via the Admin Users page. The two auth methods coexist independently.

5. Priority-based resolution — When a user belongs to multiple mapped groups, the mapping with the highest priority value wins. This allows fine-grained control (e.g., "Engineering" group = admin with limited permissions at priority 5, "Platform Team" = super_admin at priority 10).

The sidebar dynamically filters menu items based on permissions. Unauthorized features are hidden:

• backend/app/models/user.py — UserRole enum, role and permissions columns
• backend/app/api/deps.py — require_permission(), check_resource_scope(), get_allowed_resource_ids()