From 62f829e2743c1fc5df108d10f1ee579f8568a91a Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Tue, 24 Feb 2026 12:30:35 +0000 Subject: update grasp-audit README port examples and remove stale TAG_MIGRATION doc --- grasp-audit/README.md | 10 +-- grasp-audit/TAG_MIGRATION.md | 151 ------------------------------------------- 2 files changed, 5 insertions(+), 156 deletions(-) delete mode 100644 grasp-audit/TAG_MIGRATION.md 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 . grasp-audit audit --relay wss://relay.ngit.dev # Or audit a local development relay -grasp-audit audit --relay ws://localhost:7000 +grasp-audit audit --relay ws://localhost:7334 ``` ## Usage Examples @@ -38,10 +38,10 @@ cargo install --path . grasp-audit audit --relay wss://relay.ngit.dev # Audit local development relay -grasp-audit audit --relay ws://localhost:7000 --spec nip01-smoke +grasp-audit audit --relay ws://localhost:7334 --spec nip01-smoke # Run with isolated fixtures (for testing/debugging) -grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec push-auth +grasp-audit audit --relay ws://localhost:7334 --mode isolated --spec push-auth ``` ### As a Library @@ -54,7 +54,7 @@ async fn main() -> Result<()> { // Create audit client with isolated fixtures (recommended for library use) let config = AuditConfig::isolated(); // let config = AuditConfig::shared(); // Alternative: shared fixtures - let client = AuditClient::new("ws://localhost:7000", config).await?; + let client = AuditClient::new("ws://localhost:7334", config).await?; // Run NIP-01 smoke tests let results = specs::Nip01SmokeTests::run_all(&client).await; @@ -135,7 +135,7 @@ Use this when: ```bash # Use isolated mode explicitly -grasp-audit audit --relay ws://localhost:7000 --mode isolated +grasp-audit audit --relay ws://localhost:7334 --mode isolated ``` ```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 @@ -# Tag Migration to Standard NIP-01 "t" Tags - -**Date:** November 4, 2025 -**Status:** ✅ Complete - -## Overview - -Migrated 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. - -## Motivation - -The previous tag scheme used: -- `g` tag for `grasp-audit` marker -- `r` tag for `audit-run-id` -- `c` tag for `audit-cleanup` timestamp - -However, 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. - -## Changes Made - -### Tag Structure - -**Before:** -```rust -vec![ - Tag::custom(TagKind::SingleLetter(g_tag), vec!["grasp-audit"]), - Tag::custom(TagKind::SingleLetter(r_tag), vec![run_id]), - Tag::custom(TagKind::SingleLetter(c_tag), vec![cleanup_timestamp]), -] -``` - -**After:** -```rust -vec![ - Tag::custom(TagKind::SingleLetter(t_tag), vec!["grasp-audit-test-event"]), - Tag::custom(TagKind::SingleLetter(t_tag), vec![format!("audit-{}", run_id)]), - Tag::custom(TagKind::SingleLetter(t_tag), vec![format!("audit-cleanup-after-{}", timestamp)]), -] -``` - -### Tag Values - -| Purpose | Old Tag | Old Value | New Tag | New Value | -|---------|---------|-----------|---------|-----------| -| Marker | `g` | `grasp-audit` | `t` | `grasp-audit-test-event` | -| Run ID | `r` | `ci-{uuid}` | `t` | `audit-ci-{uuid}` | -| Cleanup | `c` | `{timestamp}` | `t` | `audit-cleanup-after-{timestamp}` | - -### Example Event Tags - -```json -[ - ["t", "grasp-audit-test-event"], - ["t", "audit-ci-a1b2c3d4-e5f6-7890-abcd-ef1234567890"], - ["t", "audit-cleanup-after-1730707200"] -] -``` - -## Files Modified - -### `src/audit.rs` -- Updated `audit_tags()` to use "t" tags -- Updated tests to check for "t" tag kind -- All values now prefixed for clarity - -### `src/client.rs` -- Updated `query()` to filter by "t" tags -- Changed from `.custom_tag(g_tag, ...)` to `.custom_tag(t_tag, ...)` - -## Benefits - -1. **Standards Compliance**: Uses standard NIP-01 hashtag mechanism -2. **No Conflicts**: "t" tag is designed for categorization -3. **Better Namespacing**: Values prefixed with `audit-` to avoid collisions -4. **Queryable**: Standard tag filtering works as expected -5. **Self-Documenting**: Tag values clearly indicate their purpose - -## Testing - -All tests pass with the new tag scheme: - -```bash -# Unit tests -✓ 12/12 tests passing - -# Integration tests -✓ 1/1 test passing (NIP-01 smoke tests) - -# CLI verification -✓ All 6 smoke tests pass -``` - -## Backwards Compatibility - -⚠️ **Breaking Change**: Events created with old tags will not be found by new queries. - -This is acceptable because: -- System is in alpha/development -- Old events are test data only -- Cleanup happens automatically via timestamps -- No production deployments exist yet - -## Migration Path - -For future tag changes: -1. Consider versioning in tag values (e.g., `grasp-audit-v2-test-event`) -2. Support querying both old and new tags during transition -3. Document breaking changes clearly -4. Provide migration tools if needed - -## References - -- **NIP-01**: https://github.com/nostr-protocol/nips/blob/master/01.md -- **Tag Standardization**: "t" tags for topics/categories -- **Previous Implementation**: Commit `8190a3a` (custom g/r/c tags) -- **Current Implementation**: Uses standard "t" tags - -## Verification - -To verify the new tag structure: - -```bash -# Run tests -nix develop -c cargo test --lib -nix develop -c cargo test -- --ignored - -# Run CLI -nix develop -c cargo run -- audit \ - --relay ws://localhost:7000 \ - --mode ci \ - --spec nip01-smoke - -# Check event structure (example) -# Events will have tags like: -# ["t", "grasp-audit-test-event"] -# ["t", "audit-ci-{uuid}"] -# ["t", "audit-cleanup-after-{timestamp}"] -``` - -## Next Steps - -- [ ] Update documentation to reflect new tag scheme -- [ ] Consider adding tag validation helpers -- [ ] Document tag format in API/spec documentation -- [ ] Add examples showing tag usage - ---- - -**Status:** ✅ Migration complete and verified -**All tests passing:** 13/13 (12 unit + 1 integration) -**CLI verified:** ✅ Working correctly -- cgit v1.2.3