velar: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Velar (formerly PromptShield) is a local HTTP/HTTPS proxy with MITM support for AI traffic. It detects and masks PII/secrets in outbound requests to AI providers, then restores original values in responses. All processing is local — nothing is sent to external services.

Commands

# Build both binaries (velar CLI + velard daemon)
make build

# Run all tests with race detector
make test

# Run a single package's tests
go test ./internal/sanitizer/... -run TestSanitize

# Run a single test
go test ./internal/sanitizer/... -run TestSanitize/email -v

# Test ONNX NER detector (requires Python venv with numpy + onnxruntime)
make test-ner

# Run the proxy directly (without daemonizing)
go run ./cmd/velar daemon

# Start as background daemon (requires make build first)
./bin/velar start

Architecture

The project produces two binaries:

• cmd/velar — CLI that manages the daemon lifecycle (start, stop, restart, status, logs, stats, ca, proxy, model)
• cmd/velard — The actual daemon process spawned by velar start

Request Flow

Client -> Proxy.handle() -> policy.Engine.Evaluate()
  -> if CONNECT + MITM domain: mitm.Handler.HandleMITM()
  -> if CONNECT + tunnel: handleTunnel()
  -> if HTTP: handleHTTP()
    -> Inspector.InspectRequest()  [sanitize outbound]
    -> upstream RoundTrip
    -> Inspector.InspectResponse() [restore inbound]

Key Packages

Package	Role
internal/proxy	Core HTTP proxy; routes to MITM or tunnel based on policy
internal/proxy/mitm	MITM handler: TLS intercept via per-host leaf certs signed by local CA; uses singleConnListener pattern
internal/sanitizer	SanitizingInspector implements the Inspector interface; JSON-aware masking with fallback to full-text
internal/detect	Detection backends: RegexDetector (fast), ONNXNERDetector (Python subprocess), HybridDetector (combines both)
internal/policy	Rule engine: evaluates allow/block/mitm decisions per host
internal/session	Per-request store mapping placeholders -> originals, keyed by session ID propagated via context
internal/config	YAML/JSON config loader with custom lite parser (no external YAML dep); env overrides VELAR_PORT, VELAR_LOG_FILE
internal/audit	JSONL audit logger for request/response entries
internal/stats	In-memory stats collector for velar stats command
internal/classifier	Host classifier (stub — used as hook for future classification)
internal/notifier	macOS NSUserNotification wrapper (no-op on other platforms)
internal/systemproxy	macOS networksetup wrapper to toggle system HTTP/HTTPS proxy
internal/models	ONNX model registry and downloader for velar model commands