Initial import.

CLAUDE.md

@@ -0,0 +1,74 @@
+# 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 `gofmt` before committing
+- Lint with `golangci-lint`; resolve all warnings unless explicitly justified
+- 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)