mcat/ARCHITECTURE.md

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

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