upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDanConwayDev <DanConwayDev@protonmail.com>2026-02-24 12:30:35 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2026-02-24 12:30:35 +0000
commit62f829e2743c1fc5df108d10f1ee579f8568a91a (patch)
tree790bb9f6de7a3bb5dc4dcb6343bee82b058f7a26
parent319c1c7e524bfb78a3f686041e5af2ed60ea182d (diff)
update grasp-audit README port examples and remove stale TAG_MIGRATION doc
-rw-r--r--grasp-audit/README.md10
-rw-r--r--grasp-audit/TAG_MIGRATION.md151
2 files changed, 5 insertions, 156 deletions
diff --git a/grasp-audit/README.md b/grasp-audit/README.md
index 936f10f..54e1e93 100644
--- a/grasp-audit/README.md
+++ b/grasp-audit/README.md
@@ -23,7 +23,7 @@ cargo install --path .
23grasp-audit audit --relay wss://relay.ngit.dev 23grasp-audit audit --relay wss://relay.ngit.dev
24 24
25# Or audit a local development relay 25# Or audit a local development relay
26grasp-audit audit --relay ws://localhost:7000 26grasp-audit audit --relay ws://localhost:7334
27``` 27```
28 28
29## Usage Examples 29## Usage Examples
@@ -38,10 +38,10 @@ cargo install --path .
38grasp-audit audit --relay wss://relay.ngit.dev 38grasp-audit audit --relay wss://relay.ngit.dev
39 39
40# Audit local development relay 40# Audit local development relay
41grasp-audit audit --relay ws://localhost:7000 --spec nip01-smoke 41grasp-audit audit --relay ws://localhost:7334 --spec nip01-smoke
42 42
43# Run with isolated fixtures (for testing/debugging) 43# Run with isolated fixtures (for testing/debugging)
44grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec push-auth 44grasp-audit audit --relay ws://localhost:7334 --mode isolated --spec push-auth
45``` 45```
46 46
47### As a Library 47### As a Library
@@ -54,7 +54,7 @@ async fn main() -> Result<()> {
54 // Create audit client with isolated fixtures (recommended for library use) 54 // Create audit client with isolated fixtures (recommended for library use)
55 let config = AuditConfig::isolated(); 55 let config = AuditConfig::isolated();
56 // let config = AuditConfig::shared(); // Alternative: shared fixtures 56 // let config = AuditConfig::shared(); // Alternative: shared fixtures
57 let client = AuditClient::new("ws://localhost:7000", config).await?; 57 let client = AuditClient::new("ws://localhost:7334", config).await?;
58 58
59 // Run NIP-01 smoke tests 59 // Run NIP-01 smoke tests
60 let results = specs::Nip01SmokeTests::run_all(&client).await; 60 let results = specs::Nip01SmokeTests::run_all(&client).await;
@@ -135,7 +135,7 @@ Use this when:
135 135
136```bash 136```bash
137# Use isolated mode explicitly 137# Use isolated mode explicitly
138grasp-audit audit --relay ws://localhost:7000 --mode isolated 138grasp-audit audit --relay ws://localhost:7334 --mode isolated
139``` 139```
140 140
141```rust 141```rust
diff --git a/grasp-audit/TAG_MIGRATION.md b/grasp-audit/TAG_MIGRATION.md
deleted file mode 100644
index aaba729..0000000
--- a/grasp-audit/TAG_MIGRATION.md
+++ /dev/null
@@ -1,151 +0,0 @@
1# Tag Migration to Standard NIP-01 "t" Tags
2
3**Date:** November 4, 2025
4**Status:** ✅ Complete
5
6## Overview
7
8Migrated audit system tags from custom single-letter tags (`g`, `r`, `c`) to standard NIP-01 "t" tags (hashtags) to avoid conflicts and follow Nostr conventions.
9
10## Motivation
11
12The previous tag scheme used:
13- `g` tag for `grasp-audit` marker
14- `r` tag for `audit-run-id`
15- `c` tag for `audit-cleanup` timestamp
16
17However, this could conflict with other uses of these single-letter tags. The "t" tag is the standard NIP-01 tag type for categorization/topics, making it the appropriate choice for audit event tagging.
18
19## Changes Made
20
21### Tag Structure
22
23**Before:**
24```rust
25vec![
26 Tag::custom(TagKind::SingleLetter(g_tag), vec!["grasp-audit"]),
27 Tag::custom(TagKind::SingleLetter(r_tag), vec![run_id]),
28 Tag::custom(TagKind::SingleLetter(c_tag), vec![cleanup_timestamp]),
29]
30```
31
32**After:**
33```rust
34vec![
35 Tag::custom(TagKind::SingleLetter(t_tag), vec!["grasp-audit-test-event"]),
36 Tag::custom(TagKind::SingleLetter(t_tag), vec![format!("audit-{}", run_id)]),
37 Tag::custom(TagKind::SingleLetter(t_tag), vec![format!("audit-cleanup-after-{}", timestamp)]),
38]
39```
40
41### Tag Values
42
43| Purpose | Old Tag | Old Value | New Tag | New Value |
44|---------|---------|-----------|---------|-----------|
45| Marker | `g` | `grasp-audit` | `t` | `grasp-audit-test-event` |
46| Run ID | `r` | `ci-{uuid}` | `t` | `audit-ci-{uuid}` |
47| Cleanup | `c` | `{timestamp}` | `t` | `audit-cleanup-after-{timestamp}` |
48
49### Example Event Tags
50
51```json
52[
53 ["t", "grasp-audit-test-event"],
54 ["t", "audit-ci-a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
55 ["t", "audit-cleanup-after-1730707200"]
56]
57```
58
59## Files Modified
60
61### `src/audit.rs`
62- Updated `audit_tags()` to use "t" tags
63- Updated tests to check for "t" tag kind
64- All values now prefixed for clarity
65
66### `src/client.rs`
67- Updated `query()` to filter by "t" tags
68- Changed from `.custom_tag(g_tag, ...)` to `.custom_tag(t_tag, ...)`
69
70## Benefits
71
721. **Standards Compliance**: Uses standard NIP-01 hashtag mechanism
732. **No Conflicts**: "t" tag is designed for categorization
743. **Better Namespacing**: Values prefixed with `audit-` to avoid collisions
754. **Queryable**: Standard tag filtering works as expected
765. **Self-Documenting**: Tag values clearly indicate their purpose
77
78## Testing
79
80All tests pass with the new tag scheme:
81
82```bash
83# Unit tests
84✓ 12/12 tests passing
85
86# Integration tests
87✓ 1/1 test passing (NIP-01 smoke tests)
88
89# CLI verification
90✓ All 6 smoke tests pass
91```
92
93## Backwards Compatibility
94
95⚠️ **Breaking Change**: Events created with old tags will not be found by new queries.
96
97This is acceptable because:
98- System is in alpha/development
99- Old events are test data only
100- Cleanup happens automatically via timestamps
101- No production deployments exist yet
102
103## Migration Path
104
105For future tag changes:
1061. Consider versioning in tag values (e.g., `grasp-audit-v2-test-event`)
1072. Support querying both old and new tags during transition
1083. Document breaking changes clearly
1094. Provide migration tools if needed
110
111## References
112
113- **NIP-01**: https://github.com/nostr-protocol/nips/blob/master/01.md
114- **Tag Standardization**: "t" tags for topics/categories
115- **Previous Implementation**: Commit `8190a3a` (custom g/r/c tags)
116- **Current Implementation**: Uses standard "t" tags
117
118## Verification
119
120To verify the new tag structure:
121
122```bash
123# Run tests
124nix develop -c cargo test --lib
125nix develop -c cargo test -- --ignored
126
127# Run CLI
128nix develop -c cargo run -- audit \
129 --relay ws://localhost:7000 \
130 --mode ci \
131 --spec nip01-smoke
132
133# Check event structure (example)
134# Events will have tags like:
135# ["t", "grasp-audit-test-event"]
136# ["t", "audit-ci-{uuid}"]
137# ["t", "audit-cleanup-after-{timestamp}"]
138```
139
140## Next Steps
141
142- [ ] Update documentation to reflect new tag scheme
143- [ ] Consider adding tag validation helpers
144- [ ] Document tag format in API/spec documentation
145- [ ] Add examples showing tag usage
146
147---
148
149**Status:** ✅ Migration complete and verified
150**All tests passing:** 13/13 (12 unit + 1 integration)
151**CLI verified:** ✅ Working correctly