metacircular/CLAUDE.md

CLAUDE.md

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

Overview

Metacircular is a multi-service personal infrastructure platform. This root repository is a workspace container — each subdirectory is a separate Git repo (gitignored here). The authoritative platform-wide standards live in engineering-standards.md.

Project Map

Directory	Purpose	Language
mcias/	Identity and Access Service — central SSO/IAM, all other services delegate auth here	Go
metacrypt/	Cryptographic service engine — encrypted secrets, PKI/CA, SSH CA, transit encryption	Go
mc-proxy/	TLS proxy and router — L4 passthrough or L7 terminating, PROXY protocol, firewall	Go
mcr/	OCI container registry — integrated with MCIAS for auth and policy-based push/pull	Go
mcat/	MCIAS login policy tester — lightweight web app to test and audit login policies	Go
mcdsl/	Standard library — shared packages for auth, db, config, HTTP/gRPC servers, CSRF, snapshots	Go
mcdoc/	Documentation server — renders markdown from Gitea, serves public docs via mc-proxy	Go
mcq/	Document review queue — push docs for review, MCP server for Claude integration	Go
mcp/	Control plane — operator-driven deployment, service registry, container lifecycle (master/agent)	Go
mcdeploy/	Deployment CLI — deprecated, superseded by MCP (archived)	Go
mcns/	Networking service — custom Go DNS server, authoritative for internal zones	Go
ca/	PKI infrastructure and secrets for dev/test (not source code, gitignored)	—
docs/	Platform-wide documentation (architecture overview, deployment guide)	Markdown

Each subproject has its own CLAUDE.md, ARCHITECTURE.md, Makefile, and go.mod. When working in a subproject, read its own CLAUDE.md first.

Service Dependencies

MCIAS is the root dependency — every other service authenticates through it. No service maintains its own user database. The dependency graph:

mcias (standalone — no MCIAS dependency)
  ├── metacrypt (uses MCIAS for auth)
  ├── mc-proxy (uses MCIAS for admin auth)
  ├── mcr (uses MCIAS for auth + policy)
  ├── mcdoc (public, no MCIAS — fetches docs from Gitea)
  ├── mcq (uses MCIAS for auth; document review queue)
  ├── mcp (uses MCIAS for auth; orchestrates deployment and lifecycle)
  ├── mcns (uses MCIAS for auth; authoritative DNS for internal zones)
  └── mcat (tests MCIAS login policies)

Standard Build Commands (all subprojects)

make all         # vet → lint → test → build (the CI pipeline)
make build       # go build ./...
make test        # go test ./...
make vet         # go vet ./...
make lint        # golangci-lint run ./...
make proto       # regenerate gRPC code from .proto files
make proto-lint  # buf lint + buf breaking
make devserver   # build and run locally against srv/ config
make docker      # build container image
make clean       # remove binaries

Run a single test: go test ./internal/auth/ -run TestTokenValidation

Critical Rules

1. REST/gRPC sync: Every REST endpoint must have a corresponding gRPC RPC, updated in the same change.
2. gRPC interceptor maps: New RPCs must be added to authRequiredMethods, adminRequiredMethods, and/or sealRequiredMethods. Forgetting this is a security defect.
3. No CGo in production: All builds use CGO_ENABLED=0. Use modernc.org/sqlite, not mattn/go-sqlite3.
4. No test frameworks: Use stdlib testing only. Real SQLite in t.TempDir(), no mocks for databases.
5. Default deny: Unauthenticated and unauthorized requests are always rejected. Admin detection comes solely from the MCIAS admin role.
6. Proto versioning: Start at v1. Only create v2 for breaking changes. Non-breaking additions go in-place.

Architecture Patterns

• Seal/Unseal: Metacrypt starts sealed and requires a password to unlock (Vault-like pattern). Key hierarchy: Password → Argon2id → KWK → MEK → per-engine DEKs.
• Web UI separation: Web UIs run as separate binaries communicating with the API server via gRPC. No direct DB access from the web tier.
• Config: TOML with env var overrides (SERVICENAME_*). All runtime data in /srv/<service>/.
• Policy engines: Priority-based ACL rules, default deny, admin bypass. See metacrypt's implementation as reference.
• Auth flow: Client → service /v1/auth/login → MCIAS client library → MCIAS validates → bearer token returned. Token validation cached 30s keyed by SHA-256 of token.

Tech Stack

• Go 1.25+, chi router, cobra CLI, go-toml/v2
• SQLite via modernc.org/sqlite (pure Go), WAL mode, foreign keys on
• gRPC + protobuf, buf for linting
• htmx + Go html/template for web UIs
• golangci-lint v2 with errcheck, gosec, staticcheck, revive
• TLS 1.3 minimum, AES-256-GCM, Argon2id, Ed25519