Security Deep Dive: Auth, 2FA, WAF & Rate Limiting

Why Security Matters

Before we look at Grit's security features, let's understand what we're defending against. Here are the most common attacks against web applications:

• • Brute Force: An attacker tries thousands of password combinations until one works. Without rate limiting, they can try millions of passwords per hour
• • SQL Injection: An attacker sends malicious SQL in form fields or URL parameters, tricking the database into executing unintended commands. Can dump your entire database
• • XSS (Cross-Site Scripting): An attacker injects JavaScript into your pages that runs in other users' browsers, stealing cookies, tokens, or personal data
• • CSRF (Cross-Site Request Forgery): An attacker tricks a logged-in user's browser into making requests to your API — transferring money, changing passwords, deleting data
• • Credential Stuffing: Attackers use leaked email/password combinations from other breaches to try logging into your app. Most people reuse passwords across sites

Layer 1: Password Security (bcrypt)

The most fundamental security rule: never store passwords in plain text. If an attacker gains access to your database (through SQL injection, a backup leak, or an insider threat), plain text passwords give them immediate access to every account. Instead, Grit stores passwords as one-way hashes.

Here's the process when a user registers:

1. 1.User submits password: myPassword123
2. 2.bcrypt generates a random salt: $2a$10$N9qo8uLOickgx2ZMRZoMye
3. 3.bcrypt hashes password + salt through 1,024 iterations
4. 4.Result stored in database: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

// Hashing a password during registration
hashedPassword, err := bcrypt.GenerateFromPassword(
    []byte(input.Password),
    bcrypt.DefaultCost, // Cost factor 10 = 2^10 iterations
)

// Verifying a password during login
err := bcrypt.CompareHashAndPassword(
    []byte(user.Password), // stored hash
    []byte(input.Password), // submitted password
)

Layer 2: JWT Authentication

After verifying a password, Grit issues two tokens: an access token (short-lived, 15 minutes) and a refresh token (long-lived, 7 days). This dual-token approach limits the damage if a token is stolen.

Why two tokens? If an access token is intercepted by an attacker, it only works for 15 minutes. The refresh token is stored in an HTTP-only cookie (inaccessible to JavaScript), so XSS attacks cannot steal it. When the access token expires, the frontend silently uses the refresh token to get a new one.

Login successful
  ├── Access Token (JWT, 15 min expiry)
  │   └── Sent in Authorization header: Bearer <token>
  │   └── Contains: user ID, email, role
  │   └── Stateless — no database lookup needed
  │
  └── Refresh Token (JWT, 7 day expiry)
      └── Stored in HTTP-only cookie
      └── Used only to get new access tokens
      └── Cannot be read by JavaScript (XSS protection)

The auth middleware runs on every protected route. It extracts the JWT from the Authorization header, verifies the signature, checks the expiration, and attaches the user information to the request context.

Layer 3: Role-Based Access Control

Authentication answers "who are you?" Authorization answers "what are you allowed to do?" Grit uses role-based access control (RBAC) with three built-in roles:

The RequireRole middleware enforces access control at the route level:

// Public routes — no auth required
auth := api.Group("/auth")
auth.POST("/login", h.Login)
auth.POST("/register", h.Register)

// Protected routes — any authenticated user
users := api.Group("/users")
users.Use(middleware.AuthMiddleware(cfg))
users.GET("/me", h.GetMe)

// Admin-only routes
admin := api.Group("/admin")
admin.Use(middleware.AuthMiddleware(cfg))
admin.Use(middleware.RequireRole("ADMIN"))
admin.GET("/users", h.ListUsers)
admin.DELETE("/users/:id", h.DeleteUser)

Layer 4: Two-Factor Authentication (TOTP)

Passwords can be stolen through phishing, keyloggers, or data breaches. Two-factor authentication (2FA) adds a second layer: something you know (password) plus something you have (your phone). Even if an attacker has your password, they cannot log in without your phone.

The 2FA setup flow in Grit:

1. 1.Generate secret. The API creates a random TOTP secret and returns it as a QR code URL.
2. 2.Scan QR code. The user scans the QR code with their authenticator app, which stores the secret.
3. 3.Verify code. The user enters the current 6-digit code from their app to prove it's working.
4. 4.2FA enabled. The secret is saved to the database. Future logins require both password and TOTP code.

Step 1: POST /api/auth/login
  Body: { "email": "user@example.com", "password": "..." }
  Response: { "requires_2fa": true, "temp_token": "..." }

Step 2: POST /api/auth/verify-2fa
  Body: { "temp_token": "...", "code": "482917" }
  Response: { "access_token": "...", "refresh_token": "..." }

Layer 5: Backup Codes

What happens if you lose your phone? Without backup codes, you're locked out of your account forever. Grit generates 10 one-time backup codes when 2FA is enabled. Each code can be used exactly once as a substitute for the TOTP code.

Backup codes are:

• • 10 codes generated when 2FA is enabled
• • One-time use — each code is invalidated after use
• • bcrypt-hashed in the database — if the database is compromised, the raw codes are not exposed
• • Shown once — the user sees the plain text codes only at generation time and must save them

Your backup codes (save these somewhere safe):

1.  a8f2-k9m3-p4x7
2.  b3n6-j7w2-q8r1
3.  c5t9-h1y4-s6v3
4.  d2p8-g3z7-u9e5
5.  e7k1-f6x4-w2m8
6.  f4j3-e9n6-y7t2
7.  g1w7-d2p5-z3k9
8.  h8y4-c7m1-a6j3
9.  i6z2-b4t8-e1w5
10. j3x9-a1s7-f4n6

Each code can only be used once.
Store them in a password manager or print them.

Layer 6: Trusted Devices

Entering a 2FA code every time you log in on the same computer gets annoying fast. Trusted devices solve this: after you verify 2FA once, the server sets a 30-day cookie on your browser. On subsequent logins from that device, the 2FA step is skipped.

The trusted device cookie is:

• • Secure — only sent over HTTPS (in production)
• • HTTP-only — JavaScript cannot read it (XSS protection)
• • 30-day expiry — after 30 days, you'll need to enter a 2FA code again
• • Per-device — trusting your laptop does not trust your phone's browser

Layer 7: Sentinel WAF

Grit includes Sentinel, a built-in WAF that runs as middleware. It inspects every request and blocks:

• • SQL injection patterns — detects ' OR 1=1 --, UNION SELECT, and other injection attempts in query parameters and request bodies
• • XSS attempts — blocks <script> tags, event handlers like onerror=, and other JavaScript injection vectors
• • Suspicious user agents — blocks known attack tools like sqlmap, nikto, and dirbuster
• • Path traversal — blocks attempts to access files outside the web root using ../../

Sentinel also includes a dashboard at /sentinel/ui where you can see:

• • Total requests processed
• • Blocked requests and the reasons they were blocked
• • Top attacking IPs
• • Attack type distribution

Layer 8: Rate Limiting

Grit's Sentinel middleware includes configurable rate limiting. Limits are applied per IP address and can be configured per route or globally:

// Default rate limits in Grit
Global:     100 requests per minute per IP
Auth:       10 requests per minute per IP (login, register)
Upload:     20 requests per minute per IP
API:        60 requests per minute per IP

// When a client exceeds the limit:
// HTTP 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retry_after": 45
    }
  }
}

The auth endpoints have a stricter limit (10/minute) because brute force attacks target login endpoints. An attacker trying 10,000 passwords per minute would be blocked after the first 10 attempts.

Layer 9: Security Headers

HTTP response headers can instruct browsers to enable security features. Grit sets these headers on every response:

Layer 10: JWT Secret Management

The JWT secret is the key used to sign and verify tokens. If an attacker knows your secret, they can forge tokens for any user — including admin accounts. The secret must be:

• • Long — at least 32 characters (256 bits)
• • Random — generated by a cryptographic random number generator, not a human-chosen phrase
• • Secret — stored in environment variables, never committed to Git
• • Unique per environment — development, staging, and production should each have different secrets

# Generate a 64-character hex string (256 bits of entropy)
openssl rand -hex 32

# Example output:
# a3f8b2c1e9d7f4a6b8c2e1d3f5a7b9c1e3d5f7a9b1c3e5d7f9a1b3c5e7d9f1a3

# Add to your .env file (NEVER commit this file)
JWT_SECRET=a3f8b2c1e9d7f4a6b8c2e1d3f5a7b9c1e3d5f7a9b1c3e5d7f9a1b3c5e7d9f1a3

OAuth2 Security

Social login (Google, GitHub, etc.) is not just convenient — it's a security feature. When users log in with Google, your application never sees their password. This prevents:

• • Password reuse attacks — if a user's password is leaked from another site, your app is unaffected because you never stored a password
• • Phishing — users authenticate on Google's domain, not on a page you control, so fake login pages are harder to create
• • Weak passwords — Google enforces its own password policies and 2FA, which are typically stronger than what most apps enforce

Grit links OAuth accounts by email. If a user registers with email/password and later logs in with Google using the same email, the accounts are automatically linked. One user, multiple login methods.

Summary: The 10-Layer Security Stack