Initial commit: Basic Nostr Magic Link middleware implementation

- Implemented NostrService for handling DM operations
- Added MagicLinkService for token management
- Created Express middleware for handling magic link requests
- Added comprehensive test suite with mocks
- Added documentation for testing Nostr services
- Basic security features implemented (token expiry, validation)
- TypeScript support with proper type definitions

Author: vveerrgg

.env.example

@@ -0,0 +1,40 @@
+# Server Configuration
+NODE_ENV=development
+PORT=3003  # Using 3003 since 3000 (relay), 3001 (IPFS), and 3002 (auth) are taken
+
+# CORS Configuration
+CORS_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:3002,http://localhost:3003
+
+# Nostr Configuration
+NOSTR_RELAYS=wss://relay.maiqr.app,wss://relay.damus.io,wss://relay.nostr.band
+NOSTR_PRIVATE_KEY=  # Bot's private key in hex format (64 chars)
+NOSTR_PUBLIC_KEY=   # Bot's public key in hex format (64 chars)
+
+# Magic Link Configuration
+MAGIC_LINK_BASE_URL=http://localhost:3003/auth
+MAGIC_LINK_EXPIRY=300000  # 5 minutes in milliseconds
+
+# JWT Configuration
+JWT_SECRET=your_jwt_secret_key
+JWT_EXPIRES_IN=24h
+
+# API Platform Integration
+API_PLATFORM_URL=http://localhost:8000
+API_PLATFORM_JWT_PUBLIC_KEY=
+
+# Logging
+LOG_LEVEL=info  # debug, info, warn, error
+LOG_DIR=logs    # Directory for log files
+
+# Test Configuration
+AUTH_HOST=http://localhost:3003  # Used by test scripts
+TEST_PUBKEY=  # Your test public key for running integration tests
+
+# Security Configuration
+API_KEYS=your_api_key_1,your_api_key_2  # Comma-separated list of valid API keys
+RATE_LIMIT_WINDOW_MS=900000  # 15 minutes in milliseconds
+RATE_LIMIT_MAX_REQUESTS=100  # Maximum requests per window
+TRUSTED_PROXIES=127.0.0.1,::1  # Comma-separated list of trusted proxy IPs
+
+# Development Mode (Optional)
+TEST_MODE=true  # Set to false in production

.github/FUNDING.yml

@@ -0,0 +1,16 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: [
+  'https://getalby.com/p/vveerrgg',  # Lightning address
+  'https://blockchair.com/bitcoin/address/bc1qw6kasfudkd64sts2q5a0lpm8zgea9txjc4gxj7',  # Bitcoin address
+  'https://blockchair.com/litecoin/address/ltc1qhvt82z3308nr2gmpfuhldmu9cw3d943n7lf2we'  # Litecoin address
+] # Up to 4 custom sponsorship URLs

.gitignore

@@ -0,0 +1,50 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build output
+dist/
+build/
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE and editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Test coverage
+coverage/
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity

.keys/jwt_secret

@@ -0,0 +1,2 @@
+cc311501dc56dd5212ead538f5b36ab7cafe951608a91b8a46c0b8ac11ad
+87d2

.keys/nostr_private_key

@@ -0,0 +1,2 @@
+c75ddaf00f239f0676a6b890a8f5c3e87ff5ef23ccbc9513f48b9e6c068a
+46ca

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to nostr-dm-magiclink-middleware
+
+We love your input! We want to make contributing to nostr-dm-magiclink-middleware as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## We Develop with Github
+We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html)
+Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## Any contributions you make will be under the MIT Software License
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using Github's [issue tracker](https://github.com/HumanjavaEnterprises/nostr-dm.magiclink-middleware/issues)
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/HumanjavaEnterprises/nostr-dm.magiclink-middleware/issues/new); it's that easy!
+
+## Write bug reports with detail, background, and sample code
+
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can.
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+## License
+By contributing, you agree that your contributions will be licensed under its MIT License.
+
+## References
+This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HumanjavaEnterprises
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,111 @@
+# Nostr DM Magic Link Middleware
+
+[![License](https://img.shields.io/npm/l/nostr-dm-magiclink-middleware)](https://github.com/HumanjavaEnterprises/nostr-dm.magiclink-middleware/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/nostr-dm-magiclink-middleware)](https://www.npmjs.com/package/nostr-dm-magiclink-middleware)
+[![GitHub issues](https://img.shields.io/github/issues/HumanjavaEnterprises/nostr-dm.magiclink-middleware)](https://github.com/HumanjavaEnterprises/nostr-dm.magiclink-middleware/issues)
+[![GitHub stars](https://img.shields.io/github/stars/HumanjavaEnterprises/nostr-dm.magiclink-middleware)](https://github.com/HumanjavaEnterprises/nostr-dm.magiclink-middleware/stargazers)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![Node Version](https://img.shields.io/node/v/nostr-dm-magiclink-middleware)](https://nodejs.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
+
+A middleware for handling magic link authentication via Nostr DMs. This package provides a secure way to implement passwordless authentication using Nostr's direct messaging system.
+
+## Features
+
+- 🔐 Secure magic link generation and verification
+- 📨 Delivery via encrypted Nostr DMs
+- 🔑 Built-in session management
+- 🚀 Easy integration with Express.js
+- 📦 TypeScript support
+- ⚡ Async/await API
+
+## Installation
+
+```bash
+npm install nostr-dm-magiclink-middleware
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { createNostrMagicLink } from 'nostr-dm-magiclink-middleware';
+
+const app = express();
+app.use(express.json());
+
+// Initialize the middleware
+const magicLink = createNostrMagicLink({
+  privateKey: process.env.NOSTR_PRIVATE_KEY!, // Your bot's private key
+  baseUrl: 'https://your-app.com/auth',       // Your auth endpoint base URL
+  relayUrl: 'wss://relay.damus.io',           // Optional: custom relay URL
+  tokenExpiry: 5 * 60 * 1000                  // Optional: token expiry in ms (default: 5 minutes)
+});
+
+// Endpoint to initiate login
+app.post('/auth/login', magicLink.initiate);
+
+// Endpoint to verify magic link
+app.get('/auth/verify', magicLink.verify, (req, res) => {
+  // User is now verified
+  const { npub, sessionId } = req.nostr;
+  
+  // Create user session, JWT, etc.
+  res.json({
+    success: true,
+    message: 'Authentication successful',
+    npub
+  });
+});
+
+// Cleanup when shutting down
+process.on('SIGTERM', async () => {
+  await magicLink.cleanup();
+});
+```
+
+## How It Works
+
+1. User requests login with their Nostr public key (npub)
+2. Middleware generates a secure magic link
+3. Link is sent via encrypted Nostr DM to the user
+4. User clicks the link in their Nostr client
+5. Middleware verifies the link and authenticates the user
+
+## Security Features
+
+- ✅ Encrypted DMs using NIP-04
+- ✅ One-time use tokens
+- ✅ Configurable token expiry
+- ✅ Session-based verification
+- ✅ Automatic cleanup of expired sessions
+
+## Advanced Usage
+
+You can also use the services directly for more custom implementations:
+
+```typescript
+import { NostrService, MagicLinkService } from 'nostr-dm-magiclink-middleware';
+
+// Use NostrService directly for DM functionality
+const nostr = new NostrService(privateKey, relayUrl);
+
+// Use MagicLinkService for custom magic link handling
+const magicLink = new MagicLinkService(privateKey, baseUrl, relayUrl);
+```
+
+## Documentation
+
+For detailed documentation, check out:
+
+- [Testing Nostr Services](docs/testing-nostr-services.md) - Learn about testing strategies, common challenges, and best practices for testing Nostr services
+- [API Reference](docs/api-reference.md) - Detailed API documentation
+- [Security Guide](docs/security-guide.md) - Security best practices and considerations
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details