diff options
Diffstat (limited to 'grasp-audit')
| -rw-r--r-- | grasp-audit/README.md | 10 | ||||
| -rw-r--r-- | grasp-audit/TAG_MIGRATION.md | 151 |
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 . | |||
| 23 | grasp-audit audit --relay wss://relay.ngit.dev | 23 | grasp-audit audit --relay wss://relay.ngit.dev |
| 24 | 24 | ||
| 25 | # Or audit a local development relay | 25 | # Or audit a local development relay |
| 26 | grasp-audit audit --relay ws://localhost:7000 | 26 | grasp-audit audit --relay ws://localhost:7334 |
| 27 | ``` | 27 | ``` |
| 28 | 28 | ||
| 29 | ## Usage Examples | 29 | ## Usage Examples |
| @@ -38,10 +38,10 @@ cargo install --path . | |||
| 38 | grasp-audit audit --relay wss://relay.ngit.dev | 38 | grasp-audit audit --relay wss://relay.ngit.dev |
| 39 | 39 | ||
| 40 | # Audit local development relay | 40 | # Audit local development relay |
| 41 | grasp-audit audit --relay ws://localhost:7000 --spec nip01-smoke | 41 | grasp-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) |
| 44 | grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec push-auth | 44 | grasp-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 |
| 138 | grasp-audit audit --relay ws://localhost:7000 --mode isolated | 138 | grasp-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 | |||
| 8 | 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. | ||
| 9 | |||
| 10 | ## Motivation | ||
| 11 | |||
| 12 | The 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 | |||
| 17 | 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. | ||
| 18 | |||
| 19 | ## Changes Made | ||
| 20 | |||
| 21 | ### Tag Structure | ||
| 22 | |||
| 23 | **Before:** | ||
| 24 | ```rust | ||
| 25 | vec![ | ||
| 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 | ||
| 34 | vec![ | ||
| 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 | |||
| 72 | 1. **Standards Compliance**: Uses standard NIP-01 hashtag mechanism | ||
| 73 | 2. **No Conflicts**: "t" tag is designed for categorization | ||
| 74 | 3. **Better Namespacing**: Values prefixed with `audit-` to avoid collisions | ||
| 75 | 4. **Queryable**: Standard tag filtering works as expected | ||
| 76 | 5. **Self-Documenting**: Tag values clearly indicate their purpose | ||
| 77 | |||
| 78 | ## Testing | ||
| 79 | |||
| 80 | All 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 | |||
| 97 | This 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 | |||
| 105 | For future tag changes: | ||
| 106 | 1. Consider versioning in tag values (e.g., `grasp-audit-v2-test-event`) | ||
| 107 | 2. Support querying both old and new tags during transition | ||
| 108 | 3. Document breaking changes clearly | ||
| 109 | 4. 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 | |||
| 120 | To verify the new tag structure: | ||
| 121 | |||
| 122 | ```bash | ||
| 123 | # Run tests | ||
| 124 | nix develop -c cargo test --lib | ||
| 125 | nix develop -c cargo test -- --ignored | ||
| 126 | |||
| 127 | # Run CLI | ||
| 128 | nix 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 | ||