nostr-nip34

A comprehensive npm package implementing NIP-34 for creating and managing git repository announcements on Nostr using event kind 30617.

Features

• 🔐 Complete NIP-34 Implementation - Full support for repository announcements
• 📦 Pure JavaScript Library - No dependencies, works in browser and Node.js
• 🖥️ CLI Tool - Command-line interface for managing repositories
• 🌐 Single Page App - Modern web interface using Preact HTM
• ⚡ ES Modules - Modern JavaScript with ES module support
• 🔒 Cryptographic Security - Uses noble-secp256k1 for signing

Quick Start

Using the Web Interface

Open index.html in your browser and start creating repository announcements immediately:

# Serve locally
npm run serve
# Open http://localhost:8080

Using the CLI

# Install dependencies
npm install

# Generate a new key pair
npm start -- init

# Create a repository announcement
npm start -- create \
  --name "my-project" \
  --description "An awesome project" \
  --clone "https://github.com/user/my-project.git" \
  --web "https://github.com/user/my-project" \
  --relay "wss://relay.damus.io" \
  --relay "wss://nostr.band"

# View repository information
npm start -- info --id "my-project"

Using the Library

import {
  generatePrivateKey,
  getPublicKey,
  createSignedRepositoryEvent,
  createSignedPatchEvent,
  createSignedIssueEvent
} from 'nostr-nip34'

// Generate keys
const privateKey = generatePrivateKey()
const publicKey = getPublicKey(privateKey)

// Create a repository announcement
const repoEvent = await createSignedRepositoryEvent({
  privateKey,
  name: 'my-awesome-project',
  description: 'A revolutionary new tool',
  clone: 'https://github.com/user/my-awesome-project.git',
  web: 'https://github.com/user/my-awesome-project',
  relays: ['wss://relay.damus.io'],
  maintainers: [publicKey]
})

console.log('Repository Event:', repoEvent)

NIP-34 Overview

NIP-34 defines how to use Nostr for git repository management. It includes:

• Repository Announcements (Kind 30617) - Announce repositories with metadata
• Patches (Kind 1617) - Submit patches to repositories
• Issues (Kind 1621) - Report issues and bugs
• Replies (Kind 1622) - Comment on issues and patches

Repository Event Structure

{
  "kind": 30617,
  "tags": [
    ["d", "repository-identifier"],
    ["name", "Repository Name"],
    ["description", "Repository description"],
    ["clone", "git clone URL"],
    ["web", "web URL"],
    ["r", "relay URL"],
    ["p", "maintainer pubkey"]
  ],
  "content": "Repository description"
}

API Reference

Core Functions

generatePrivateKey()

Generates a new random private key.

• Returns: string - 64-character hex private key

getPublicKey(privateKey)

Derives public key from private key.

• privateKey: string - Private key in hex
• Returns: string - Public key in hex

createSignedRepositoryEvent(params)

Creates a signed repository announcement event.

• params: object
  • privateKey - Private key for signing
  • name - Repository name (required)
  • description - Repository description
  • clone - Git clone URL
  • web - Web URL
  • identifier - Custom identifier (defaults to name)
  • relays - Array of relay URLs
  • maintainers - Array of maintainer pubkeys
• Returns: Promise<object> - Signed nostr event

createSignedPatchEvent(params)

Creates a signed patch submission event.

• params: object
  • privateKey - Private key for signing
  • repositoryId - Target repository identifier
  • patch - Git patch content
  • description - Patch description
  • commit - Commit hash
• Returns: Promise<object> - Signed nostr event

createSignedIssueEvent(params)

Creates a signed issue report event.

• params: object
  • privateKey - Private key for signing
  • repositoryId - Target repository identifier
  • title - Issue title
  • content - Issue content/description
• Returns: Promise<object> - Signed nostr event

Utility Functions

parseRepositoryEvent(event)

Parses a repository event into structured data.

• event: object - Nostr event
• Returns: object - Parsed repository data

verifyEvent(event)

Verifies the signature of a nostr event.

• event: object - Nostr event
• Returns: Promise<boolean> - Verification result

CLI Commands

Initialize Configuration

nip34 init [--key <private-key>]

Create Repository

nip34 create \
  --name "project-name" \
  --description "Project description" \
  --clone "git clone URL" \
  --web "web URL" \
  --relay "relay URL" \
  --maintainer "pubkey"

Submit Patch

nip34 patch \
  --repo "repository-id" \
  --patch "patch-content" \
  --description "patch description"

Create Issue

nip34 issue \
  --repo "repository-id" \
  --title "Issue title" \
  --content "Issue description"

List Repositories

nip34 list

Show Repository Info

nip34 info --id "repository-id"

Web Interface

The included single-page application provides a user-friendly interface for:

• 🔐 Key Management - Generate and manage private keys
• 📦 Repository Creation - Create repository announcements
• 🔍 Event Viewing - Parse and view nostr events
• 📱 Responsive Design - Works on desktop and mobile

Key Features

• Secure Key Storage - Keys stored in browser localStorage
• Real-time Validation - Form validation with helpful error messages
• Event Preview - See generated events before publishing
• Mobile Friendly - Responsive design for all devices

Development

Project Structure

nostr-nip34/
├── lib/           # Core library
│   └── index.js   # Main library file
├── cli/           # CLI tool
│   └── index.js   # CLI implementation
├── index.html     # Single page application
├── package.json   # Package configuration
└── README.md      # This file

Dependencies

• noble-secp256k1 - Cryptographic operations
• Preact + HTM - Web interface (CDN)

Building

No build step required! This package uses pure ES modules that work directly in browsers and Node.js.

Testing

npm test

Security Considerations

• 🔐 Private keys are sensitive - store them securely
• 🌐 The web interface stores keys in localStorage - consider using secure storage for production
• 🔒 Always verify event signatures before trusting content
• 🛡️ Use reputable relays to prevent spam and malicious content

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Related

• NIP-34 Specification
• Nostr Protocol
• noble-secp256k1

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]