nostr-bray 1.42.3 → 2.1.0

package/dist/cli/commands/social.js

@@ -1,4 +1,4 @@
-import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialDelete, handleSocialRepost, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsFollow, handleContactsUnfollow, handleDmSend, handleDmRead, handleNotifications, handleFeed, handleNipPublish, handleNipRead, handleBlossomUpload, handleBlossomList, handleBlossomDelete, handleGroupInfo, handleGroupChat, handleGroupSend, handleGroupMembers, handleGroupCreate, handleGroupUpdate, handleGroupAddUser, handleGroupRemoveUser, handleGroupAdmins, handleGroupRoles, handleGroupInspect, handleGroupCreateInvite, handleGroupJoin, handleGroupLeave, handleGroupDeleteEvent, handleGroupDelete, handleGroupForumTopics, handleGroupForumTopicCreate, handleGroupForumComments, handleGroupForumComment, } from '../../exports.js';
+import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialDelete, handleSocialRepost, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsFollow, handleContactsUnfollow, handleDmSend, handleDmRead, handleNotifications, handleFeed, handleNipPublish, handleNipRead, handleBlossomUpload, handleBlossomList, handleBlossomDelete, handleBlossomDownload, handleBlossomCheck, handleBlossomDiscover, handleBlossomVerify, handleBlossomRepair, handleBlossomUsage, handleBlossomMirror, handleBlossomServersGet, handleBlossomServersSet, handleGroupInfo, handleGroupChat, handleGroupSend, handleGroupMembers, handleGroupCreate, handleGroupUpdate, handleGroupAddUser, handleGroupRemoveUser, handleGroupAdmins, handleGroupRoles, handleGroupInspect, handleGroupCreateInvite, handleGroupJoin, handleGroupLeave, handleGroupDeleteEvent, handleGroupDelete, handleGroupForumTopics, handleGroupForumTopicCreate, handleGroupForumComments, handleGroupForumComment, } from '../../exports.js';
 import * as fmt from '../../format.js';
 export async function dispatch(cmd, cmdArgs, h, ctx, pool, config) {
     const { req, flag, flags, hasFlag, out } = h;
@@ -121,6 +121,67 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool, config) {
                 sha256: req(2, 'blossom-delete <server> <sha256>'),
             }));
             break;
+        case 'blossom-download': {
+            const { writeFileSync } = await import('node:fs');
+            const result = await handleBlossomDownload({
+                server: req(1, 'blossom-download <server> <sha256> [out-file]'),
+                sha256: req(2, 'blossom-download <server> <sha256> [out-file]'),
+            });
+            const dest = cmdArgs[3];
+            if (dest) {
+                writeFileSync(dest, result.data);
+                out({ sha256: cmdArgs[2], bytes: result.data.length, contentType: result.contentType, path: dest });
+            }
+            else {
+                // No destination: stream the blob to stdout so it can be piped
+                process.stdout.write(result.data);
+            }
+            break;
+        }
+        case 'blossom-check':
+            out(await handleBlossomCheck({
+                server: req(1, 'blossom-check <server> <sha256> [--verify]'),
+                sha256: req(2, 'blossom-check <server> <sha256> [--verify]'),
+                verify: hasFlag('verify'),
+            }));
+            break;
+        case 'blossom-discover':
+            out(await handleBlossomDiscover(pool, ctx.activeNpub, {
+                pubkeys: flags('pubkey').length ? flags('pubkey') : undefined,
+            }));
+            break;
+        case 'blossom-verify':
+            out(await handleBlossomVerify({
+                content: req(1, 'blossom-verify <content> [--verify-hash]'),
+                verifyHash: hasFlag('verify-hash'),
+            }));
+            break;
+        case 'blossom-repair':
+            out(await handleBlossomRepair(ctx, {
+                sha256: req(1, 'blossom-repair <sha256> --search <url> [--search <url>...] [--target <url>]'),
+                searchServers: flags('search'),
+                targetServer: flag('target'),
+            }));
+            break;
+        case 'blossom-usage':
+            out(await handleBlossomUsage({
+                servers: flags('server'),
+                pubkeyHex: req(1, 'blossom-usage <pubkey-hex> --server <url> [--server <url>...]'),
+            }));
+            break;
+        case 'blossom-mirror':
+            out(await handleBlossomMirror(ctx, {
+                servers: flags('server'),
+                sourceUrl: flag('source'),
+                filePath: flag('file'),
+            }));
+            break;
+        case 'blossom-servers':
+            out(await handleBlossomServersGet(pool, ctx.activeNpub, req(1, 'blossom-servers <pubkey-hex>')));
+            break;
+        case 'blossom-servers-set':
+            out(await handleBlossomServersSet(ctx, pool, { servers: flags('server') }));
+            break;
         case 'group-info':
             out(await handleGroupInfo(pool, ctx.activeNpub, {
                 relay: req(1, 'group-info <relay-url> <group-id>'),

package/dist/cli/commands/util.js

@@ -1,4 +1,4 @@
-import { handleDecode, handleEncodeNpub, handleEncodeNote, handleEncodeNprofile, handleEncodeNevent, handleVerify, handleEncrypt, handleDecrypt, handleCount, handleFetch, handleKeyPublic, handleEncodeNsec, handleFilter, handleNipList, handleNipShow, handleKeyEncrypt, handleKeyDecrypt, handleValidateEvent, lookupKind, searchKinds, } from '../../exports.js';
+import { handleDecode, handleEncodeNpub, handleEncodeNote, handleEncodeNprofile, handleEncodeNevent, handleVerify, handleEncrypt, handleDecrypt, handleCount, handleFetch, handleKeyPublic, handleEncodeNsec, handleFilter, handleNipList, handleNipShow, handleKeyEncrypt, handleKeyDecrypt, handleValidateEvent, lookupKind, searchKinds, handleGiftWrap, handleGiftUnwrap, } from '../../exports.js';
 import { validateInputPath } from '../../validation.js';
 import * as fmt from '../../format.js';
 export async function dispatch(cmd, cmdArgs, h, ctx, pool) {
@@ -63,6 +63,19 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool) {
             out(handleValidateEvent(JSON.parse(raw), mode));
             break;
         }
+        case 'gift-wrap': {
+            const recipient = req(1, 'gift-wrap <recipient-pubkey-hex> <event-json|-> [--file path]');
+            out(await handleGiftWrap(ctx, {
+                event: JSON.parse(await readJsonArg(cmdArgs[2], flag('file'))),
+                recipientPubkey: recipient,
+            }));
+            break;
+        }
+        case 'gift-unwrap':
+            out(await handleGiftUnwrap(ctx, {
+                event: JSON.parse(await readJsonArg(cmdArgs[1], flag('file'))),
+            }));
+            break;
         case 'kind': {
             const arg = req(1, 'kind <number|search text>');
             if (/^\d+$/.test(arg)) {
@@ -107,3 +120,15 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool) {
             throw new Error(`Unknown command: ${cmd}. Run --help for usage.`);
     }
 }
+/**
+ * Read a JSON argument from, in order: an explicit --file, a positional
+ * argument, or stdin. `-` selects stdin explicitly, matching common CLI usage.
+ */
+async function readJsonArg(positional, filePath) {
+    const { readFileSync } = await import('node:fs');
+    if (filePath)
+        return readFileSync(validateInputPath(filePath), 'utf8');
+    if (positional && positional !== '-' && !positional.startsWith('--'))
+        return positional;
+    return readFileSync(0, 'utf8');
+}

package/dist/cli/dispatch.js

@@ -27,6 +27,8 @@ export const COMPOUND_COMMANDS = new Set([
     'trust-read', 'trust-verify', 'trust-revoke', 'trust-request', 'trust-rank',
     'nip-publish', 'nip-read',
     'relay-set', 'relay-add', 'relay-curl',
+    // blossom two-word forms
+    'blossom-servers-set',
     'outbox-relays', 'outbox-publish',
     'ring-prove', 'ring-verify',
     'musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate',
@@ -44,7 +46,7 @@ export const OFFLINE_COMMANDS = new Set([
     'ring-verify', 'zap-decode', 'safety-configure', 'safety-activate',
     'decode', 'encode-npub', 'encode-note', 'encode-nprofile', 'encode-nevent', 'encode-nsec',
     'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'verify', 'encrypt', 'decrypt',
-    'validate-event', 'kind',
+    'validate-event', 'kind', 'gift-wrap', 'gift-unwrap',
     'musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate',
     // wallet config subcommands don't touch the relay
     'wallet-connect', 'wallet-disconnect', 'wallet-status',

package/dist/cli/index.js

@@ -56,7 +56,12 @@ if (command === 'serve' && !args.includes('--help')) {
     const hostname = args.includes('--hostname') ? args[args.indexOf('--hostname') + 1] : 'localhost';
     const port = args.includes('--port') ? parseInt(args[args.indexOf('--port') + 1], 10) : 10547;
     const eventsFile = args.includes('--events') ? args[args.indexOf('--events') + 1] : undefined;
-    const relayServer = startRelay({ hostname, port, eventsFile, quiet: args.includes('--quiet') });
+    const relayServer = startRelay({
+        hostname, port, eventsFile,
+        quiet: args.includes('--quiet'),
+        auth: args.includes('--auth') || args.includes('--eager-auth'),
+        eagerAuth: args.includes('--eager-auth'),
+    });
     console.error(`nostr-bray test relay running at ${relayServer.url}`);
     console.error('Press Ctrl+C to stop');
     process.on('SIGINT', () => { relayServer.close(); process.exit(0); });
@@ -102,6 +107,15 @@ Social:
   blossom-upload <server> <file>      Upload file to blossom media server
   blossom-list <server> <pubkey>      List blobs on blossom server
   blossom-delete <server> <sha256>    Delete blob from blossom server
+  blossom-download <server> <sha256> [file]  Download a blob (stdout if no file)
+  blossom-check <server> <sha256> [--verify]  Check a blob exists
+  blossom-discover [--pubkey hex ...] Discover servers from kind 10063 lists
+  blossom-verify <content> [--verify-hash]    Check media URLs in content resolve
+  blossom-repair <sha256> --search <url>... [--target <url>]  Re-upload a lost blob
+  blossom-usage <pubkey-hex> --server <url>...  Storage used per server
+  blossom-mirror --server <url>... [--source <url>|--file <path>]  Copy a blob to servers
+  blossom-servers <pubkey-hex>        Read a kind 10063 server list
+  blossom-servers-set --server <url>...  Publish your kind 10063 server list
   group-info <relay> <group-id>       Fetch verified NIP-29 group metadata
   group-chat <relay> <group-id>       Fetch relay-scoped group chat
   group-send <relay> <group-id> "message"  Send a group message
@@ -206,6 +220,8 @@ Utility:
   nips                                List all official NIPs
   nip <number>                        Show a specific NIP
   kind <number|text>                  Look up an event kind: required tags, value shapes
+  gift-wrap <pubkey-hex> <event|-> [--file f]  Seal + wrap an event for a recipient (NIP-59)
+  gift-unwrap <event-json|-> [--file f]        Open a kind 1059 gift wrap addressed to you
   verify <event-json>                 Verify event hash and signature
   encrypt <pubkey-hex> "plaintext"    NIP-44 encrypt for a recipient
   decrypt <pubkey-hex> <ciphertext>   NIP-44 decrypt from a sender
@@ -220,7 +236,8 @@ MuSig2 (BIP-327 multi-signature):
 
 Modes:
   (no command)                        Start MCP server (stdio)
-  serve [--port N] [--events file]    Start in-memory test relay
+  serve [--port N] [--events file] [--auth] [--eager-auth]  Start in-memory test relay
+                                      (--auth requires NIP-42; --eager-auth also challenges on connect)
   bunker connect <bunker://…>              Save remote bunker URI for future commands
   bunker authorize <hex-pubkey>           Pre-authorise an app pubkey on the local bunker
   bunker status                           Show saved bunker connection state
@@ -382,6 +399,7 @@ const SOCIAL_CMDS = new Set([
     'contacts', 'follow', 'unfollow', 'dm', 'dm-read', 'feed', 'notifications',
     'nip-publish', 'nip-read',
     'blossom-upload', 'blossom-list', 'blossom-delete',
+    'blossom-download', 'blossom-check', 'blossom-discover', 'blossom-verify', 'blossom-repair', 'blossom-usage', 'blossom-mirror', 'blossom-servers', 'blossom-servers-set',
     'group-info', 'group-chat', 'group-send', 'group-members',
     'group-admins', 'group-roles', 'group-inspect',
     'group-create', 'group-update', 'group-add-user', 'group-remove-user',
@@ -398,7 +416,7 @@ const SAFETY_CMDS = new Set(['safety-configure', 'safety-activate']);
 const EVENT_CMDS = new Set(['event', 'publish-raw']);
 const UTIL_CMDS = new Set([
     'decode', 'encode-npub', 'encode-note', 'encode-nprofile', 'encode-nevent', 'encode-nsec',
-    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', 'encrypt', 'decrypt', 'count', 'fetch',
+    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', 'gift-wrap', 'gift-unwrap', 'encrypt', 'decrypt', 'count', 'fetch',
 ]);
 const MUSIG2_CMDS = new Set(['musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate']);
 const SYNC_CMDS = new Set(['sync-plan', 'sync-pull', 'sync-push']);
@@ -455,6 +473,7 @@ const ALL_COMMANDS = [
     'zap-send', 'zap-balance', 'zap-invoice', 'zap-lookup', 'zap-transactions', 'zap-receipts', 'zap-decode',
     'safety-configure', 'safety-activate',
     'blossom-upload', 'blossom-list', 'blossom-delete',
+    'blossom-download', 'blossom-check', 'blossom-discover', 'blossom-verify', 'blossom-repair', 'blossom-usage', 'blossom-mirror', 'blossom-servers', 'blossom-servers-set',
     'group-info', 'group-chat', 'group-send', 'group-members',
     'group-admins', 'group-roles', 'group-inspect',
     'group-create', 'group-update', 'group-add-user', 'group-remove-user',
@@ -462,7 +481,7 @@ const ALL_COMMANDS = [
     'group-forum-topics', 'group-forum-topic-create', 'group-forum-comments', 'group-forum-comment',
     'event', 'publish-raw',
     'decode', 'encode-npub', 'encode-note', 'encode-nprofile', 'encode-nevent', 'encode-nsec',
-    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', 'encrypt', 'decrypt', 'count', 'fetch',
+    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', 'gift-wrap', 'gift-unwrap', 'encrypt', 'decrypt', 'count', 'fetch',
     'musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate',
     'sync-plan', 'sync-pull', 'sync-push',
     ...ADMIN_COMMANDS,

package/dist/event/gift-wrap.d.ts

@@ -0,0 +1,72 @@
+/**
+ * NIP-59 gift wrap for arbitrary events.
+ *
+ * `src/nip17-wrap.ts` wraps DMs specifically: it builds a kind 14 rumor from a
+ * message string. This is the general form — seal and wrap any event you like,
+ * which is what `nak gift wrap` does and what NIP-59 actually describes.
+ *
+ * Three layers:
+ *   rumor  — an unsigned event, signed by nobody, identified only by its hash
+ *   seal   — kind 13, the rumor NIP-44 encrypted to the recipient, signed by you
+ *   wrap   — kind 1059, the seal NIP-44 encrypted under a throwaway key
+ *
+ * Only the wrap is public, and it is signed by an ephemeral key, so nothing
+ * on the wire links back to the sender.
+ *
+ * All crypto goes through the SigningContext rather than a raw private key, so
+ * this works unchanged under NIP-46 where the key lives in a remote bunker.
+ */
+import type { Event as NostrEvent } from 'nostr-tools';
+import type { SigningContext } from '../signing-context.js';
+/** An event to be wrapped. Anything already signed has its signature dropped: a rumor is unsigned by definition. */
+export interface RumorInput {
+    kind: number;
+    content?: string;
+    tags?: string[][];
+    created_at?: number;
+}
+export interface GiftWrapResult {
+    /** The kind 1059 wrap, ready to publish. */
+    wrap: NostrEvent;
+    /** The rumor's id, which the recipient will see after unwrapping. */
+    rumorId: string;
+    recipient: string;
+}
+/**
+ * Seal and wrap an event for one recipient.
+ *
+ * @throws if the recipient pubkey is not 64-char hex.
+ */
+export declare function handleGiftWrap(ctx: SigningContext, args: {
+    event: RumorInput;
+    recipientPubkey: string;
+}): Promise<GiftWrapResult>;
+export interface GiftUnwrapResult {
+    /** The rumor that was hidden inside. */
+    rumor: {
+        id?: string;
+        pubkey: string;
+        kind: number;
+        content: string;
+        tags: string[][];
+        created_at: number;
+    };
+    /** Pubkey that signed the seal — the real sender. */
+    sender: string;
+    /**
+     * Whether the seal's signer matches the rumor's claimed author.
+     *
+     * A mismatch means someone sealed an event attributed to a third party.
+     * NIP-59 requires the recipient to check this; a rumor is unsigned, so its
+     * `pubkey` field is a claim, not proof.
+     */
+    senderMatchesRumor: boolean;
+}
+/**
+ * Unwrap a kind 1059 gift wrap back to its rumor.
+ *
+ * @throws if the event is not a gift wrap, or either layer fails to decrypt.
+ */
+export declare function handleGiftUnwrap(ctx: SigningContext, args: {
+    event: NostrEvent;
+}): Promise<GiftUnwrapResult>;

package/dist/event/gift-wrap.js

@@ -0,0 +1,104 @@
+/**
+ * NIP-59 gift wrap for arbitrary events.
+ *
+ * `src/nip17-wrap.ts` wraps DMs specifically: it builds a kind 14 rumor from a
+ * message string. This is the general form — seal and wrap any event you like,
+ * which is what `nak gift wrap` does and what NIP-59 actually describes.
+ *
+ * Three layers:
+ *   rumor  — an unsigned event, signed by nobody, identified only by its hash
+ *   seal   — kind 13, the rumor NIP-44 encrypted to the recipient, signed by you
+ *   wrap   — kind 1059, the seal NIP-44 encrypted under a throwaway key
+ *
+ * Only the wrap is public, and it is signed by an ephemeral key, so nothing
+ * on the wire links back to the sender.
+ *
+ * All crypto goes through the SigningContext rather than a raw private key, so
+ * this works unchanged under NIP-46 where the key lives in a remote bunker.
+ */
+import { finalizeEvent, generateSecretKey, getEventHash } from 'nostr-tools/pure';
+/** Timestamps are randomised up to two days back, per NIP-59, to frustrate correlation. */
+const TWO_DAYS = 2 * 24 * 60 * 60;
+const randomNow = () => Math.round(Date.now() / 1000 - Math.random() * TWO_DAYS);
+const HEX64 = /^[0-9a-f]{64}$/i;
+/**
+ * Seal and wrap an event for one recipient.
+ *
+ * @throws if the recipient pubkey is not 64-char hex.
+ */
+export async function handleGiftWrap(ctx, args) {
+    const recipient = args.recipientPubkey.toLowerCase();
+    if (!HEX64.test(recipient)) {
+        throw new Error('recipientPubkey must be a 64-character hex public key');
+    }
+    // A rumor carries an id but no signature — that is what makes it deniable.
+    const rumor = {
+        pubkey: ctx.activePublicKeyHex,
+        created_at: args.event.created_at ?? Math.floor(Date.now() / 1000),
+        kind: args.event.kind,
+        tags: args.event.tags ?? [],
+        content: args.event.content ?? '',
+    };
+    const rumorId = getEventHash(rumor);
+    const rumorWithId = { ...rumor, id: rumorId };
+    // Seal: rumor encrypted to the recipient, signed by us
+    const sealContent = await ctx.nip44Encrypt(recipient, JSON.stringify(rumorWithId));
+    const sign = ctx.getSigningFunction();
+    const seal = await sign({
+        kind: 13,
+        content: sealContent,
+        created_at: randomNow(),
+        tags: [],
+    });
+    // Wrap: seal encrypted under a throwaway key, so the wrap is unattributable
+    const ephemeralSk = generateSecretKey();
+    try {
+        const { getConversationKey, encrypt } = await import('nostr-tools/nip44');
+        const ck = getConversationKey(ephemeralSk, recipient);
+        const wrap = finalizeEvent({
+            kind: 1059,
+            content: encrypt(JSON.stringify(seal), ck),
+            created_at: randomNow(),
+            tags: [['p', recipient]],
+        }, ephemeralSk);
+        return { wrap, rumorId, recipient };
+    }
+    finally {
+        ephemeralSk.fill(0);
+    }
+}
+/**
+ * Unwrap a kind 1059 gift wrap back to its rumor.
+ *
+ * @throws if the event is not a gift wrap, or either layer fails to decrypt.
+ */
+export async function handleGiftUnwrap(ctx, args) {
+    const wrap = args.event;
+    if (wrap?.kind !== 1059) {
+        throw new Error(`Expected a kind 1059 gift wrap, got kind ${wrap?.kind}`);
+    }
+    // Outer layer: decrypt against the ephemeral pubkey that signed the wrap
+    let seal;
+    try {
+        seal = JSON.parse(await ctx.nip44Decrypt(wrap.pubkey, wrap.content));
+    }
+    catch (e) {
+        throw new Error(`Could not decrypt the gift wrap — it may not be addressed to this identity: ${e.message}`);
+    }
+    if (seal?.kind !== 13) {
+        throw new Error(`Expected a kind 13 seal inside the wrap, got kind ${seal?.kind}`);
+    }
+    // Inner layer: decrypt against the seal's signer, which is the real sender
+    let rumor;
+    try {
+        rumor = JSON.parse(await ctx.nip44Decrypt(seal.pubkey, seal.content));
+    }
+    catch (e) {
+        throw new Error(`Could not decrypt the seal: ${e.message}`);
+    }
+    return {
+        rumor,
+        sender: seal.pubkey,
+        senderMatchesRumor: rumor.pubkey === seal.pubkey,
+    };
+}

package/dist/event/index.d.ts

@@ -1,3 +1,4 @@
 export * from './handlers.js';
 export * from '../event-validation/index.js';
 export * from './pow.js';
+export * from './gift-wrap.js';

package/dist/event/index.js

@@ -1,3 +1,4 @@
 export * from './handlers.js';
 export * from '../event-validation/index.js';
 export * from './pow.js';
+export * from './gift-wrap.js';

package/dist/serve.d.ts

@@ -9,6 +9,16 @@ export interface ServeOptions {
     port?: number;
     eventsFile?: string;
     quiet?: boolean;
+    /**
+     * Require NIP-42 AUTH before serving EVENT or REQ.
+     *
+     * Exists so clients can be tested against an auth-gated relay without
+     * needing a real one — bray's own NIP-42 support is otherwise only
+     * exercisable against third-party infrastructure.
+     */
+    auth?: boolean;
+    /** Send the AUTH challenge on connect rather than waiting for a rejection. */
+    eagerAuth?: boolean;
 }
 export declare function startRelay(opts?: ServeOptions): {
     url: string;

package/dist/serve.js

@@ -7,6 +7,7 @@
 import { WebSocketServer, WebSocket } from 'ws';
 import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { verifyEvent } from 'nostr-tools/pure';
 let subCounter = 0;
 /** Check if an event matches a single filter */
@@ -39,10 +40,36 @@ function matchFilter(filter, event) {
 function matchFilters(filters, event) {
     return filters.some(f => matchFilter(f, event));
 }
+/**
+ * Check a NIP-42 auth event against the challenge this connection issued.
+ *
+ * Returns a reason string when it should be rejected, or undefined when it is
+ * good. Beyond the signature this checks kind, freshness and that the
+ * `challenge` tag matches — without the last one an auth event captured from
+ * another connection would be replayable here.
+ */
+function checkAuthEvent(event, challenge) {
+    if (!event?.id || !event?.sig || !event?.pubkey)
+        return 'malformed auth event';
+    if (event.kind !== 22242)
+        return `expected kind 22242, got ${event.kind}`;
+    if (!verifyEvent(event))
+        return 'invalid signature';
+    const sent = event.tags?.find(t => t[0] === 'challenge')?.[1];
+    if (sent !== challenge)
+        return 'challenge mismatch';
+    // NIP-42 suggests rejecting anything far from the present
+    const age = Math.abs(Math.floor(Date.now() / 1000) - event.created_at);
+    if (age > 600)
+        return 'auth event timestamp too far from now';
+    return undefined;
+}
 export function startRelay(opts = {}) {
     const hostname = opts.hostname ?? 'localhost';
     const port = opts.port ?? 10547;
     const quiet = opts.quiet ?? false;
+    const requireAuth = opts.auth ?? false;
+    const eagerAuth = opts.eagerAuth ?? false;
     const log = quiet ? () => { } : (...args) => console.error('[relay]', ...args);
     // The bundled test relay has no auth and accepts arbitrary signed events.
     // Binding it to anything other than loopback exposes a writable Nostr endpoint
@@ -86,7 +113,14 @@ export function startRelay(opts = {}) {
     const wss = new WebSocketServer({ server: httpServer });
     wss.on('connection', (ws) => {
         const clientSubs = new Set();
+        // NIP-42: one challenge per connection; authedPubkey is set once the
+        // client returns a valid kind 22242 naming this relay and that challenge.
+        const challenge = randomBytes(16).toString('hex');
+        let authedPubkey;
         log('Client connected');
+        if (requireAuth && eagerAuth) {
+            ws.send(JSON.stringify(['AUTH', challenge]));
+        }
         ws.on('message', (raw) => {
             let msg;
             try {
@@ -101,6 +135,31 @@ export function startRelay(opts = {}) {
                 return;
             }
             const type = msg[0];
+            if (type === 'AUTH') {
+                const authEvent = msg[1];
+                const problem = checkAuthEvent(authEvent, challenge);
+                if (problem) {
+                    ws.send(JSON.stringify(['OK', authEvent?.id ?? '', false, `auth-required: ${problem}`]));
+                    return;
+                }
+                authedPubkey = authEvent.pubkey;
+                log('Client authenticated as', authedPubkey);
+                ws.send(JSON.stringify(['OK', authEvent.id, true, '']));
+                return;
+            }
+            if (requireAuth && !authedPubkey && (type === 'EVENT' || type === 'REQ')) {
+                // Send the challenge alongside the rejection so a client that did not
+                // ask for one up front can still recover without reconnecting.
+                ws.send(JSON.stringify(['AUTH', challenge]));
+                if (type === 'EVENT') {
+                    const e = msg[1];
+                    ws.send(JSON.stringify(['OK', e?.id ?? '', false, 'auth-required: authentication required']));
+                }
+                else {
+                    ws.send(JSON.stringify(['CLOSED', String(msg[1]), 'auth-required: authentication required']));
+                }
+                return;
+            }
             if (type === 'EVENT') {
                 const event = msg[1];
                 if (!event?.id || !event?.sig || !event?.pubkey) {

package/dist/util/tools.js

@@ -7,6 +7,7 @@ import { handleDecode, handleEncodeNpub, handleEncodeNote, handleEncodeNprofile,
 import { handleValidateEvent } from '../event-validation/validator.js';
 import { eventValidationModeSchema, semanticEventInputSchema } from '../event-validation/tools-schema.js';
 import { lookupKind, searchKinds } from '../event-validation/kind-lookup.js';
+import { handleGiftWrap, handleGiftUnwrap } from '../event/gift-wrap.js';
 export function registerUtilTools(server, deps) {
     server.registerTool('decode', {
         description: 'Decode a nip19 entity (npub, nsec, note, nevent, nprofile, naddr) or nostr: URI to its components.',
@@ -87,6 +88,35 @@ export function registerUtilTools(server, deps) {
         const result = handleValidateEvent(event, mode);
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     });
+    server.registerTool('gift-wrap', {
+        description: 'Seal and gift-wrap any event for one recipient (NIP-59). Returns a kind 1059 wrap signed by a throwaway key, ' +
+            'so nothing public links it to you. Use for metadata-private delivery of arbitrary events; DMs already wrap themselves via dm-send.',
+        inputSchema: {
+            event: z.object({
+                kind: z.number().int().min(0).describe('Kind of the event to wrap'),
+                content: z.string().optional().describe('Event content'),
+                tags: z.array(z.array(z.string())).optional().describe('Event tags'),
+                created_at: z.number().int().optional().describe('Unix timestamp (defaults to now)'),
+            }).describe('The event to wrap. It is sealed unsigned, as NIP-59 requires.'),
+            recipient_pubkey: hexId.describe('Recipient hex public key'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ event, recipient_pubkey }) => {
+        const result = await handleGiftWrap(deps.ctx, { event, recipientPubkey: recipient_pubkey });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('gift-unwrap', {
+        description: 'Unwrap a NIP-59 kind 1059 gift wrap addressed to the active identity, returning the hidden rumor and the ' +
+            'pubkey that sealed it. Also reports whether the sealer matches the rumor\'s claimed author — a rumor is ' +
+            'unsigned, so its pubkey is a claim rather than proof, and a mismatch means someone sealed an event attributed to a third party.',
+        inputSchema: {
+            event: nostrEventSchema.describe('The kind 1059 gift wrap to open'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ event }) => {
+        const result = await handleGiftUnwrap(deps.ctx, { event: event });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
     server.registerTool('kind-info', {
         description: 'Look up what a Nostr event kind is for and what shape it takes: description, storage class ' +
             '(regular/replaceable/ephemeral/addressable), required tags, repeatable tags, and the expected value type ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.42.3",
+  "version": "2.1.0",
   "mcpName": "dev.forgesworn/bray",
   "description": "Trust-aware Nostr for AI and humans. Three dimensions of trust -- verification, proximity, and access -- woven into every interaction.",
   "type": "module",
@@ -149,7 +149,7 @@
   "homepage": "https://github.com/forgesworn/bray#readme",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
   },
   "dependencies": {
     "@forgesworn/range-proof": "^2.0.1",
@@ -166,7 +166,7 @@
     "signet-protocol": "^1.1.0",
     "socks-proxy-agent": "^10.0.0",
     "spoken-token": "^2.0.3",
-    "undici": "^7.25.0",
+    "undici": "^8.9.0",
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },