Kyle Isom
0cada7e64e
- 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>
97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
# 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.
|