Kyle Isom
ec7c966ad2
- Trusted proxy config option for proxy-aware IP extraction used by rate limiting and audit logs; validates proxy IP before trusting X-Forwarded-For / X-Real-IP headers - TOTP replay protection via counter-based validation to reject reused codes within the same time step (±30s) - RateLimit middleware updated to extract client IP from proxy headers without IP spoofing risk - New tests for ClientIP proxy logic (spoofed headers, fallback) and extended rate-limit proxy coverage - HTMX error banner script integrated into web UI base - .gitignore updated for mciasdb build artifact Security: resolves CRIT-01 (TOTP replay attack) and DEF-03 (proxy-unaware rate limiting); gRPC TOTP enrollment aligned with REST via StorePendingTOTP Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Project Overview
|
|
|
|
MCIAS (Metacircular Identity and Access System) is a single-sign-on (SSO) and Identity & Access Management (IAM) system for personal projects. The target audience is a single developer building personal apps, with support for onboarding friends onto those apps.
|
|
|
|
**Priorities (in order):** security, robustness, correctness. Performance is secondary.
|
|
|
|
## Tech Stack
|
|
|
|
- **Language:** Go
|
|
- **Database:** SQLite
|
|
- **Logging/Utilities:** git.wntrmute.dev/kyle/goutils
|
|
- **Crypto:** Ed25519 (signatures), Argon2 (password hashing)
|
|
- **Tokens:** JWT signed with Ed25519 (algorithm: EdDSA); always validate the `alg` header on receipt — never accept `none` or symmetric algorithms
|
|
- **Auth:** Username/password + optional TOTP; future FIDO/Yubikey support
|
|
|
|
## Binaries
|
|
|
|
- `mciassrv` — authentication server (REST + gRPC over HTTPS/TLS, with HTMX web UI)
|
|
- `mciasctl` — admin CLI for account/token/credential/policy management (REST)
|
|
- `mciasdb` — offline SQLite maintenance tool (schema, accounts, tokens, audit, pgcreds)
|
|
- `mciasgrpcctl` — admin CLI for gRPC interface
|
|
|
|
## Development Workflow
|
|
|
|
If PROGRESS.md does not yet exist, create it before proceeding. It is the source of truth for current state.
|
|
|
|
1. Check PROGRESS.md for current state and next steps
|
|
2. Define discrete next steps with actionable acceptance criteria
|
|
3. Implement, adversarially verify correctness, write tests
|
|
4. Commit to git, update PROGRESS.md
|
|
5. Repeat
|
|
|
|
When instructed to checkpoint:
|
|
- Verify that the project lints cleanly.
|
|
- Verify that the project unit tests complete successfully.
|
|
- Ensure that all integration and end-to-end tests complete successfully.
|
|
- Commit to git and update PROGRESS.md.
|
|
|
|
## Security Constraints
|
|
|
|
This is a security-critical project. The following rules are non-negotiable:
|
|
|
|
- Never implement custom crypto. Use standard library (`crypto/...`) or well-audited packages only.
|
|
- Always validate the `alg` header in JWTs before processing; reject `none` and any non-EdDSA algorithm.
|
|
- Argon2id parameters must meet current OWASP recommendations; never reduce them for convenience.
|
|
- Credential storage (passwords, tokens, secrets) must never appear in logs, error messages, or API responses.
|
|
- Any code touching authentication flows, token issuance/validation, or credential storage must include a comment citing the rationale for each security decision.
|
|
- When in doubt about a crypto or auth decision, halt and ask rather than guess.
|
|
- Review all crypto primitives against current best practices before use; flag any deviation in the commit body.
|
|
|
|
## Testing Requirements
|
|
|
|
- Tests live alongside source in the same package, using the `_test.go` suffix
|
|
- Run with `go test ./...`; CI must pass with zero failures
|
|
- Unit tests for all exported functions and security-critical internal functions
|
|
- Integration tests for all subsystems (database layer, token issuance, auth flows)
|
|
- End-to-end tests for complete login, token renewal, and revocation flows
|
|
- Adversarially verify all outputs: test invalid inputs, boundary conditions, and known attack patterns (e.g., JWT `alg` confusion, timing attacks on credential comparison)
|
|
- Use `crypto/subtle.ConstantTimeCompare` wherever token or credential equality is checked
|
|
|
|
## Git Commit Style
|
|
|
|
- First line: single line, max 55 characters
|
|
- Body (optional): bullet points describing work done
|
|
- Security-sensitive changes (crypto primitives, auth flows, token handling, credential storage, session management) must be explicitly flagged in the commit body with a `Security:` line describing what changed and why it is safe
|
|
|
|
## Go Conventions
|
|
|
|
- Format all code with `goimports` before committing
|
|
- Lint with `golangci-lint`; resolve all warnings unless explicitly justified. This must be done after every step.
|
|
- Wrap errors with `fmt.Errorf("context: %w", err)` to preserve stack context
|
|
- Prefer explicit error handling over panics; never silently discard errors
|
|
- Use `log/slog` (or goutils equivalents) for structured logging; never `fmt.Println` in production paths
|
|
|
|
## Verification
|
|
|
|
After any code edit, always verify the fix by running `go build ./...` and `go test ./...` before claiming the issue is resolved. Never claim lint/tests pass without actually running them.
|
|
|
|
## Database
|
|
|
|
When working with migrations (golang-migrate or SQLite), always test migrations against a fresh database AND an existing database to catch duplicate column/table errors. SQLite does not support IF NOT EXISTS for ALTER TABLE.
|
|
|
|
## File Editing
|
|
|
|
Before editing files, re-read the current on-disk version to confirm it matches expectations. If files seem inconsistent, stop and flag this to the user before proceeding.
|
|
|
|
## Project Context
|
|
|
|
For this project (MCIAS): Go codebase, uses golang-migrate, SQLite (with shared-cache for in-memory), htmx frontend with Go html/template, golangci-lint (use `go vet` if version incompatible), and cert tool for TLS certificates. Check `docs/` for tool-specific usage before guessing CLI flags.
|
|
|
|
## UI Development
|
|
|
|
When implementing UI features, ensure they work for the empty-state case (e.g., no credentials exist yet, no accounts created). Always test with zero records.
|
|
|
|
## Key Documents
|
|
|
|
- `PROJECT.md` — Project specifications and requirements
|
|
- `ARCHITECTURE.md` — **Required before any implementation.** Covers token lifecycle, session management, multi-app trust boundaries, and database schema. Do not generate code until this document exists.
|
|
- `PROJECT_PLAN.md` — Discrete implementation steps (to be written)
|
|
- `PROGRESS.md` — Development progress tracking (to be written)
|
|
- `openapi.yaml` - Must be kept in sync with any API changes.
|