mcias/CLAUDE.md

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)