NostrBridge is a rule-based SaaS webhook transformer hosted on Cloudflare. It allows users to define custom HTTP webhooks (e.g., for GitHub releases, Stripe billing events, RSS feeds) that automatically ingest JSON payloads, format them using custom templates, cryptographically sign them as Nostr events, and publish them to configured Nostr relays.
Monetization is built directly into the protocol via zaps (NIP-57/LNURL-pay) where users pay-per-execution.
NostrBridge is released under the PolyForm Noncommercial License 1.0.0.
- Allowed: Personal self-hosting, non-commercial research, non-commercial education, private testing, and open-source contributions.
- Prohibited: Commercial exploitation, running the software as a paid hosted service, or embedding it in a commercial SaaS product without express permission.
For details, read the full text in LICENSE.
- Monorepo Manager:
pnpmworkspace protocol - API (Hono on Cloudflare Workers): Low-latency edge router handles authentication, mapping engine, relay broadcasting, and zap verification.
- Dashboard (Vite + React + TailAdmin): Single Page Application styled with TailAdmin UI & Tailwind CSS for rules setup, logs, and top-ups.
- Marketing Site (Astro.js): Highly optimized static/SSR marketing site deployed to Cloudflare Pages.
- Database & State Management:
- Cloudflare D1: Relational SQL database for users, rules, log audits, and invoices.
- Cloudflare KV: High-speed cache for rules lookup and credit balance validation.
- Durable Objects: Rate-limiting and transient state coordination (e.g., NIP-46 socket coordination).
- Nostr Integration:
nostr-toolsfor cryptographic signing, NIP-98 authentication, and connection pooling to relays.
The codebase is organized as a monorepo workspace under the following directory layout:
nostrbridge/
├── .github/ # Issue & PR templates, community workflows
├── apps/
│ ├── api/ # Hono App on Cloudflare Workers
│ │ ├── src/ # API Endpoint routers and handler logic
│ │ ├── migrations/ # D1 Database SQL migration files
│ │ └── wrangler.toml# Cloudflare Workers configuration
│ ├── dashboard/ # React SPA
│ │ ├── src/ # Dashboard pages, forms, and logs components
│ │ └── package.json # Dashboards build dependencies
│ └── landing/ # Astro.js Marketing Site
│ ├── src/ # Astro page templates and documentation guides
│ └── package.json # Astro build configuration
├── packages/
│ ├── shared/ # Types, interfaces, and Zod schemas shared across apps
│ ├── nostr/ # Event signers, decryptors, and relay broadcasting wrappers
│ └── config/ # Shared tsconfigs, tailwind configurations, and ESLint settings
├── CONTRIBUTING.md # Developer guide & Supervised AI policy
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
├── SECURITY.md # Security policy & vulnerability reporting
├── LICENSE # PolyForm Noncommercial License 1.0.0
├── package.json # Workspace root package settings
├── pnpm-workspace.yaml # Workspace configuration defining app boundaries
└── .nvmrc # Node.js target environment configuration
- Node.js: v20.x (check configuration using
.nvmrc) - Node Version Manager (
nvm) - Package Manager:
pnpm(v8 or later recommended) - Cloudflare Wrangler CLI: Installed globally or run via pnpm (
wrangler)
Clone the repository and install all workspace dependencies:
# Ensure you are using the correct Node.js version
nvm use
# Install dependencies and link local workspace packages
pnpm installSet up your local SQLite database migrations using Wrangler:
# Verify Node version and run migration scripts
nvm use
pnpm --filter api wrangler d1 migrations apply DB --localStart the Hono API, React Dashboard, and Astro Marketing Site concurrently:
# Run all dev servers in parallel
nvm use
pnpm dev- API Dev Server:
http://localhost:8787 - Dashboard SPA:
http://localhost:5173 - Marketing Landing Page:
http://localhost:4321
NostrBridge is designed to be easily self-hosted for personal use on your own Cloudflare account.
- Create a free Cloudflare Account.
- Install & authenticate Wrangler CLI:
nvm use nvm exec pnpm wrangler login
Create your D1 database and KV namespace:
nvm use
# Create D1 Database
pnpm --filter api wrangler d1 create nostrbridge-db
# Create KV Namespace
pnpm --filter api wrangler kv:namespace create CACHE_KVUpdate apps/api/wrangler.toml with the returned database_id and kv_namespace id.
Apply D1 schema migrations to your remote database:
nvm use
pnpm --filter api wrangler d1 migrations apply DB --remoteSet secrets required for encryption and authentication:
nvm use
pnpm --filter api wrangler secret put ENCRYPTION_KEY
pnpm --filter api wrangler secret put JWT_SECRETDeploy the API Worker and frontend apps:
nvm use
# Deploy API Worker
pnpm --filter api wrangler deploy
# Deploy Dashboard SPA to Cloudflare Pages
pnpm --filter dashboard build
pnpm --filter dashboard wrangler pages deploy dist/ --project-name=nostrbridge-dashboardCreate this file locally for local development. Never commit it to git.
# AES encryption key (32 bytes base64/hex) to encrypt stored keys at rest
ENCRYPTION_KEY="your-super-secret-256-bit-aes-encryption-key"
# Secret token signing key for JWT issuance
JWT_SECRET="your-jwt-auth-signing-secret"We welcome contributions! Please review our community guidelines before opening an issue or Pull Request:
- CONTRIBUTING.md: Developer setup, code standards, and Supervised AI Policy (NO VIBE CODE).
- CODE_OF_CONDUCT.md: Community standards and behavior.
- SECURITY.md: Vulnerability reporting and cryptographic security guidelines.
NostrBridge permits AI-assisted contributions under strict human supervision:
- No Vibe Coding: Blindly submitting unreviewed, untested AI-generated code is strictly prohibited.
- Every function must be reviewed, tested with unit tests (
pnpm test), and fully understood by the submitter.
This project is licensed under the terms of the PolyForm Noncommercial License 1.0.0. See the LICENSE file for details.