1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
# 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
### Unit Tests
```bash
# Enter dev environment (NixOS)
nix develop
# Run unit tests (no relay required)
cargo test
```
### Integration Tests Against ngit-relay
Test against the reference GRASP implementation to ensure compatibility.
**Automated Script (Recommended):**
```bash
# Handles setup, testing, and cleanup automatically
./test-ngit-relay.sh
```
See `test-ngit-relay.sh` for full setup/cleanup details.
**Manual One-Liner:**
```bash
# Start relay, then run: RELAY_URL="ws://localhost:$PORT" cargo test --lib -- --ignored --nocapture
```
**Note:** ngit-relay only accepts Git-related events (NIP-34). Some NIP-01 smoke tests will fail (expected). Validation tests should pass.
### Testing Against General-Purpose Relays
For full NIP-01 smoke test coverage (all 6 tests passing), test against a general-purpose relay:
```bash
# Start nostr-rs-relay (accepts all event kinds)
docker run --rm -d --name nostr-test-relay -p 7000:8080 scsibug/nostr-rs-relay
# Run tests (all should pass)
cargo test --lib -- --ignored --nocapture
# Cleanup
docker stop nostr-test-relay
```
Expected: 6/6 tests passed (100%)
## 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
|