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