-
@ Brunswick
2025-03-26 21:03:59Introduction
Nutsax is a capability-based access control system for Nostr relays, designed to provide flexible, privacy-preserving rate limiting, permissioning, and operation-scoped token redemption.
At its core, Nutsax introduces:
- Blind-signed tokens, issued by relays, for specific operation types.
- Token redemption as part of Nostr event publishing or interactions.
- Encrypted token storage using existing Nostr direct message infrastructure, allowing portable, persistent, and private storage of these tokens — the Nutsax.
This mechanism augments the existing Nostr protocol without disrupting adoption, requiring no changes to NIP-01 for clients or relays that don’t opt into the system.
Motivation
Nostr relays currently have limited tools for abuse prevention and access control. Options like IP banning, whitelisting, or monetized access are coarse and often centralized.
Nutsax introduces:
- Fine-grained, operation-specific access control using cryptographic tokens.
- Blind signature protocols to issue tokens anonymously, preserving user privacy.
- A native way to store and recover tokens using Nostr’s encrypted event system.
This allows relays to offer:
- Optional access policies (e.g., “3 posts per hour unless you redeem a token”)
- Paid or invite-based features (e.g., long-term subscriptions, advanced filters)
- Temporary elevation of privileges (e.g., bypass slow mode for one message)
All without requiring accounts, emails, or linking identity beyond the user’s
npub.Core Components
1. Operation Tokens
Tokens are blind-signed blobs issued by the relay, scoped to a specific operation type (e.g.,
"write","filter-subscribe","broadcast").- Issued anonymously: using a blind signature protocol.
- Validated on redemption: at message submission or interaction time.
- Optional and redeemable: the relay decides when to enforce token redemption.
Each token encodes:
- Operation type (string)
- Relay ID (to scope the token)
- Expiration (optional)
- Usage count or burn-on-use flag
- Random nonce (blindness)
Example (before blinding):
json { "relay": "wss://relay.example", "operation": "write", "expires": 1720000000, "nonce": "b2a8c3..." }This is then blinded and signed by the relay.
2. Token Redemption
Clients include tokens when submitting events or requests to the relay.
Token included via event tag:
json ["token", "<base64-encoded-token>", "write"]Redemption can happen:
- Inline with any event (kind 1, etc.)
- As a standalone event (e.g., ephemeral kind 20000)
- During session initiation (optional AUTH extension)
The relay validates the token:
- Is it well-formed?
- Is it valid for this relay and operation?
- Is it unexpired?
- Has it been used already? (for burn-on-use)
If valid, the relay accepts the event or upgrades the rate/permission scope.
3. Nutsax: Private Token Storage on Nostr
Tokens are stored securely in the client’s Nutsax, a persistent, private archive built on Nostr’s encrypted event system.
Each token is stored in a kind 4 or kind 44/24 event, encrypted with the client’s own
npub.Example:
json { "kind": 4, "tags": [ ["p", "<your npub>"], ["token-type", "write"], ["relay", "wss://relay.example"] ], "content": "<encrypted token blob>", "created_at": 1234567890 }This allows clients to:
- Persist tokens across restarts or device changes.
- Restore tokens after reinstalling or reauthenticating.
- Port tokens between devices.
All without exposing the tokens to the public or requiring external storage infrastructure.
Client Lifecycle
1. Requesting Tokens
- Client authenticates to relay (e.g., via NIP-42).
- Requests blind-signed tokens:
- Sends blinded token requests.
- Receives blind signatures.
- Unblinds and verifies.
2. Storing Tokens
- Each token is encrypted to the user’s own
npub. - Stored as a DM (kind 4 or compatible encrypted event).
- Optional tagging for organization.
3. Redeeming Tokens
- When performing a token-gated operation (e.g., posting to a limited relay), client includes the appropriate token in the event.
- Relay validates and logs/consumes the token.
4. Restoring the Nutsax
- On device reinstallation or session reset, the client:
- Reconnects to relays.
- Scans encrypted DMs.
- Decrypts and reimports available tokens.
Privacy Model
- Relays issuing tokens do not know which tokens were redeemed (blind signing).
- Tokens do not encode sender identity unless the client opts to do so.
- Only the recipient (
npub) can decrypt their Nutsax. - Redemption is pseudonymous — tied to a key, not to external identity.
Optional Enhancements
- Token index tag: to allow fast search and categorization.
- Multiple token types: read, write, boost, subscribe, etc.
- Token delegation: future support for transferring tokens via encrypted DM to another
npub. - Token revocation: relays can publish blacklists or expiration feeds if needed.
Compatibility
- Fully compatible with NIP-01, NIP-04 (encrypted DMs), and NIP-42 (authentication).
- Non-disruptive: relays and clients can ignore tokens if not supported.
- Ideal for layering on top of existing infrastructure and monetization strategies.
Conclusion
Nutsax offers a privacy-respecting, decentralized way to manage access and rate limits in the Nostr ecosystem. With blind-signed, operation-specific tokens and encrypted, persistent storage using native Nostr mechanisms, it gives relays and clients new powers without sacrificing Nostr’s core principles: simplicity, openness, and cryptographic self-sovereignty.