diff --git a/PROTOCOL_INVENTORY.md b/PROTOCOL_INVENTORY.md index af8d232..037ac57 100644 --- a/PROTOCOL_INVENTORY.md +++ b/PROTOCOL_INVENTORY.md @@ -6,20 +6,36 @@ This file tracks external protocol specifications and libraries used in this rep | Protocol / Spec | Implementation Points | Compliance Status | Notes | | :--- | :--- | :--- | :--- | -| **NIP-01** (Basic Protocol) | `src/lib.mjs`, `src/lock-ops.mjs` | Compliant | Uses `nostr-tools` for event creation, signing, and relay communication. | +| **NIP-01** (Basic Protocol) | `src/lib.mjs`, `src/lock-ops.mjs`, `src/relay-health.mjs` | Compliant | Uses `nostr-tools` for event creation, signing, and relay communication. | | **NIP-04** (Encrypted Direct Message) | N/A | Unknown | Not explicitly used in lock logic, but mentioned in test prompts. | +| **NIP-33** (Parameterized Replaceable Events) | `src/lock-ops.mjs` | Compliant | Defines the mechanics for Kind 30078 updates (d-tags). | +| **NIP-40** (Expiration Timestamp) | `src/lock-ops.mjs` | Compliant | Parses `expiration` tag to filter active locks. | | **NIP-42** (Authentication) | N/A | Unknown | Not currently implemented in lock logic. | -| **NIP-33** (Parameterized Replaceable Events) | `src/lock-ops.mjs` | Compliant | Used for lock events (Kind 30078 is used, which is Application Specific Data, functionally similar to replaceable events). | +| **NIP-78** (Application-specific Data) | `src/lock-ops.mjs` | Compliant | Uses Kind 30078 for distributed lock state. | + +## Other Protocols + +| Protocol | Implementation Points | Compliance Status | Notes | +| :--- | :--- | :--- | :--- | +| **HTTP/1.1** | `src/dashboard.mjs`, `dashboard/` | Compliant | Dashboard server uses Node.js `http` module. | +| **WebSocket** | `src/relay-health.mjs` | Compliant | Raw `ws` usage for health probes; `nostr-tools` for standard relay comms. | +| **JSON** | `src/lock-ops.mjs`, `src/ops.mjs` | Compliant | Ubiquitous for event content and config files. | + +## Internal / Custom Protocols + +| Name | Kind / ID | Implementation | Notes | +| :--- | :--- | :--- | :--- | +| **Relay Health Probe** | Kind `27235` | `src/relay-health.mjs` | Custom ephemeral event kind used for deep reachability checks. | ## Libraries | Library | Version | Usage | Risks | | :--- | :--- | :--- | :--- | -| `nostr-tools` | `2.19.4` | Core Nostr primitives (keys, events, pool). | Supply chain risk. pinned version recommended. | -| `ws` | `8.19.0` | WebSocket client for Node.js. | standard library for Node.js websocket support. | +| `nostr-tools` | `2.19.4` | Core Nostr primitives (keys, events, pool). | Supply chain risk. Pinned version recommended. | +| `ws` | `8.19.0` | WebSocket client for Node.js. | Standard library for Node.js websocket support. | ## Implementation details -- **Locking Mechanism**: Uses Kind 30078 (Application Specific Data) for lock events. +- **Locking Mechanism**: Uses Kind 30078 (NIP-78) with NIP-33 semantics (d-tags) and NIP-40 expiration. - **Relay Communication**: Uses `SimplePool` from `nostr-tools` for querying and publishing. -- **Health Checks**: Uses raw `WebSocket` connections in `src/relay-health.mjs` for deep health probes. +- **Health Checks**: Uses raw `WebSocket` connections in `src/relay-health.mjs` for deep health probes (Kind 27235). diff --git a/protocol-report-2026-02-17.md b/protocol-report-2026-02-17.md new file mode 100644 index 0000000..1bbc99d --- /dev/null +++ b/protocol-report-2026-02-17.md @@ -0,0 +1,32 @@ +# Protocol Compliance Report - 2026-02-17 + +**Agent:** protocol-research-agent +**Date:** 2026-02-17 + +## Executive Summary +The repository maintains strong compliance with core Nostr specifications (NIP-01, NIP-33) and leverages NIP-78 (Application-specific Data) effectively for its distributed locking mechanism. Protocol usage is centralized in `src/lock-ops.mjs` and `src/relay-health.mjs`. + +## Findings + +### 1. Nostr Protocol Compliance +- **NIP-01 (Basic Protocol):** Fully implemented via `nostr-tools`. +- **NIP-33 (Parameterized Replaceable Events):** Correctly used for managing lock state updates via `d` tags. +- **NIP-40 (Expiration Timestamp):** Implemented in `src/lock-ops.mjs`. The `expiration` tag is parsed and respected during lock validation, ensuring stale locks are automatically pruned. +- **NIP-78 (Application-specific Data):** Kind 30078 is the primary vehicle for lock data, aligning with the spec's intent for non-social app data. + +### 2. Custom Protocol Usage +- **Relay Health Probes (Kind 27235):** `src/relay-health.mjs` uses an ephemeral event Kind `27235` to test relay write/read round-trip capability. This appears to be an internal convention or experimental kind not yet standardized. +- **Risk Assessment:** Low. The events are ephemeral and scoped to the application namespace. + +### 3. Web & Transport +- **HTTP/1.1:** `src/dashboard.mjs` implements a standard Node.js HTTP server for the dashboard UI. +- **WebSocket:** Raw `ws` usage in `src/relay-health.mjs` provides fine-grained control for connection health checks, complementing the higher-level `SimplePool` abstraction. + +### 4. Gaps & Unknowns +- **NIP-42 (Authentication):** Not currently implemented. As relay ecosystem evolves, paid/auth-required relays may become inaccessible without NIP-42 support. + +## Recommendations + +1. **Document Custom Kinds:** Ensure Kind 27235 is clearly documented as internal-only to prevent confusion with standardized kinds. +2. **Monitor NIP-42:** Keep NIP-42 on the roadmap if relay reliability issues arise due to auth requirements. +3. **Maintain Dependency Hygiene:** Continue pinning `nostr-tools` to avoid upstream breaking changes in protocol implementation. diff --git a/task-logs/daily/2026-02-17T01-06-52Z__protocol-research-agent__completed.md b/task-logs/daily/2026-02-17T01-06-52Z__protocol-research-agent__completed.md new file mode 100644 index 0000000..1d0c0f5 --- /dev/null +++ b/task-logs/daily/2026-02-17T01-06-52Z__protocol-research-agent__completed.md @@ -0,0 +1,27 @@ +--- +agent: protocol-research-agent +status: completed +date: 2026-02-17 +platform: jules +--- + +# Daily Task: Protocol Research + +**Agent:** protocol-research-agent +**Date:** 2026-02-17 +**Status:** Completed + +## Summary +- Scanned codebase for protocol usage (Nostr, HTTP, WebSocket). +- Updated `PROTOCOL_INVENTORY.md` with: + - NIP-40 (Expiration) compliance. + - NIP-78 (App Data) compliance. + - HTTP/WebSocket usage details. + - Custom Kind 27235 (Relay Health Probe) documentation. +- Created `protocol-report-2026-02-17.md` with detailed findings. +- Verified system health via unit tests (`test/lock-ops.test.mjs`, `test/relay-health-thresholds.test.mjs`). +- Performed memory retrieval and storage cycles. + +## Artifacts +- `PROTOCOL_INVENTORY.md` (Updated) +- `protocol-report-2026-02-17.md` (Created)