60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Metacrypt is a cryptographic service for the Metacircular platform, written in Go. It provides cryptographic resources via an "engines" architecture (CA, SSH CA, transit encryption, user-to-user encryption). Authentication is handled by MCIAS (Metacircular Identity and Access Service) using the client library at `git.wntrmute.dev/kyle/mcias/clients/go`. MCIAS API docs: https://mcias.metacircular.net:8443/docs
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
go build ./... # Build all packages
|
|
go test ./... # Run all tests
|
|
go vet ./... # Static analysis
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Engines**: Modular cryptographic service providers (CA, SSH CA, transit, user-to-user encryption)
|
|
- **Storage**: SQLite database with an encrypted storage barrier (similar to HashiCorp Vault)
|
|
- **Seal/Unseal**: Single password unseals the service; a master encryption key serves as a key-encryption key (KEK) to decrypt per-engine data encryption keys
|
|
- **Auth**: MCIAS integration; MCIAS admin users get admin privileges on this service
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── cmd/metacrypt/ # CLI entry point (server, init, status, snapshot)
|
|
├── deploy/
|
|
│ ├── docker/ # Docker Compose configuration
|
|
│ ├── examples/ # Example config files
|
|
│ ├── scripts/ # Deployment scripts
|
|
│ └── systemd/ # systemd unit files
|
|
├── internal/
|
|
│ ├── auth/ # MCIAS token authentication & caching
|
|
│ ├── barrier/ # Encrypted key-value storage abstraction
|
|
│ ├── config/ # TOML configuration loading & validation
|
|
│ ├── crypto/ # Low-level cryptographic primitives
|
|
│ ├── db/ # SQLite setup & schema migrations
|
|
│ ├── engine/ # Pluggable engine registry & interface
|
|
│ ├── policy/ # Priority-based ACL engine
|
|
│ ├── seal/ # Seal/unseal state machine
|
|
│ └── server/ # HTTP server, routes, middleware
|
|
├── proto/metacrypt/ # Protobuf/gRPC definitions
|
|
├── web/
|
|
│ ├── static/ # CSS, HTMX
|
|
│ └── templates/ # Go HTML templates
|
|
├── Dockerfile
|
|
├── Makefile
|
|
└── metacrypt.toml.example
|
|
```
|
|
|
|
## Ignored Directories
|
|
|
|
- `srv/` — Local runtime data (database, certs, config). Do not read, modify, or reference these files.
|
|
|
|
## API Sync Rule
|
|
|
|
The gRPC proto definitions (`proto/metacrypt/v1/`) and the REST API (`internal/server/routes.go`) must always be kept in sync. When adding, removing, or changing an endpoint in either surface, the other must be updated in the same change. Every REST endpoint must have a corresponding gRPC RPC (and vice versa), with matching request/response fields.
|