nostr-dm-magiclink-utils
Version:
A comprehensive Nostr utility library for magic link authentication via direct messages, supporting both ESM and CommonJS. Features NIP-01/04 compliant message encryption, multi-relay support, internationalization (i18n) with RTL support, and TypeScript-f
289 lines (246 loc) • 8.91 kB
Markdown
[](https://www.npmjs.com/package/nostr-dm-magiclink-utils)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org)
[](https://codecov.io/gh/HumanjavaEnterprises/nostr-dm-magiclink-utils)
[](https://github.com/HumanjavaEnterprises/nostr-dm-magiclink-utils/actions)
[](https://libraries.io/npm/nostr-dm-magiclink-utils)
[](https://github.com/prettier/prettier)
[](https://github.com/vveerrgg)
[](https://bundlephobia.com/package/nostr-dm-magiclink-utils)
[](https://www.npmjs.com/package/nostr-dm-magiclink-utils)
[](https://github.com/HumanjavaEnterprises/nostr-dm-magiclink-utils#supported-languages)
[](https://github.com/nostr-protocol/nips/blob/master/04.md)
A comprehensive Nostr utility library for implementing secure, user-friendly authentication via magic links in direct messages. Built with TypeScript and following Nostr Improvement Proposals (NIPs) for maximum compatibility and security.
## Features
- 🔐 **NIP-04 Compliant**: Secure, encrypted direct messages following Nostr standards
- 🌍 **Rich i18n Support**: 9 languages with RTL support
- 🔄 **Multi-Relay Support**: Reliable message delivery with automatic failover
- 🛡️ **Type-Safe**: Full TypeScript support with comprehensive types
- 📝 **Flexible Templates**: Customizable messages with variable interpolation
- 🚀 **Modern API**: Promise-based, async/await friendly interface
- 🎯 **Zero Config**: Sensible defaults with optional deep customization
## Installation
```bash
npm install nostr-dm-magiclink-utils
```
## Quick Start
Here's a complete example showing how to set up and use the magic link service:
```typescript
import { createNostrMagicLink, NostrError } from 'nostr-dm-magiclink-utils';
import { generatePrivateKey } from 'nostr-tools'; // For demo purposes
async function setupAuthService() {
// Create manager with secure configuration
const magicLink = createNostrMagicLink({
nostr: {
// In production, load from secure environment variable
privateKey: process.env.NOSTR_PRIVATE_KEY || generatePrivateKey(),
relayUrls: [
'wss://relay.damus.io',
'wss://relay.nostr.band',
'wss://nos.lol'
],
// Optional: Configure connection timeouts
connectionTimeout: 5000
},
magicLink: {
verifyUrl: 'https://your-app.com/verify',
// Async token generation with expiry
token: async () => {
const token = await generateSecureToken({
expiresIn: '15m',
length: 32
});
return token;
},
defaultLocale: 'en',
// Optional: Custom message templates
templates: {
en: {
subject: 'Login to {{appName}}',
body: 'Click this secure link to log in: {{link}}\nValid for 15 minutes.'
}
}
}
});
return magicLink;
}
// Example usage in an Express route handler
app.post('/auth/magic-link', async (req, res) => {
try {
const { pubkey } = req.body;
if (!pubkey) {
return res.status(400).json({ error: 'Missing pubkey' });
}
const magicLink = await setupAuthService();
const result = await magicLink.sendMagicLink({
recipientPubkey: pubkey,
messageOptions: {
locale: req.locale, // From i18n middleware
variables: {
appName: 'YourApp',
username: req.body.username
}
}
});
if (result.success) {
res.json({
message: 'Magic link sent successfully',
expiresIn: '15 minutes'
});
}
} catch (error) {
if (error instanceof NostrError) {
// Handle specific Nostr-related errors
res.status(400).json({
error: error.message,
code: error.code
});
} else {
// Handle unexpected errors
res.status(500).json({
error: 'Failed to send magic link'
});
}
}
});
```
```typescript
try {
const result = await magicLink.sendMagicLink({
recipientPubkey: pubkey,
messageOptions: { locale: 'en' }
});
if (!result.success) {
switch (result.error.code) {
case 'RELAY_CONNECTION_FAILED':
// Attempt reconnection or use fallback relay
await magicLink.reconnect();
break;
case 'ENCRYPTION_FAILED':
// Log encryption errors for debugging
logger.error('Encryption failed:', result.error);
break;
case 'INVALID_PUBKEY':
// Handle invalid recipient public key
throw new UserError('Invalid recipient');
break;
}
}
} catch (error) {
// Handle other errors
}
```
```typescript
// Arabic (RTL) example
const result = await magicLink.sendMagicLink({
recipientPubkey: pubkey,
messageOptions: {
locale: 'ar',
// Optional: Override default template
template: {
subject: 'تسجيل الدخول إلى {{appName}}',
body: 'انقر فوق هذا الرابط الآمن لتسجيل الدخول: {{link}}'
},
variables: {
appName: 'تطبيقك',
username: 'المستخدم'
}
}
});
```
```typescript
const magicLink = createNostrMagicLink({
// ... other config
magicLink: {
verifyUrl: 'https://your-app.com/verify',
token: async (recipientPubkey: string) => {
// Generate a secure, short-lived token
const token = await generateJWT({
sub: recipientPubkey,
exp: Math.floor(Date.now() / 1000) + (15 * 60), // 15 minutes
jti: crypto.randomUUID(),
iss: 'your-app'
});
// Optional: Store token in database for verification
await db.tokens.create({
token,
pubkey: recipientPubkey,
expiresAt: new Date(Date.now() + 15 * 60 * 1000)
});
return token;
}
}
});
```
```typescript
const magicLink = createNostrMagicLink({
nostr: {
privateKey: process.env.NOSTR_PRIVATE_KEY,
relayUrls: ['wss://relay1.com', 'wss://relay2.com'],
// Advanced relay options
relayOptions: {
retryAttempts: 3,
retryDelay: 1000,
timeout: 5000,
onError: async (error, relay) => {
logger.error(`Relay ${relay} error:`, error);
// Optionally switch to backup relay
await magicLink.addRelay('wss://backup-relay.com');
}
}
}
});
// Monitor relay status
magicLink.on('relay:connected', (relay) => {
logger.info(`Connected to relay: ${relay}`);
});
magicLink.on('relay:disconnected', (relay) => {
logger.warn(`Disconnected from relay: ${relay}`);
});
```
1. **Private Key Management**
- Never hardcode private keys
- Use secure environment variables
- Rotate keys periodically
```typescript
// Load private key securely
const privateKey = await loadPrivateKeyFromSecureStore();
if (!privateKey) {
throw new Error('Missing required private key');
}
```
2. **Token Security**
- Use short expiration times (15-30 minutes)
- Include necessary claims (sub, exp, jti)
- Store tokens securely for verification
3. **Error Handling**
- Never expose internal errors to users
- Log errors securely
- Implement rate limiting
4. **Relay Security**
- Use trusted relays
- Implement connection timeouts
- Handle connection errors gracefully
## Supported Languages
The library includes built-in support for:
- 🇺🇸 English (en)
- 🇪🇸 Spanish (es)
- 🇫🇷 French (fr)
- 🇯🇵 Japanese (ja)
- 🇰🇷 Korean (ko)
- 🇨🇳 Chinese (zh)
- 🇧🇷 Portuguese (pt)
- 🇷🇺 Russian (ru)
- 🇸🇦 Arabic (ar) - with RTL support
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
## License
MIT © [vveerrgg](https://github.com/vveerrgg)