Migrate to mcdsl: auth, config, csrf, web

- Replace internal/auth with mcdsl/auth - Replace internal/config with mcdsl/config (embed config.Base) - Replace internal/webserver/csrf.go with mcdsl/csrf - Use mcdsl/web for session cookies and template rendering - Use mcdsl/httpserver for server setup and StatusWriter - Remove direct mcias client library dependency - Update .golangci.yaml to v2 format (formatters section) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 17:53:15 -07:00
commit 0cada7e64e
21 changed files with 1042 additions and 0 deletions
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,96 @@
+# Architecture
+
+## Overview
+
+mcat is a lightweight web application for testing MCIAS login policies. It
+presents a login form, forwards credentials (along with a configurable
+`service_name` and `tags`) to an MCIAS instance, and displays whether the
+login was accepted or denied. This lets operators verify that login policy
+rules behave as expected for a given service context.
+
+## System Diagram
+
+```
+┌──────────────┐       HTTPS        ┌──────────────┐
+│   Browser    │◄──────────────────►│     mcat     │
+│  (htmx UI)  │                    │  web server  │
+└──────────────┘                    └──────┬───────┘
+                                           │
+                                           │ HTTPS (Login, ValidateToken)
+                                           ▼
+                                    ┌──────────────┐
+                                    │    MCIAS     │
+                                    │   (auth)     │
+                                    └──────────────┘
+```
+
+## Components
+
+### Web Server (`internal/webserver/`)
+
+Single chi-based HTTP server serving the web UI over TLS. Handles:
+
+- **Login flow**: Renders login form, submits credentials to MCIAS via the
+  auth package, sets session cookie on success.
+- **Session management**: HttpOnly/Secure/SameSite=Strict cookies containing
+  the MCIAS bearer token.
+- **CSRF protection**: HMAC-SHA256 double-submit cookies on all mutating
+  requests.
+- **Template rendering**: Go `html/template` with a layout + page block
+  pattern. Templates and static files are embedded via `//go:embed`.
+
+### Auth Package (`internal/auth/`)
+
+Wraps the MCIAS Go client library. Provides:
+
+- `Login(username, password, totpCode)` — Forwards to MCIAS with the
+  configured `service_name` and `tags`. Returns the bearer token.
+- `ValidateToken(token)` — Validates against MCIAS with 30-second cache
+  (keyed by SHA-256 of token).
+- `Logout()` — Revokes the token on MCIAS.
+
+### Configuration (`internal/config/`)
+
+TOML configuration loaded at startup. Required fields are validated; the
+service refuses to start if any are missing.
+
+### CLI (`cmd/mcat/`)
+
+Cobra-based. Subcommands: `server` (start), `version`.
+
+## Configuration Reference
+
+```toml
+[server]
+listen_addr = ":8443"           # HTTPS listen address
+tls_cert    = "cert.pem"        # TLS certificate path
+tls_key     = "key.pem"         # TLS key path
+
+[mcias]
+server_url   = "https://..."    # MCIAS server URL
+ca_cert      = ""               # Optional CA cert for MCIAS TLS
+service_name = "mcat"           # Sent with login requests for policy eval
+tags         = []               # Sent with login requests for policy eval
+
+[log]
+level = "info"                  # debug, info, warn, error
+```
+
+## Web Routes
+
+| Method | Path         | Auth | Description              |
+|--------|-------------|------|--------------------------|
+| GET    | `/`         | No   | Redirect to /dashboard or /login |
+| GET    | `/login`    | No   | Login form               |
+| POST   | `/login`    | No   | Submit login             |
+| POST   | `/logout`   | Yes  | Revoke token, clear cookie |
+| GET    | `/dashboard`| Yes  | Session info display     |
+| GET    | `/static/*` | No   | Embedded static files    |
+
+## Security
+
+- TLS 1.3 minimum, no fallback.
+- CSRF via HMAC-SHA256 double-submit cookies.
+- Session cookies: HttpOnly, Secure, SameSite=Strict.
+- All authentication delegated to MCIAS — no local user database.
+- Token validation cached for 30 seconds to reduce MCIAS load.