mcat/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mcat is a lightweight web application for testing MCIAS login policies. It presents a login form, forwards credentials (with configurable service_name and tags) to MCIAS, and shows whether the login was accepted or denied by policy. Single binary, no database, no gRPC.

Module path: git.wntrmute.dev/mc/mcat

MCIAS client library: git.wntrmute.dev/mc/mcias/clients/go (imported as mcias), local replace directive in go.mod.

Build Commands

make mcat          # Build the mcat binary (stripped, version-injected)
make build         # Build all packages
make test          # Run all tests
make vet           # Run go vet
make lint          # Run golangci-lint v2
make all           # Full pipeline: vet → lint → test → build
make devserver     # Build and run locally against srv/mcat.toml

Run a single test:

go test ./internal/auth/ -run TestLoginSuccess

Architecture

• cmd/mcat/ — Cobra CLI entry point. server subcommand wires config → auth → webserver.
• internal/auth/ — Wraps MCIAS client for login/logout/token validation with 30s cache.
• internal/config/ — TOML config loading and validation.
• internal/webserver/ — Chi-based web server with CSRF (HMAC-SHA256 double-submit cookies), session cookies, and template rendering.
• web/ — Embedded templates (layout + page blocks) and static files (htmx, CSS).
• deploy/ — Dockerfile, systemd unit, install script, example config.
• srv/ — Local dev data directory (gitignored).

Critical Rules

• No test frameworks: Use stdlib testing only.
• Auth via MCIAS only: No local user databases.
• TLS 1.3 minimum, no exceptions.
• CSRF on all mutations: Double-submit cookie pattern, validated in middleware.
• Session cookies: HttpOnly, Secure, SameSite=Strict.