# 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)
- `openapi.yaml` - Must be kept in sync with any API changes.