Skip to content

Commit 4f0396d

Browse files
bb-connorbb-connor
authored
claude/codex specs (#33)
1 parent 5e0e3ce commit 4f0396d

File tree

2 files changed

+163
-0
lines changed

2 files changed

+163
-0
lines changed

‎AGENTS.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
5+
- `crates/`: Rust workspace crates (core engine, guards, CLI, daemon, WASM bindings)
6+
- `packages/`: TypeScript SDK + framework adapters, plus Python SDK in `packages/hush-py/`
7+
- `apps/desktop/`: Tauri + Vite desktop app
8+
- `rulesets/`: pre-configured YAML policies used by examples and tooling
9+
- `docs/`: mdBook source (`docs/src/**`)
10+
- `examples/`, `fixtures/`, `scripts/`, `tools/`, `fuzz/`
11+
- `vendor/`: vendored Rust dependencies for offline builds (avoid hand-editing)
12+
13+
## Build, Test, and Development Commands
14+
15+
Toolchains are pinned in `mise.toml` (Rust `1.93`, Node `24`, Python `3.12`).
16+
17+
- Rust workspace: `cargo build`, `cargo test --workspace`
18+
- Format/lint: `cargo fmt --all` and `cargo clippy --all-targets --all-features -- -D warnings`
19+
- Rust “local CI”: `mise run ci`
20+
- Full platform check (Rust + TS + Python + docs): `bash scripts/test-platform.sh`
21+
- Offline (vendored) Rust tests: `CARGO_NET_OFFLINE=true scripts/cargo-offline.sh test --workspace --all-targets`
22+
23+
TypeScript packages are built/tested per-package (no root JS workspace):
24+
- Example: `npm --prefix packages/hush-ts ci && npm --prefix packages/hush-ts test`
25+
- Desktop: `npm --prefix apps/desktop ci && npm --prefix apps/desktop run tauri:dev`
26+
27+
Docs:
28+
- `mdbook build docs` / `mdbook test docs`
29+
30+
## Coding Style & Naming Conventions
31+
32+
- Rust: `rustfmt` is authoritative. Clippy denies `unwrap()`/`expect()` at the workspace level—prefer `?` + typed errors.
33+
- TypeScript: 2-space indentation, ESM modules. Keep public exports stable; run `npm run typecheck` in touched packages.
34+
- Python (`packages/hush-py`): 4-space indentation, `ruff` (line length 100) + `mypy --strict`.
35+
36+
## Testing Guidelines
37+
38+
- Rust: `cargo test -p <crate>`; add unit/integration tests for guard/policy changes (property tests may use `proptest`).
39+
- TypeScript: `vitest` with `*.test.ts` / `*.e2e.test.ts` naming; run `npm test` in affected packages.
40+
- Python: `pytest` under `packages/hush-py/tests/` (`test_*.py`).
41+
42+
## Commit & Pull Request Guidelines
43+
44+
- Commits follow Conventional Commits (seen in history): `feat:`, `fix:`, `docs:`, `chore(deps):`, with optional scopes (e.g. `feat(desktop): …`) and `!` for breaking changes.
45+
- Branches typically use `feature/<name>` or `fix/<name>`.
46+
- PRs: keep scope tight, link issues (“Closes #123”), update docs for public API changes, and include screenshots for `apps/desktop` UI changes.
47+
- Security reports: follow `SECURITY.md` (no public issues for vulnerabilities).

‎CLAUDE.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Clawdstrike is a runtime security enforcement system for AI agents. It provides policy-driven security checks at the tool boundary between agent runtimes and their executed actions. The project is Rust-first with multi-language support (TypeScript, Python, WebAssembly).
8+
9+
**Design Philosophy:** Fail-closed. Invalid policies reject at load time; errors during evaluation deny access.
10+
11+
## Common Commands
12+
13+
```bash
14+
# Build
15+
cargo build --workspace
16+
17+
# Test
18+
cargo test --workspace # All tests
19+
cargo test -p clawdstrike # Single crate
20+
cargo test test_name # Single test
21+
22+
# Lint & Format
23+
cargo fmt --all
24+
cargo clippy --workspace -- -D warnings
25+
26+
# Full CI locally
27+
mise run ci # or: cargo fmt --all -- --check && cargo clippy --workspace -- -D warnings && cargo test --workspace
28+
29+
# Documentation
30+
cargo doc --no-deps --all-features
31+
mdbook build docs
32+
33+
# TypeScript packages
34+
npm install --workspace=packages/hush-ts
35+
npm run build --workspace=packages/hush-ts
36+
npm test --workspace=packages/hush-ts
37+
38+
# Python
39+
pip install -e packages/hush-py[dev]
40+
pytest packages/hush-py/tests
41+
42+
# CLI
43+
cargo install --path crates/hush-cli
44+
clawdstrike check --action-type file --ruleset strict ~/.ssh/id_rsa
45+
```
46+
47+
## Architecture
48+
49+
### Monorepo Structure
50+
51+
**Rust Crates (`crates/`):**
52+
- `hush-core` - Cryptographic primitives (Ed25519, SHA-256, Keccak-256, Merkle trees, canonical JSON RFC 8785)
53+
- `clawdstrike` - Main library: guards, policy engine, receipts
54+
- `hush-cli` - CLI binary (commands: `clawdstrike`, `hush`)
55+
- `hushd` - HTTP daemon for centralized enforcement (experimental)
56+
- `hush-proxy` - Network proxy utilities
57+
- `hush-wasm` - WebAssembly bindings
58+
- `hush-certification` - Compliance templates
59+
- `hush-multi-agent` - Multi-agent orchestration
60+
61+
**TypeScript Packages (`packages/`):**
62+
- `hush-ts` - Core TypeScript SDK (`@clawdstrike/sdk`)
63+
- `clawdstrike-policy` - Canonical policy engine (TS)
64+
- `clawdstrike-adapter-core` - Base adapter interface
65+
- Framework adapters: `clawdstrike-openclaw`, `clawdstrike-vercel-ai`, `clawdstrike-langchain`, `clawdstrike-claude-code`, `clawdstrike-codex`, `clawdstrike-opencode`
66+
67+
**Python:** `packages/hush-py`
68+
69+
### Core Abstractions
70+
71+
- **Guard** - A security check implementing the `Guard` trait (sync) or `AsyncGuard` trait (async)
72+
- **Policy** - YAML configuration (schema v1.1.0) with `extends` for inheritance
73+
- **Receipt** - Ed25519-signed attestation of decision, policy, and evidence
74+
- **HushEngine** - Facade orchestrating guards and signing
75+
76+
### Built-in Guards (7)
77+
78+
1. `ForbiddenPathGuard` - Blocks sensitive filesystem paths
79+
2. `EgressAllowlistGuard` - Controls network egress by domain
80+
3. `SecretLeakGuard` - Detects secrets in file writes
81+
4. `PatchIntegrityGuard` - Validates patch safety
82+
5. `McpToolGuard` - Restricts MCP tool invocations
83+
6. `PromptInjectionGuard` - Detects prompt injection
84+
7. `JailbreakGuard` - 4-layer detection (heuristic + statistical + ML + optional LLM-judge)
85+
86+
### Policy System
87+
88+
Policies are YAML files with schema version 1.1.0. They support inheritance via `extends`:
89+
- Built-in rulesets: `permissive`, `default`, `strict`, `ai-agent`, `cicd`
90+
- Local file references
91+
- Remote URLs
92+
- Git refs
93+
94+
Location: `rulesets/` directory contains built-in policies.
95+
96+
### Decision Flow
97+
98+
```
99+
Policy Load → Guard Instantiation → Action Check → Per-Guard Evaluation
100+
→ Aggregate Verdict → Receipt Signing → Audit Logging
101+
```
102+
103+
## Conventions
104+
105+
- **Commit messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/) - `feat(scope):`, `fix(scope):`, `docs:`, `test:`, `refactor:`, `perf:`, `chore:`
106+
- **Clippy:** Must pass with `-D warnings` (treat warnings as errors)
107+
- **Property testing:** Use `proptest` for cryptographic and serialization code
108+
- **MSRV:** Rust 1.93
109+
110+
## Key Files
111+
112+
- `Cargo.toml` - Workspace root with all crate definitions
113+
- `mise.toml` - Task runner configuration
114+
- `deny.toml` - cargo-deny license/advisory config
115+
- `rulesets/*.yaml` - Built-in security policies
116+
- `docs/` - mdBook documentation source

0 commit comments

Comments
 (0)