SwBratcher on Nostr: NIP-9999 ======== Key Revokable Delegates (pre-alpha for feedback) ...
NIP-9999
========
Key Revokable Delegates (pre-alpha for feedback)
-------------------------------
`draft` `optional`
This proposed NIP introduces hierarchical key management for Nostr, enabling users to create subordinate private keys (`nsub`) derived from the master private key (`nsec`). Events signed by `nsub` keys are cryptographically tied to the same public key (`npub`), ensuring compatibility with the current protocol. The model introduces a delegation proof mechanism, enabling secure delegation and revocation of signing authority to subordinate keys without compromising the master key. This design improves account security, simplifies key recovery, and supports scalable multi-client or multi-user scenarios.
---
## Problem Description
Current Nostr key management relies on a single private key (`nsec`) to authenticate and sign all user events. While this design ensures simplicity, it introduces critical vulnerabilities that can compromise account security and usability. If the `nsec` is exposed — whether through user error, malicious software, or insecure client storage — the account is effectively "burned", and recovery is impossible, forcing abandonment of the associated `npub`. This leads to significant problems:
1. **Account Compromise**:
- A compromised `nsec` allows an attacker to impersonate the user, post malicious events, or delete existing events.
- Once leaked, there is no way to revoke access or mitigate damage, as the `nsec` cannot be invalidated or replaced.
2. **Usability Issues**:
- Users must distribute their `nsec` to multiple clients or devices, increasing the risk of compromise.
- High-value accounts (e.g., organizations, influencers, or businesses) require secure, multi-device setups, but the single-key model cannot adequately support this without significant risk.
3. **Loss of Followers and Content**:
- When an `nsec` is compromised, users often abandon their `npub`, losing all followers, social connections, and previously signed content.
- Migrating to a new account is disruptive and diminishes the user experience, especially for high-profile or corporate accounts.
---
## Proposed Use-case Solution
This proposal seeks to resolve the issues described above by introducing a hierarchical key system with subordinate keys, the `nsub`, and revokable delegation proofs with an optional expiry. This model allows users to:
- Securely distribute unlimited subordinate keys to team members, client applications or tracked devices.
- Revoke compromised or retired keys without abandoning the `npub` account with valuable follower and content connections.
- Support high-value, multi-device, or multi-user scenarios.
This hierarchical model aligns with Nostr’s decentralization principles by reducing reliance on centralized recovery mechanisms while maintaining user control and flexibility.
---
## Specification
### Key Hierarchy
1. **Master Private Key:** `nsec`:
- Root key for generating and managing subordinate keys.
- Must remain secure and offline where possible.
2. **Subordinate Private Keys:** `nsub`
- Deterministically derived from the master private key using a hierarchical deterministic (HD) method (e.g., BIP-32 HD Wallet principles).
- Each `nsub` is associated with a unique path or purpose (e.g., per client or per device).
- Delegation proofs bind each `nsub` to the master `nsec`.
3. **Public Key:** `npub`
- Remains unchanged for the user and maps to all subordinate keys.
---
### Delegation Proofs
Delegation proofs authorize subordinate keys (`nsub`) to sign events on behalf of the master key (`nsec`).
#### Format:
```json
{
"delegator_pubkey": "<master_npub>",
"delegatee_pubkey": "<subordinate_public_key>",
"conditions": {
"event_kinds": [1, 0],
"expiration": "<expiration_timestamp>"
},
"purpose": "Client authentication for mobile device",
"version": 1,
"signature": "<signed_by_nsec>"
}
```
### Fields
- **delegator_pubkey**: The public key of the master key.
- **delegatee_pubkey**: The public key of the subordinate key.
- **conditions**: Restrictions for the subordinate key.
- **event_kinds**: Defines the kinds of events the `nsub` can sign.
- **expiration**: Optional expiration timestamp for the delegation proof.
- **purpose**: Context for the delegation proof (optional).
- **version**: Version number to ensure future extensibility.
- **signature**: Cryptographic signature of the delegation proof generated by the `nsec`.
---
### Event Kind Declarations and Clarifications
To implement hierarchical key management effectively, this NIP introduces two new event kinds: **Delegation Proof Event** and **Revocation Event**. These event kinds are critical to ensuring secure delegation and revocation processes within the Nostr protocol.
#### **Event Kind:** Delegation Proof (kind: 30080)
**Purpose:** Establishes the relationship between the master key (nsec) and subordinate keys (nsub). It sets conditions such as permissions and expiration for the subordinate key’s actions.
Format:
```json
{
"delegator_pubkey": "<master_npub>",
"delegatee_pubkey": "<subordinate_public_key>",
"conditions": {
"event_kinds": [1, 0],
"expiration": "<expiration_timestamp>"
},
"purpose": "Client authentication for mobile device",
"version": 1,
"signature": "<signed_by_nsec>"
}
```
Key Points:
- Cryptographically ties the subordinate key to the master key.
- Specifies conditions like event kinds and expiration to limit the subordinate key’s usage.
- Enables scalable setups for multi-device or multi-user accounts.
#### **Event Kind:** Revocation Event (kind: 30081)
**Purpose:** Allows the master key (nsec) to revoke a subordinate key (nsub), invalidating its signing authority and ensuring account security.
Format:
```json
{
"npub": "<master_npub>",
"revoke_nsub": "<subordinate_public_key>",
"reason": "Key compromised",
"timestamp": "<timestamp>",
"expiration": "<optional_expiration_timestamp>",
"signature": "<signed_by_nsec>"
}
```
Key Points:
- Relays must reject events signed by revoked keys.
- Enables temporary suspensions through the optional expiration field.
- Provides clear reasons for revocation (e.g., key_compromised, expired).
#### Format:
```json
{
"npub": "<master_npub>",
"revoke_nsub": "<subordinate_public_key>",
"reason": "Key compromised",
"timestamp": "<timestamp>",
"expiration": "<optional_expiration_timestamp>",
"signature": "<signed_by_nsec>"
}
```
### Functionality
- **Relays**: Must reject events signed by revoked keys.
- **Clients**: Should mark affected events as invalid or untrusted.
---
### Benefits
- **Enumerated Reasons**: Provides clear context for revocation (`key_compromised`, `expired`, etc.).
- **Temporary Suspensions**: Optional expiration field supports time-bound revocations.
---
### Use Cases
1. **Revoking a Compromised Client Key**:\
A user revokes a compromised `nsub` key and prevents further misuse while maintaining account integrity.
2. **Multi-Device Security**:\
Each device is issued its own `nsub`, isolating risk and ensuring independent security.
3. **Corporate Account Management**:\
Team members use individual `nsub` keys for controlled access. Revoked keys do not affect the entire account.
4. **Mitigating Accidental Exposure**:\
An exposed `nsub` can be revoked while other keys remain valid, reducing the risk of total compromise.
5. **High-Value Accounts**:\
Influencers and organizations can recover from partial compromises without disrupting their presence.
---
## Relay and Client Implementation
### Relay Optimization
To enhance relay performance while supporting delegation proofs and revocation events, two complementary optimization approaches are proposed:
#### **1. Caching Validated Proofs**
- **Description**: Relays cache validated delegation proofs to minimize repetitive cryptographic checks.
- **Implementation**:
- Cache structure stores mappings of `delegatee_pubkey` to their validated conditions (e.g., expiration timestamps, event kinds).
- Example cache entry:
```json
{
"delegatee_pubkey": "<subordinate_public_key>",
"valid_until": "<expiration_timestamp>",
"event_kinds": [1, 0],
"verified": true
}
```
- **Advantages**:
- Reduces computational overhead during high-traffic scenarios.
- Ensures quick lookup for relay processing.
#### **2. Efficient Cryptographic Libraries**
- **Description**: Utilize high-performance cryptographic libraries to handle signature verification for delegation proofs and revocation events.
- **Recommendation**:
- Libraries such as `libsecp256k1` provide optimized implementations for cryptographic operations, ensuring scalability for relays handling high-volume workloads.
- **Advantages**:
- Improves signature verification speed.
- Reduces latency for processing delegation and revocation events.
#### Comparison of Optimization Approaches
| **Optimization** | **Focus** | **Advantages** | **Trade-offs** |
| --- | --- | --- | --- |
| **Caching Validated Proofs** | Reduces repetitive cryptographic checks | Faster relay processing for validated proofs | Requires memory for storing cached data |
| **Efficient Cryptographic Libraries** | Improves cryptographic operation speed | Enhances scalability for high traffic loads | May depend on library compatibility |
Implementing both optimizations can maximize relay performance by balancing computational efficiency and scalability. Caching ensures quick lookups, while optimized libraries handle cryptographic operations efficiently.
---
### Client UX Recommendations
To ensure smooth adoption and ease of use, client applications should provide intuitive user experiences for managing hierarchical keys and handling revocations. The following recommendations focus on enhancing usability while maintaining robust security:
---
#### **Clear Interfaces For**:
1. **Generating and Managing Subordinate Keys**:
1. **Key Generation**:
- Provide a simple, guided process for generating subordinate keys (`nsub`) derived from the master key (`nsec`).
- Include visual and textual clarity to demystify hierarchical key generation and handling instructions.
2. **Key Management**:
- Display a list of all active subordinate keys with default or custom (user-created) metadata such as:
- Key purpose (e.g., "Specified Client Key" or "John Doe's Key").
- Expiration time/date (if applicable).
- Associated permissions (e.g., allowed event kinds).
- Allow users to deactivate or revoke keys directly from the interface.
2. **Revoking Keys with Minimal User Effort**:
- **Revocation Workflow**:
- Offer a one-click revocation process for compromised or obsolete subordinate keys.
- Prompt users to confirm revocation to prevent accidental irreversable actions.
- **Feedback Mechanism**:
- Provide real-time feedback on revocation status, such as:
- "Key successfully revoked."
- "Revocation broadcast pending relay confirmation."
- **Notifications**:
- Notify the user if a revoked key is still in use by unauthorized devices or relays.
---
#### **Additional Client Feature Considerations**:
1. **Key Rotation Reminders**:
- Implement reminders for periodic key rotation to maintain security best practices.
2. **Audit Logs**:
- Maintain a log of key generation, usage, and revocation activities for user reference and troubleshooting.
3. **Multi-Language Support**:
- Ensure interfaces are localized to support a global user base.
4. **Backup and Recovery**:
- Guide users to securely back up their master key (`nsec`) and subordinate key configurations to avoid accidental lockouts.
5. **Expiration Alerts**:
- Implement reminders for key upcoming expirations to avoid accidental lockouts if a manual renew is intended.
---
#### **Example Error Messages**
For Revoked Keys: Provide clear error messages for revoked or invalid keys to aid user understanding and relay troubleshooting:
```json
{
"status": "error",
"message": "The key <subordinate_public_key> has been revoked by the master key or has expired as scheduled.",
"timestamp": "<current_timestamp>"
}
```
### Backwards Compatibility
- This proposal does not alter the existing public key (`npub`) structure, ensuring compatibility with current relays and clients.
- Systems not implementing delegation proofs will continue to function normally but will not benefit from enhanced security.
---
### Acknowledgments
- **Status**: Draft (this pre-alpha draft version is the first request for feedback.)
- **Prepared By**: @swbratcher // swb@primal.net
- **Feedback Specifically Requested from known client devs:**
@Will npub1xtscya34g58tk0z605fvr788k263gsu6cy9x0mhnm87echrgufzsevkk5s
@fiatjaf npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6
@miljan npub16c0nh3dnadzqpm76uctf5hqhe2lny344zsmpm6feee9p5rdxaa9q586nvr
@PABLOF7z npub1l2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqutajft
@Vitor Pamplona npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z
- **Date**: 2024/11/28
========
Key Revokable Delegates (pre-alpha for feedback)
-------------------------------
`draft` `optional`
This proposed NIP introduces hierarchical key management for Nostr, enabling users to create subordinate private keys (`nsub`) derived from the master private key (`nsec`). Events signed by `nsub` keys are cryptographically tied to the same public key (`npub`), ensuring compatibility with the current protocol. The model introduces a delegation proof mechanism, enabling secure delegation and revocation of signing authority to subordinate keys without compromising the master key. This design improves account security, simplifies key recovery, and supports scalable multi-client or multi-user scenarios.
---
## Problem Description
Current Nostr key management relies on a single private key (`nsec`) to authenticate and sign all user events. While this design ensures simplicity, it introduces critical vulnerabilities that can compromise account security and usability. If the `nsec` is exposed — whether through user error, malicious software, or insecure client storage — the account is effectively "burned", and recovery is impossible, forcing abandonment of the associated `npub`. This leads to significant problems:
1. **Account Compromise**:
- A compromised `nsec` allows an attacker to impersonate the user, post malicious events, or delete existing events.
- Once leaked, there is no way to revoke access or mitigate damage, as the `nsec` cannot be invalidated or replaced.
2. **Usability Issues**:
- Users must distribute their `nsec` to multiple clients or devices, increasing the risk of compromise.
- High-value accounts (e.g., organizations, influencers, or businesses) require secure, multi-device setups, but the single-key model cannot adequately support this without significant risk.
3. **Loss of Followers and Content**:
- When an `nsec` is compromised, users often abandon their `npub`, losing all followers, social connections, and previously signed content.
- Migrating to a new account is disruptive and diminishes the user experience, especially for high-profile or corporate accounts.
---
## Proposed Use-case Solution
This proposal seeks to resolve the issues described above by introducing a hierarchical key system with subordinate keys, the `nsub`, and revokable delegation proofs with an optional expiry. This model allows users to:
- Securely distribute unlimited subordinate keys to team members, client applications or tracked devices.
- Revoke compromised or retired keys without abandoning the `npub` account with valuable follower and content connections.
- Support high-value, multi-device, or multi-user scenarios.
This hierarchical model aligns with Nostr’s decentralization principles by reducing reliance on centralized recovery mechanisms while maintaining user control and flexibility.
---
## Specification
### Key Hierarchy
1. **Master Private Key:** `nsec`:
- Root key for generating and managing subordinate keys.
- Must remain secure and offline where possible.
2. **Subordinate Private Keys:** `nsub`
- Deterministically derived from the master private key using a hierarchical deterministic (HD) method (e.g., BIP-32 HD Wallet principles).
- Each `nsub` is associated with a unique path or purpose (e.g., per client or per device).
- Delegation proofs bind each `nsub` to the master `nsec`.
3. **Public Key:** `npub`
- Remains unchanged for the user and maps to all subordinate keys.
---
### Delegation Proofs
Delegation proofs authorize subordinate keys (`nsub`) to sign events on behalf of the master key (`nsec`).
#### Format:
```json
{
"delegator_pubkey": "<master_npub>",
"delegatee_pubkey": "<subordinate_public_key>",
"conditions": {
"event_kinds": [1, 0],
"expiration": "<expiration_timestamp>"
},
"purpose": "Client authentication for mobile device",
"version": 1,
"signature": "<signed_by_nsec>"
}
```
### Fields
- **delegator_pubkey**: The public key of the master key.
- **delegatee_pubkey**: The public key of the subordinate key.
- **conditions**: Restrictions for the subordinate key.
- **event_kinds**: Defines the kinds of events the `nsub` can sign.
- **expiration**: Optional expiration timestamp for the delegation proof.
- **purpose**: Context for the delegation proof (optional).
- **version**: Version number to ensure future extensibility.
- **signature**: Cryptographic signature of the delegation proof generated by the `nsec`.
---
### Event Kind Declarations and Clarifications
To implement hierarchical key management effectively, this NIP introduces two new event kinds: **Delegation Proof Event** and **Revocation Event**. These event kinds are critical to ensuring secure delegation and revocation processes within the Nostr protocol.
#### **Event Kind:** Delegation Proof (kind: 30080)
**Purpose:** Establishes the relationship between the master key (nsec) and subordinate keys (nsub). It sets conditions such as permissions and expiration for the subordinate key’s actions.
Format:
```json
{
"delegator_pubkey": "<master_npub>",
"delegatee_pubkey": "<subordinate_public_key>",
"conditions": {
"event_kinds": [1, 0],
"expiration": "<expiration_timestamp>"
},
"purpose": "Client authentication for mobile device",
"version": 1,
"signature": "<signed_by_nsec>"
}
```
Key Points:
- Cryptographically ties the subordinate key to the master key.
- Specifies conditions like event kinds and expiration to limit the subordinate key’s usage.
- Enables scalable setups for multi-device or multi-user accounts.
#### **Event Kind:** Revocation Event (kind: 30081)
**Purpose:** Allows the master key (nsec) to revoke a subordinate key (nsub), invalidating its signing authority and ensuring account security.
Format:
```json
{
"npub": "<master_npub>",
"revoke_nsub": "<subordinate_public_key>",
"reason": "Key compromised",
"timestamp": "<timestamp>",
"expiration": "<optional_expiration_timestamp>",
"signature": "<signed_by_nsec>"
}
```
Key Points:
- Relays must reject events signed by revoked keys.
- Enables temporary suspensions through the optional expiration field.
- Provides clear reasons for revocation (e.g., key_compromised, expired).
#### Format:
```json
{
"npub": "<master_npub>",
"revoke_nsub": "<subordinate_public_key>",
"reason": "Key compromised",
"timestamp": "<timestamp>",
"expiration": "<optional_expiration_timestamp>",
"signature": "<signed_by_nsec>"
}
```
### Functionality
- **Relays**: Must reject events signed by revoked keys.
- **Clients**: Should mark affected events as invalid or untrusted.
---
### Benefits
- **Enumerated Reasons**: Provides clear context for revocation (`key_compromised`, `expired`, etc.).
- **Temporary Suspensions**: Optional expiration field supports time-bound revocations.
---
### Use Cases
1. **Revoking a Compromised Client Key**:\
A user revokes a compromised `nsub` key and prevents further misuse while maintaining account integrity.
2. **Multi-Device Security**:\
Each device is issued its own `nsub`, isolating risk and ensuring independent security.
3. **Corporate Account Management**:\
Team members use individual `nsub` keys for controlled access. Revoked keys do not affect the entire account.
4. **Mitigating Accidental Exposure**:\
An exposed `nsub` can be revoked while other keys remain valid, reducing the risk of total compromise.
5. **High-Value Accounts**:\
Influencers and organizations can recover from partial compromises without disrupting their presence.
---
## Relay and Client Implementation
### Relay Optimization
To enhance relay performance while supporting delegation proofs and revocation events, two complementary optimization approaches are proposed:
#### **1. Caching Validated Proofs**
- **Description**: Relays cache validated delegation proofs to minimize repetitive cryptographic checks.
- **Implementation**:
- Cache structure stores mappings of `delegatee_pubkey` to their validated conditions (e.g., expiration timestamps, event kinds).
- Example cache entry:
```json
{
"delegatee_pubkey": "<subordinate_public_key>",
"valid_until": "<expiration_timestamp>",
"event_kinds": [1, 0],
"verified": true
}
```
- **Advantages**:
- Reduces computational overhead during high-traffic scenarios.
- Ensures quick lookup for relay processing.
#### **2. Efficient Cryptographic Libraries**
- **Description**: Utilize high-performance cryptographic libraries to handle signature verification for delegation proofs and revocation events.
- **Recommendation**:
- Libraries such as `libsecp256k1` provide optimized implementations for cryptographic operations, ensuring scalability for relays handling high-volume workloads.
- **Advantages**:
- Improves signature verification speed.
- Reduces latency for processing delegation and revocation events.
#### Comparison of Optimization Approaches
| **Optimization** | **Focus** | **Advantages** | **Trade-offs** |
| --- | --- | --- | --- |
| **Caching Validated Proofs** | Reduces repetitive cryptographic checks | Faster relay processing for validated proofs | Requires memory for storing cached data |
| **Efficient Cryptographic Libraries** | Improves cryptographic operation speed | Enhances scalability for high traffic loads | May depend on library compatibility |
Implementing both optimizations can maximize relay performance by balancing computational efficiency and scalability. Caching ensures quick lookups, while optimized libraries handle cryptographic operations efficiently.
---
### Client UX Recommendations
To ensure smooth adoption and ease of use, client applications should provide intuitive user experiences for managing hierarchical keys and handling revocations. The following recommendations focus on enhancing usability while maintaining robust security:
---
#### **Clear Interfaces For**:
1. **Generating and Managing Subordinate Keys**:
1. **Key Generation**:
- Provide a simple, guided process for generating subordinate keys (`nsub`) derived from the master key (`nsec`).
- Include visual and textual clarity to demystify hierarchical key generation and handling instructions.
2. **Key Management**:
- Display a list of all active subordinate keys with default or custom (user-created) metadata such as:
- Key purpose (e.g., "Specified Client Key" or "John Doe's Key").
- Expiration time/date (if applicable).
- Associated permissions (e.g., allowed event kinds).
- Allow users to deactivate or revoke keys directly from the interface.
2. **Revoking Keys with Minimal User Effort**:
- **Revocation Workflow**:
- Offer a one-click revocation process for compromised or obsolete subordinate keys.
- Prompt users to confirm revocation to prevent accidental irreversable actions.
- **Feedback Mechanism**:
- Provide real-time feedback on revocation status, such as:
- "Key successfully revoked."
- "Revocation broadcast pending relay confirmation."
- **Notifications**:
- Notify the user if a revoked key is still in use by unauthorized devices or relays.
---
#### **Additional Client Feature Considerations**:
1. **Key Rotation Reminders**:
- Implement reminders for periodic key rotation to maintain security best practices.
2. **Audit Logs**:
- Maintain a log of key generation, usage, and revocation activities for user reference and troubleshooting.
3. **Multi-Language Support**:
- Ensure interfaces are localized to support a global user base.
4. **Backup and Recovery**:
- Guide users to securely back up their master key (`nsec`) and subordinate key configurations to avoid accidental lockouts.
5. **Expiration Alerts**:
- Implement reminders for key upcoming expirations to avoid accidental lockouts if a manual renew is intended.
---
#### **Example Error Messages**
For Revoked Keys: Provide clear error messages for revoked or invalid keys to aid user understanding and relay troubleshooting:
```json
{
"status": "error",
"message": "The key <subordinate_public_key> has been revoked by the master key or has expired as scheduled.",
"timestamp": "<current_timestamp>"
}
```
### Backwards Compatibility
- This proposal does not alter the existing public key (`npub`) structure, ensuring compatibility with current relays and clients.
- Systems not implementing delegation proofs will continue to function normally but will not benefit from enhanced security.
---
### Acknowledgments
- **Status**: Draft (this pre-alpha draft version is the first request for feedback.)
- **Prepared By**: @swbratcher // swb@primal.net
- **Feedback Specifically Requested from known client devs:**
@Will npub1xtscya34g58tk0z605fvr788k263gsu6cy9x0mhnm87echrgufzsevkk5s
@fiatjaf npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6
@miljan npub16c0nh3dnadzqpm76uctf5hqhe2lny344zsmpm6feee9p5rdxaa9q586nvr
@PABLOF7z npub1l2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqutajft
@Vitor Pamplona npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z
- **Date**: 2024/11/28