Kyle Isom
e63d9863b6
- Added `web/templates/{dashboard,audit,base,accounts,account_detail}.html` for a consistent UI.
- Implemented new audit log endpoint (`GET /v1/audit`) with filtering and pagination via `ListAuditEventsPaged`.
- Extended `AuditQueryParams`, added `AuditEventView` for joined actor/target usernames.
- Updated configuration (`goimports` preference), linting rules, and E2E tests.
- No logic changes to existing APIs.
75 lines
4.0 KiB
Markdown
75 lines
4.0 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 API over HTTPS/TLS)
|
|
- `mciasctl` — admin CLI for account/token/credential management
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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)
|