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 + 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.