created POC grasp-auditor

1 files changed, 167 insertions, 0 deletions

diff --git a/grasp-audit/README.md b/grasp-audit/README.md
new file mode 100644
index 0000000..558e201
--- /dev/null
+++ b/grasp-audit/README.md
@@ -0,0 +1,167 @@
+# GRASP Audit
+
+A reusable audit and compliance testing tool for GRASP protocol implementations.
+
+## Features
+
+- ✅ **Isolated Testing**: Tests run in parallel with unique audit IDs
+- ✅ **Production Audit**: Test live services with minimal impact
+- ✅ **Clean Audit Events**: Special tags for easy cleanup (no deletion trails)
+- ✅ **Spec-Mirrored Tests**: Test structure matches GRASP protocol exactly
+- ✅ **Reusable**: Can test any GRASP implementation (Rust, Go, Python, etc.)
+
+## Quick Start
+
+### As a Library
+
+```rust
+use grasp_audit::*;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create audit client for CI testing
+    let config = AuditConfig::ci();
+    let client = AuditClient::new("ws://localhost:7000", config).await?;
+    
+    // Run NIP-01 smoke tests
+    let results = specs::Nip01SmokeTests::run_all(&client).await;
+    results.print_report();
+    
+    if !results.all_passed() {
+        std::process::exit(1);
+    }
+    
+    Ok(())
+}
+```
+
+### As a CLI Tool
+
+```bash
+# Install
+cargo install --path .
+
+# Run smoke tests against local relay
+grasp-audit audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke
+
+# Audit production server (read-only)
+grasp-audit audit --relay wss://relay.example.com --mode production --spec all
+```
+
+## Test Specifications
+
+### NIP-01 Smoke Tests (6 tests)
+
+Basic Nostr relay functionality:
+
+1. `websocket_connection` - Can connect to /
+2. `send_receive_event` - Can send EVENT, get OK
+3. `create_subscription` - Can subscribe with REQ
+4. `close_subscription` - Can close subscriptions
+5. `reject_invalid_signature` - Rejects bad signatures
+6. `reject_invalid_event_id` - Rejects wrong IDs
+
+**Why only smoke tests?** rust-nostr already has 1000+ tests for NIP-01 compliance. We focus on GRASP-specific behavior.
+
+### GRASP-01 Tests (Coming Soon)
+
+- Repository announcement acceptance
+- State event handling
+- Policy enforcement
+- And more...
+
+## Audit Event Strategy
+
+All audit events include special tags:
+
+```json
+{
+  "tags": [
+    ["grasp-audit", "true"],
+    ["audit-run-id", "ci-a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
+    ["audit-cleanup", "2025-11-03T12:00:00Z"]
+  ]
+}
+```
+
+This allows:
+- **Isolation**: Each test run has unique ID
+- **Cleanup**: Events marked for cleanup after timestamp
+- **No deletion trails**: Direct database cleanup (no NIP-09 deletion events)
+
+## Modes
+
+### CI Mode (Default)
+
+- Tests are isolated by unique run ID
+- Tests only see their own events
+- Full read/write access
+- Cleanup after 1 hour
+
+```rust
+let config = AuditConfig::ci();
+```
+
+### Production Mode
+
+- Tests see all events (including real ones)
+- Read-only by default (minimal impact)
+- Cleanup after 5 minutes
+
+```rust
+let config = AuditConfig::production();
+```
+
+## Examples
+
+See `examples/` directory:
+
+```bash
+# Simple audit example
+cargo run --example simple_audit
+```
+
+## Testing
+
+```bash
+# Run unit tests
+cargo test
+
+# Run integration tests (requires running relay)
+cargo test --ignored
+```
+
+## Architecture
+
+```
+grasp-audit/
+├── src/
+│   ├── lib.rs              # Public API
+│   ├── audit.rs            # Audit config and event tagging
+│   ├── client.rs           # Audit client
+│   ├── result.rs           # Test result types
+│   ├── isolation.rs        # Test isolation utilities
+│   └── specs/
+│       ├── mod.rs
+│       └── nip01_smoke.rs  # NIP-01 smoke tests
+├── examples/
+│   └── simple_audit.rs     # Example usage
+└── bin/
+    └── grasp-audit.rs      # CLI tool
+```
+
+## Development Status
+
+- ✅ Audit framework
+- ✅ NIP-01 smoke tests (6 tests)
+- 🚧 GRASP-01 relay tests (planned)
+- 🚧 GRASP-01 git tests (planned)
+- 🚧 Cleanup utilities (planned)
+
+## Contributing
+
+This tool is designed to be reusable by any GRASP implementation. Contributions welcome!
+
+## License
+
+MIT