Production Security¶
Comprehensive security guide for production FraiseQL deployments: SQL injection prevention, query complexity limits, rate limiting, CORS, authentication, PII handling, and compliance patterns.
Overview¶
Production security requires defense in depth: multiple layers of protection from the network edge to the database, with continuous monitoring and incident response.
Security Layers:
- SQL injection prevention (parameterized queries)
- Query complexity analysis
- Rate limiting
- CORS configuration
- Authentication & authorization
- Sensitive data handling
- Audit logging
- Compliance (GDPR, SOC2)
SQL Injection Prevention¶
Parameterized Queries¶
FraiseQL uses parameterized queries exclusively:
import fraiseql
from fraiseql.types import ID
# SAFE: repository filters are always bound parameters
@fraiseql.query
async def get_user(info, user_id: ID) -> User | None:
db = info.context["db"]
return await db.find_one("v_user", mandatory_filters={"id": user_id})
# SAFE: raw SQL with psycopg placeholders
async def get_user_email(db, user_id: str) -> str | None:
async with db.get_pool().connection() as conn:
result = await conn.execute(
"SELECT email FROM tb_user WHERE id = %s",
(user_id,) # Sent as a parameter, never spliced into the SQL
)
row = await result.fetchone()
return row[0] if row else None
# UNSAFE: String interpolation (never do this!)
# async def get_user_unsafe(db, user_id: str):
# query = f"SELECT * FROM tb_user WHERE id = '{user_id}'"
# result = await conn.execute(query) # VULNERABLE
Input Validation¶
import fraiseql
from fraiseql.security import InputValidator, ValidationResult
class UserInputValidator:
"""Validate user inputs."""
@staticmethod
def validate_user_id(user_id: str) -> ValidationResult:
"""Validate UUID format."""
import uuid
try:
uuid.UUID(user_id)
return ValidationResult(valid=True)
except ValueError:
return ValidationResult(
valid=False,
error="Invalid user ID format"
)
@staticmethod
def validate_email(email: str) -> ValidationResult:
"""Validate email format."""
import re
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
if re.match(pattern, email):
return ValidationResult(valid=True)
else:
return ValidationResult(
valid=False,
error="Invalid email format"
)
# Usage in resolver
@fraiseql.mutation
async def update_user(info, user_id: str, email: str) -> User:
# Validate inputs
user_id_valid = UserInputValidator.validate_user_id(user_id)
if not user_id_valid.valid:
raise ValueError(user_id_valid.error)
email_valid = UserInputValidator.validate_email(email)
if not email_valid.valid:
raise ValueError(email_valid.error)
# Safe to proceed
return await update_user_email(user_id, email)
GraphQL Injection Prevention¶
from graphql import parse, validate
def sanitize_graphql_query(query: str) -> str:
"""Validate GraphQL query syntax."""
try:
# Parse to AST (validates syntax)
document = parse(query)
# Validate against schema
errors = validate(schema, document)
if errors:
raise ValueError(f"Invalid query: {errors}")
return query
except Exception as e:
raise ValueError(f"Query validation failed: {e}")
Query Complexity Limits¶
FraiseQL checks a query's depth and complexity before it runs, on POST and
GET /graphql (APQ persisted queries included). A query over a limit gets a GraphQL
error and runs no resolver or SQL. No limit is on by default.
Depth Limiting¶
from fraiseql.fastapi.config import FraiseQLConfig
config = FraiseQLConfig(
database_url="postgresql://...",
max_query_depth=10, # or FRAISEQL_MAX_QUERY_DEPTH=10
)
{ users { id } } has depth 1, { users { posts { id } } } depth 2; fragments add no
depth of their own. A deeper query gets:
{"errors": [{"message": "Query depth 12 exceeds the maximum depth of 10",
"extensions": {"code": "QUERY_TOO_DEEP", "depth": 12, "maxDepth": 10}}]}
Introspection (__schema, __type) is not counted: introspection_policy decides who
may run it (it is disabled in production by default).
Complexity Analysis¶
config = FraiseQLConfig(
database_url="postgresql://...",
# Setting a limit turns complexity_enabled on
complexity_max_score=1000,
complexity_max_depth=10,
complexity_default_list_size=10,
# Cost of a field instead of 1, by name or "Type.field"
complexity_field_multipliers={
"search": 5,
"Order.lines": 3,
},
)
The score is computed from the schema: a scalar costs 1, an object field 1 plus its
selections, and a list field 1 plus its selections times its limit / first argument
(literal or variable), else complexity_default_list_size. { users { posts { id } } }
without limits scores 1 + 10 * (1 + 10 * 1) = 111; with users(limit: 2) it scores
1 + 2 * 11 = 23. A query over complexity_max_score gets a QUERY_TOO_COMPLEX error
(extensions.complexity, extensions.maxComplexity), one deeper than
complexity_max_depth a QUERY_TOO_DEEP error. complexity_enabled=False keeps these
two limits off; max_query_depth always applies.
Rate Limiting¶
Redis-Based Rate Limiting¶
from fraiseql.security import (
setup_rate_limiting,
RateLimitRule,
RateLimit,
RedisRateLimitStore
)
import redis.asyncio as redis
# Redis client
redis_client = redis.from_url("redis://localhost:6379/0")
# Rate limit rules
rate_limits = [
# GraphQL endpoint
RateLimitRule(
path_pattern="/graphql",
rate_limit=RateLimit(requests=100, window=60), # 100/min
message="GraphQL rate limit exceeded"
),
# Authentication endpoints
RateLimitRule(
path_pattern="/auth/login",
rate_limit=RateLimit(requests=5, window=300), # 5 per 5 min
message="Too many login attempts"
),
RateLimitRule(
path_pattern="/auth/register",
rate_limit=RateLimit(requests=3, window=3600), # 3 per hour
message="Too many registration attempts"
),
# Mutations
RateLimitRule(
path_pattern="/graphql",
rate_limit=RateLimit(requests=20, window=60), # 20/min for mutations
http_methods=["POST"],
message="Mutation rate limit exceeded"
)
]
# Setup rate limiting
setup_rate_limiting(
app=app,
redis_client=redis_client,
custom_rules=rate_limits
)
Per-User Rate Limiting¶
from fraiseql.security import GraphQLRateLimiter
class PerUserRateLimiter:
"""Rate limit per authenticated user."""
def __init__(self, redis_client):
self.redis = redis_client
async def check_rate_limit(
self,
user_id: str,
limit: int = 100,
window: int = 60
) -> bool:
"""Check if user is within rate limit."""
key = f"rate_limit:user:{user_id}"
current = await self.redis.incr(key)
if current == 1:
await self.redis.expire(key, window)
if current > limit:
return False
return True
@app.middleware("http")
async def user_rate_limit_middleware(request: Request, call_next):
if not hasattr(request.state, "user"):
return await call_next(request)
user_id = request.state.user.user_id
limiter = PerUserRateLimiter(redis_client)
allowed = await limiter.check_rate_limit(user_id)
if not allowed:
return Response(
content=json.dumps({
"errors": [{
"message": "Rate limit exceeded for user",
"extensions": {"code": "USER_RATE_LIMIT_EXCEEDED"}
}]
}),
status_code=429,
media_type="application/json"
)
return await call_next(request)
CORS Configuration¶
Production CORS Setup¶
from fraiseql.fastapi.config import FraiseQLConfig
config = FraiseQLConfig(
database_url="postgresql://...",
# CORS - disabled by default, configure explicitly
cors_enabled=True,
cors_origins=[
"https://app.yourapp.com",
"https://www.yourapp.com",
# NEVER use "*" in production
],
cors_methods=["GET", "POST"],
cors_headers=[
"Content-Type",
"Authorization",
"X-Request-ID"
]
)
Custom CORS Middleware¶
from starlette.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=[
"https://app.yourapp.com",
"https://www.yourapp.com"
],
allow_credentials=True,
allow_methods=["GET", "POST", "OPTIONS"],
allow_headers=[
"Content-Type",
"Authorization",
"X-Request-ID",
"X-Correlation-ID"
],
expose_headers=["X-Request-ID"],
max_age=3600 # Cache preflight for 1 hour
)
Authentication Security¶
Token Security¶
import os
from datetime import timedelta
import fraiseql
from fraiseql.auth.native import TokenManager
# JWT configuration (HS256 access and refresh tokens)
token_manager = TokenManager(
secret_key=os.environ["JWT_SECRET_KEY"], # NEVER hardcode
access_token_ttl=timedelta(hours=1),
refresh_token_ttl=timedelta(days=30),
)
@fraiseql.type
class TokenPair:
access_token: str
refresh_token: str
token_type: str = "bearer"
# Token rotation
@fraiseql.mutation
async def refresh_access_token(info, refresh_token: str) -> TokenPair:
"""Rotate access token using refresh token."""
# Checks the signature, the expiry and that it is a refresh token
payload = token_manager.verify_refresh_token(refresh_token)
# New access and refresh tokens, in the same token family
tokens = token_manager.generate_tokens(payload["sub"], family_id=payload["family"])
# Revoke old refresh token
await revocation_service.revoke_token(payload)
return TokenPair(
access_token=tokens["access_token"],
refresh_token=tokens["refresh_token"],
)
verify_refresh_token raises TokenExpiredError or InvalidTokenError (from
fraiseql.auth.native). For tokens from an identity provider (Auth0, or your own
issuer with iss / aud claims), validate them in an AuthProvider instead: see
Authentication.
Password Security¶
import bcrypt
class PasswordHasher:
"""Secure password hashing with bcrypt."""
@staticmethod
def hash_password(password: str) -> str:
"""Hash password with bcrypt."""
salt = bcrypt.gensalt(rounds=12)
hashed = bcrypt.hashpw(password.encode(), salt)
return hashed.decode()
@staticmethod
def verify_password(password: str, hashed: str) -> bool:
"""Verify password against hash."""
return bcrypt.checkpw(password.encode(), hashed.encode())
@staticmethod
def validate_password_strength(password: str) -> bool:
"""Validate password meets security requirements."""
if len(password) < 12:
return False
if not any(c.isupper() for c in password):
return False
if not any(c.islower() for c in password):
return False
if not any(c.isdigit() for c in password):
return False
if not any(c in "!@#$%^&*()-_=+[]{}|;:,.<>?" for c in password):
return False
return True
Sensitive Data Handling¶
PII Protection¶
Keep the sensitive values in private fields (a name starting with _: not in the
schema, nor in the where and orderBy inputs), and expose them through field
resolvers that check who asks:
import fraiseql
from fraiseql.security import authorize_field
from fraiseql.types import ID
@fraiseql.type
class UserGQL:
id: ID
email: str
name: str
_ssn: str | None = None # private: not in the schema
# Only admins can see the full SSN
@fraiseql.field
@authorize_field(lambda info: info.context["user"].has_role("admin"))
async def ssn(self, info) -> str | None:
return self._ssn
# Everyone sees the masked version
@fraiseql.field
async def ssn_masked(self, info) -> str | None:
return f"***-**-{self._ssn[-4:]}" if self._ssn else None
def to_graphql(row: dict) -> UserGQL:
return UserGQL(id=row["id"], email=row["email"], name=row["name"], _ssn=row.get("ssn"))
A denied ssn is null, with the error Not authorized to access field 'ssn'
(code FIELD_AUTHORIZATION_ERROR). These resolvers run when graphql-core resolves the
object, as for a resolver that returns UserGQL instances.
Data Encryption¶
from cryptography.fernet import Fernet
import os
class FieldEncryption:
"""Encrypt sensitive database fields."""
def __init__(self):
key = os.getenv("ENCRYPTION_KEY") # Store in secrets manager
self.cipher = Fernet(key.encode())
def encrypt(self, value: str) -> str:
"""Encrypt field value."""
return self.cipher.encrypt(value.encode()).decode()
def decrypt(self, encrypted: str) -> str:
"""Decrypt field value."""
return self.cipher.decrypt(encrypted.encode()).decode()
# Usage
encryptor = FieldEncryption()
# Store encrypted (conn: a psycopg connection, e.g. from db.get_pool().connection())
encrypted_ssn = encryptor.encrypt("123-45-6789")
await conn.execute(
"INSERT INTO users (id, ssn_encrypted) VALUES (%s, %s)",
(user_id, encrypted_ssn)
)
# Retrieve and decrypt
result = await conn.execute("SELECT ssn_encrypted FROM users WHERE id = %s", (user_id,))
encrypted = (await result.fetchone())[0]
ssn = encryptor.decrypt(encrypted)
Audit Logging¶
Security Event Logging¶
import fraiseql
from fraiseql.audit import get_security_logger, SecurityEventType, SecurityEventSeverity
security_logger = get_security_logger()
# Log authentication events
@fraiseql.mutation
async def login(info, username: str, password: str) -> dict:
try:
user = await authenticate_user(username, password)
security_logger.log_auth_success(
user_id=user.id,
user_email=user.email,
metadata={"ip": info.context["request"].client.host}
)
return {"token": generate_token(user)}
except AuthenticationError as e:
security_logger.log_auth_failure(
reason=str(e),
metadata={
"username": username,
"ip": info.context["request"].client.host
}
)
raise
# Log data access
@fraiseql.query
@requires_permission("pii:read")
async def get_user_pii(info, user_id: str) -> UserPII:
user = await fetch_user_pii(user_id)
security_logger.log_event(
SecurityEvent(
event_type=SecurityEventType.DATA_ACCESS,
severity=SecurityEventSeverity.INFO,
user_id=info.context["user"].user_id,
metadata={
"accessed_user": user_id,
"pii_fields": ["ssn", "credit_card"]
}
)
)
return user
Entity Change Log¶
import fraiseql
# Automatic audit trail via PostgreSQL trigger
# See advanced/event-sourcing.md for complete implementation
@fraiseql.mutation
async def update_order_status(info, order_id: str, status: str) -> Order:
"""Update order status - automatically logged."""
user_id = info.context["user"].user_id
db = info.context["db"]
async with db.get_pool().connection() as conn:
# Set user context for trigger (transaction-local, like SET LOCAL)
await conn.execute(
"SELECT set_config('app.current_user_id', %s, true)",
(str(user_id),)
)
# Update (trigger logs before/after state)
await conn.execute(
"UPDATE orders SET status = %s WHERE id = %s",
(status, order_id)
)
# The pool commits when the block exits
return await db.find_one(
"v_order", "updateOrderStatus", info, mandatory_filters={"id": order_id}
)
Compliance¶
GDPR Compliance¶
import fraiseql
@fraiseql.mutation
@requires_auth
async def export_my_data(info) -> str:
"""GDPR: Export all user data."""
user_id = info.context["user"].user_id
# Gather all user data
data = {
"user": await fetch_user(user_id),
"orders": await fetch_user_orders(user_id),
"activity": await fetch_user_activity(user_id),
"consents": await fetch_user_consents(user_id)
}
# Log export
security_logger.log_event(
SecurityEvent(
event_type=SecurityEventType.DATA_EXPORT,
severity=SecurityEventSeverity.INFO,
user_id=user_id
)
)
return json.dumps(data, default=str)
@fraiseql.mutation
@requires_auth
async def delete_my_account(info) -> bool:
"""GDPR: Right to be forgotten."""
user_id = info.context["user"].user_id
async def forget_user(conn):
# Anonymize or delete data
await conn.execute(
"UPDATE users SET email = %s, name = %s, deleted_at = NOW() WHERE id = %s",
(f"deleted-{user_id}@deleted.com", "Deleted User", user_id)
)
# Delete related data
await conn.execute("DELETE FROM user_sessions WHERE user_id = %s", (user_id,))
await conn.execute("DELETE FROM user_consents WHERE user_id = %s", (user_id,))
# One transaction: everything or nothing
await info.context["db"].run_in_transaction(forget_user)
# Log deletion
security_logger.log_event(
SecurityEvent(
event_type=SecurityEventType.DATA_DELETION,
severity=SecurityEventSeverity.WARNING,
user_id=user_id
)
)
return True
SOC2 Controls¶
import fraiseql
# Access control matrix
ROLE_PERMISSIONS = {
"user": ["orders:read:self", "profile:write:self"],
"manager": ["orders:read:team", "users:read:team"],
"admin": ["admin:all"]
}
# Audit all administrative actions
@fraiseql.mutation
@requires_role("admin")
async def admin_update_user(info, user_id: str, data: dict) -> User:
"""Admin action - fully audited."""
admin_user = info.context["user"]
# Log before change
before_state = await fetch_user(user_id)
# Perform change
updated_user = await update_user(user_id, data)
# Log after change
security_logger.log_event(
SecurityEvent(
event_type=SecurityEventType.ADMIN_ACTION,
severity=SecurityEventSeverity.WARNING,
user_id=admin_user.user_id,
metadata={
"action": "update_user",
"target_user": user_id,
"before": before_state,
"after": updated_user,
"changed_fields": list(data.keys())
}
)
)
return updated_user
Next Steps¶
- Security Example - Complete security implementation
- Authentication - Authentication patterns
- Monitoring - Security monitoring
- Deployment - Secure deployment
- Audit Logging - Complete audit trails