66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# Claude Code Guidelines for Clinch
|
|
|
|
This document provides guidelines for AI assistants (Claude, ChatGPT, etc.) working on this codebase.
|
|
|
|
## Project Context
|
|
|
|
Clinch is a lightweight identity provider (IdP) supporting:
|
|
- **OIDC/OAuth2** - Standard OAuth flows for modern apps
|
|
- **ForwardAuth** - Trusted-header SSO for reverse proxies (Traefik, Caddy, Nginx)
|
|
- **WebAuthn/Passkeys** - Passwordless authentication
|
|
- Group-based access control
|
|
|
|
Key characteristics:
|
|
- Rails 8 application with SQLite database
|
|
- Focus on simplicity and self-hosting
|
|
- No external dependencies for core functionality
|
|
|
|
## Testing Guidelines
|
|
|
|
### Do Not Test Rails Framework Functionality
|
|
|
|
When writing tests, focus on testing **our application's specific behavior and logic**, not standard Rails framework functionality.
|
|
|
|
**Examples of what NOT to test:**
|
|
- Session isolation between users (Rails handles this)
|
|
- Basic ActiveRecord associations (Rails handles this)
|
|
- Standard cookie signing/verification (Rails handles this)
|
|
- Default controller rendering behavior (Rails handles this)
|
|
- Infrastructure-level error handling (database connection failures, network issues, etc.)
|
|
|
|
**Examples of what TO test:**
|
|
- Forward auth business logic (group-based access control, header configuration, etc.)
|
|
- Custom authentication flows
|
|
- Application-specific session expiration behavior
|
|
- Domain pattern matching logic
|
|
- Custom response header generation
|
|
|
|
**Why:**
|
|
Testing Rails framework functionality adds no value and can create maintenance burden. Trust that Rails works correctly and focus tests on verifying our application's unique behavior.
|
|
|
|
### Integration Test Patterns
|
|
|
|
**Session handling:**
|
|
- Do NOT manually manipulate cookies in integration tests
|
|
- Use the session provided by the test framework
|
|
- To get the actual session ID, use `Session.last.id` after sign-in, not `cookies[:session_id]` (which is signed)
|
|
|
|
**Application setup:**
|
|
- Always create Application records for the domains you're testing
|
|
- Use wildcard patterns (e.g., `*.example.com`) when testing multiple subdomains
|
|
- Remember: `*` matches one level only (`*.example.com` matches `app.example.com` but NOT `sub.app.example.com`)
|
|
|
|
**Header assertions:**
|
|
- Always normalize header names to lowercase when asserting (HTTP headers are case-insensitive)
|
|
- Use `response.headers["x-remote-user"]` not `response.headers["X-Remote-User"]`
|
|
|
|
**Avoid threading in integration tests:**
|
|
- Rails integration tests use a single cookie jar
|
|
- Convert threaded tests to sequential requests instead
|
|
|
|
### Common Testing Pitfalls
|
|
|
|
1. **Don't test concurrent users with manual cookie manipulation** - Integration tests can't properly simulate multiple concurrent sessions
|
|
2. **Don't expect `cookies[:session_id]` to be the actual ID** - It's a signed cookie value
|
|
3. **Don't assume wildcard patterns match multiple levels** - `*.domain.com` only matches one level
|