mcias/PROJECT_PLAN.md

MCIAS Project Plan

Discrete implementation steps with acceptance criteria. See ARCHITECTURE.md for design rationale.

---

Phase 0 — Repository Bootstrap

Step 0.1: Go module and dependency setup

Acceptance criteria:

• go.mod exists with module path git.wntrmute.dev/kyle/mcias
• Required dependencies declared: modernc.org/sqlite (CGo-free SQLite), golang.org/x/crypto (Argon2, Ed25519 helpers), github.com/golang-jwt/jwt/v5, github.com/pelletier/go-toml/v2, github.com/google/uuid, git.wntrmute.dev/kyle/goutils
• go mod tidy succeeds; go build ./... succeeds on empty stubs

Step 0.2: .gitignore

Acceptance criteria:

• .gitignore excludes: build output (mciassrv, mciasctl), *.db, *.db-wal, *.db-shm, test coverage files, editor artifacts

---

Phase 1 — Foundational Packages

Step 1.1: internal/model — shared data types

Acceptance criteria:

• Account, Role, Token, AuditEvent, PGCredential structs defined
• Account types and statuses as typed constants
• No external dependencies (pure data definitions)
• Tests: struct instantiation and constant validation

Step 1.2: internal/config — configuration loading

Acceptance criteria:

• TOML config parsed into a Config struct matching ARCHITECTURE.md §11
• Validation: required fields present, listen_addr parseable, TLS paths non-empty, Argon2 params within safe bounds (memory >= 64MB, time >= 2)
• Master key config: exactly one of passphrase_env or keyfile set
• Tests: valid config round-trips; missing required field → error; unsafe Argon2 params rejected

Step 1.3: internal/crypto — key management and encryption helpers

Acceptance criteria:

• GenerateEd25519KeyPair() (crypto/ed25519.PublicKey, crypto/ed25519.PrivateKey, error)
• MarshalPrivateKeyPEM(key crypto/ed25519.PrivateKey) ([]byte, error) (PKCS#8)
• ParsePrivateKeyPEM(pemData []byte) (crypto/ed25519.PrivateKey, error)
• SealAESGCM(key, plaintext []byte) (ciphertext, nonce []byte, err error)
• OpenAESGCM(key, nonce, ciphertext []byte) ([]byte, error)
• DeriveKey(passphrase string, salt []byte) ([]byte, error) — Argon2id KDF for master key derivation (separate from password hashing)
• Key is always 32 bytes (AES-256)
• crypto/rand used for all nonce/salt generation
• Tests: seal/open round-trip; open with wrong key → error; PEM round-trip; nonces are unique across calls

Step 1.4: internal/db — database layer

Acceptance criteria:

• Open(path string) (*DB, error) opens/creates SQLite DB with WAL mode and foreign keys enabled
• Migrate(db *DB) error applies schema from ARCHITECTURE.md §9 idempotently (version table tracks applied migrations)
• CRUD for accounts, account_roles, token_revocation, system_tokens, pg_credentials, audit_log, server_config
• All queries use prepared statements (no string concatenation)
• Tests: in-memory SQLite (:memory:); each CRUD operation; FK constraint enforcement; migration idempotency

---

Phase 2 — Authentication Core

Step 2.1: internal/token — JWT issuance and validation

Acceptance criteria:

• IssueToken(key ed25519.PrivateKey, claims Claims) (string, error)
  • Header: {"alg":"EdDSA","typ":"JWT"}
  • Claims: iss, sub, iat, exp, jti (UUID), roles
• ValidateToken(key ed25519.PublicKey, tokenString string) (Claims, error)
  • Must check alg header before any other processing; reject non-EdDSA
  • Validates exp, iat, iss, jti presence
  • Returns structured error types for: expired, invalid signature, wrong alg, missing claim
• RevokeToken(db *DB, jti string, reason string) error
• PruneExpiredTokens(db *DB) (int64, error) — removes rows past expiry
• Tests: happy path; expired token rejected; wrong alg (none/HS256/RS256) rejected; tampered signature rejected; missing jti rejected; revoked token checked by caller; pruning removes only expired rows

Step 2.2: internal/auth — login and credential verification

Acceptance criteria:

• HashPassword(password string, params ArgonParams) (string, error) — returns PHC-format string
• VerifyPassword(password, hash string) (bool, error) — constant-time; re-hashes if params differ (upgrade path)
• ValidateTOTP(secret []byte, code string) (bool, error) — RFC 6238, 1-window tolerance, constant-time
• Login(ctx, db, key, cfg, req LoginRequest) (LoginResponse, error)
  • Orchestrates: load account → verify status → verify password → verify TOTP (if required) → issue JWT → write token_revocation row → write audit_log
  • On any failure: write audit_log (login_fail or login_totp_fail); return generic error to caller (no information about which step failed)
• Tests: successful login; wrong password (timing: compare duration against a threshold — at minimum assert no short-circuit); wrong TOTP; suspended account; deleted account; TOTP enrolled but not provided; constant-time comparison verified (both branches take comparable time)

---

Phase 3 — HTTP Server

Step 3.1: internal/middleware — HTTP middleware

Acceptance criteria:

• RequestLogger — logs method, path, status, duration, IP
• RequireAuth(key ed25519.PublicKey, db *DB) — extracts Bearer token, validates, checks revocation, injects claims into context; returns 401 on failure
• RequireRole(role string) — checks claims from context for role; returns 403 on failure
• RateLimit(rps float64, burst int) — per-IP token bucket; returns 429 on limit exceeded
• Tests: logger captures fields; RequireAuth rejects missing/invalid/revoked tokens; RequireRole rejects insufficient roles; RateLimit triggers after burst exceeded

Step 3.2: internal/server — HTTP handlers and router

Acceptance criteria:

• Router wired per ARCHITECTURE.md §8 (all endpoints listed)
• POST /v1/auth/login — delegates to auth.Login; returns {token, expires_at}
• POST /v1/auth/logout — revokes current token from context; 204
• POST /v1/auth/renew — validates current token, issues new one, revokes old
• POST /v1/token/validate — validates submitted token; returns claims
• DELETE /v1/token/{jti} — admin or role-scoped; revokes by JTI
• GET /v1/health — 200 {"status":"ok"}
• GET /v1/keys/public — returns Ed25519 public key as JWK
• POST /v1/accounts — admin; creates account
• GET /v1/accounts — admin; lists accounts (no password hashes in response)
• GET /v1/accounts/{id} — admin; single account
• PATCH /v1/accounts/{id} — admin; update status/fields
• DELETE /v1/accounts/{id} — admin; soft-delete + revoke all tokens
• GET|PUT /v1/accounts/{id}/roles — admin; get/replace role set
• POST /v1/auth/totp/enroll — returns TOTP secret + otpauth URI
• POST /v1/auth/totp/confirm — confirms TOTP enrollment
• DELETE /v1/auth/totp — admin; removes TOTP from account
• GET|PUT /v1/accounts/{id}/pgcreds — get/set Postgres credentials
• Credential fields (password hash, TOTP secret, Postgres password) are never included in any API response
• Tests: each endpoint happy path; auth middleware applied correctly; invalid JSON body → 400; credential fields absent from all responses

Step 3.3: cmd/mciassrv — server binary

Acceptance criteria:

• Reads config file path from --config flag
• Loads config, derives master key, opens DB, runs migrations, loads/generates signing key
• Starts HTTPS listener on configured address
• Graceful shutdown on SIGINT/SIGTERM (30s drain)
• If no signing key exists in DB, generates one and stores it encrypted
• Integration test: start server on random port, hit /v1/health, assert 200

---

Phase 4 — Admin CLI

Step 4.1: cmd/mciasctl — admin CLI

Acceptance criteria:

• Subcommands:
  • mciasctl account create --username NAME --type human|system
  • mciasctl account list
  • mciasctl account suspend --id UUID
  • mciasctl account delete --id UUID
  • mciasctl role grant --account UUID --role ROLE
  • mciasctl role revoke --account UUID --role ROLE
  • mciasctl token issue --account UUID (system accounts)
  • mciasctl token revoke --jti JTI
  • mciasctl pgcreds set --account UUID --host H --port P --db D --user U --password P
  • mciasctl pgcreds get --account UUID
• CLI reads admin JWT from MCIAS_ADMIN_TOKEN env var or --token flag
• All commands make HTTPS requests to mciassrv (base URL from --server flag or MCIAS_SERVER env var)
• Tests: flag parsing; missing required flags → error; help text complete

---

Phase 5 — End-to-End Tests and Hardening

Step 5.1: End-to-end test suite

Acceptance criteria:

• TestE2ELoginLogout — create account, login, validate token, logout, validate token again (must fail)
• TestE2ETokenRenewal — login, renew, old token rejected, new token valid
• TestE2EAdminFlow — create account via CLI, assign role, login as user
• TestE2ETOTPFlow — enroll TOTP, login without code (fail), login with code (succeed)
• TestE2ESystemAccount — create system account, issue token, validate token, rotate token (old token rejected)
• TestE2EAlgConfusion — attempt login, forge token with alg=HS256/none, submit to validate endpoint, assert 401

Step 5.2: Security hardening review

Acceptance criteria:

• golangci-lint run ./... passes with zero warnings
• go test -race ./... passes with zero race conditions
• Manual review checklist:
  • No password/token/secret in any log line (grep audit)
  • All crypto/rand — no math/rand usage
  • All token comparisons use crypto/subtle
  • Argon2id params meet OWASP minimums
  • JWT alg validated before signature check in all code paths
  • All DB queries use parameterized statements
  • TLS min version enforced in server config

Step 5.3: Documentation and commit

Acceptance criteria:

• README.md updated with: build instructions, config file example, first-run steps
• Each phase committed separately with appropriate commit messages
• PROGRESS.md reflects completed state

---

Phase 6 — mciasdb: Database Maintenance Tool

See ARCHITECTURE.md §16 for full design rationale, trust model, and command surface.

Step 6.1: cmd/mciasdb — binary skeleton and config loading

Acceptance criteria:

• Binary at cmd/mciasdb/main.go parses --config flag
• Loads [database] and [master_key] sections from mciassrv config format
• Derives master key (passphrase or keyfile, identical logic to mciassrv)
• Opens SQLite DB with WAL mode and FK enforcement (reuses internal/db)
• Exits with error if DB cannot be opened (e.g., busy-timeout exceeded)
• Help text lists all subcommands

Step 6.2: Schema subcommands

Acceptance criteria:

• mciasdb schema verify — opens DB, reports current schema version, exits 0 if up-to-date, exits 1 if migrations pending
• mciasdb schema migrate — applies any pending migrations, reports each one applied, exits 0
• Tests: verify on fresh DB reports version 0; migrate advances to current version; verify after migrate exits 0

Step 6.3: Account and role subcommands

Acceptance criteria:

• mciasdb account list — prints uuid, username, type, status for all accounts
• mciasdb account get --id UUID — prints single account record
• mciasdb account create --username NAME --type human|system — inserts row, prints new UUID
• mciasdb account set-password --id UUID — prompts twice (confirm), re-hashes with Argon2id, updates row; no --password flag permitted
• mciasdb account set-status --id UUID --status STATUS — updates status
• mciasdb account reset-totp --id UUID — clears totp_required and totp_secret_enc
• mciasdb role list --id UUID — prints roles
• mciasdb role grant --id UUID --role ROLE — inserts role row
• mciasdb role revoke --id UUID --role ROLE — deletes role row
• All write operations append an audit log row with actor tagged mciasdb
• Tests: each subcommand happy path against in-memory SQLite; unknown UUID returns error; set-password with mismatched confirmation returns error

Step 6.4: Token subcommands

Acceptance criteria:

• mciasdb token list --id UUID — prints jti, issued_at, expires_at, revoked_at for account
• mciasdb token revoke --jti JTI — sets revoked_at = now on the row
• mciasdb token revoke-all --id UUID — revokes all non-revoked tokens for account
• mciasdb prune tokens — deletes rows from token_revocation where expires_at < now; prints count removed
• All write operations append an audit log row
• Tests: revoke on unknown JTI returns error; revoke-all on account with no active tokens is a no-op (exits 0); prune removes only expired rows

Step 6.5: Audit log subcommands

Acceptance criteria:

• mciasdb audit tail [--n N] — prints last N events (default 50), newest last
• mciasdb audit query --account UUID — filters by actor_id or target_id
• mciasdb audit query --type EVENT_TYPE — filters by event_type
• mciasdb audit query --since TIMESTAMP — filters by event_time >= RFC-3339 timestamp
• Flags are combinable (AND semantics)
• --json flag on any audit subcommand emits newline-delimited JSON
• Tests: tail returns correct count; query filters correctly; --json output is valid JSON

Step 6.6: Postgres credentials subcommands

Acceptance criteria:

• mciasdb pgcreds get --id UUID — decrypts and prints host, port, db, username, password with a warning header that output is sensitive
• mciasdb pgcreds set --id UUID --host H --port P --db D --user U — prompts for password interactively (no --password flag), encrypts with AES-256-GCM, stores row
• All write operations append an audit log row
• Tests: get on account with no pgcreds returns error; set then get round-trips correctly (decrypted value matches original)

Step 6.7: .gitignore and documentation

Acceptance criteria:

• .gitignore updated to exclude mciasdb binary
• README.md updated with mciasdb usage section (when to use vs mciasctl, config requirements, example commands)
• PROGRESS.md updated to reflect Phase 6 complete

---

Implementation Order

Phase 0 → Phase 1 (1.1, 1.2, 1.3, 1.4 in parallel or sequence)
        → Phase 2 (2.1 then 2.2)
        → Phase 3 (3.1, 3.2, 3.3 in sequence)
        → Phase 4
        → Phase 5
        → Phase 6 (6.1 → 6.2 → 6.3 → 6.4 → 6.5 → 6.6 → 6.7)

Each step must have passing tests before the next step begins.