nostr-bray 2.0.0 → 2.2.0

package/dist/cli/commands/event.js

@@ -1,30 +1,28 @@
-import { assertEventSemanticallyValid, handlePublishEvent, handlePublishRaw } from '../../exports.js';
+import { assertEventSemanticallyValid, handlePublishEvent, handlePublishRaw, resolveKind } from '../../exports.js';
+import { nip19 } from 'nostr-tools';
 export async function dispatch(cmd, _cmdArgs, h, ctx, pool) {
-    const { flag, flags, hasFlag, out } = h;
+    const { flag, flags, hasFlag, flagAny, flagsAny, out } = h;
     switch (cmd) {
         case 'event': {
-            const kind = parseInt(flag('kind') ?? '', 10);
-            if (!kind || isNaN(kind))
-                throw new Error('Usage: event --kind <N> [--tag k=v] [--content s] [--relay url] [--no-publish]');
-            const tagValues = flags('tag').map(t => {
-                const eq = t.indexOf('=');
-                if (eq === -1)
-                    return [t];
-                return [t.slice(0, eq), t.slice(eq + 1)];
+            const kindArg = flagAny('kind', 'k');
+            if (!kindArg) {
+                throw new Error('Usage: event -k <number|name> [-c content] [-t k=v] [-p pubkey] [-e id] [-d ident] [--relay url]');
+            }
+            // Accepts a number or a registry kind name, e.g. -k "short text note"
+            const kind = resolveKind(kindArg);
+            const tagValues = collectTags(flagsAny('tag', 't'), {
+                p: flagsAny('p'), e: flagsAny('e'), d: flagsAny('d'), h: flagsAny('h'),
             });
-            const content = flag('content') ?? '';
+            const content = flagAny('content', 'c') ?? '';
             const validationMode = parseValidationMode(flag('validation'));
-            const relayOverrides = flags('relay');
+            const relayOverrides = flagsAny('relay', 'r');
             const pow = flag('pow') ? parseInt(flag('pow'), 10) : undefined;
             const powTimeoutMs = flag('pow-timeout') ? parseInt(flag('pow-timeout'), 10) : undefined;
+            const createdAtArg = flagAny('created-at', 'ts', 'time');
+            const createdAt = createdAtArg ? parseTimestamp(createdAtArg) : Math.floor(Date.now() / 1000);
             if (hasFlag('no-publish')) {
                 const { minePow } = await import('../../event/pow.js');
-                let template = {
-                    kind,
-                    created_at: Math.floor(Date.now() / 1000),
-                    tags: tagValues,
-                    content,
-                };
+                let template = { kind, created_at: createdAt, tags: tagValues, content };
                 if (pow !== undefined) {
                     template = minePow(template, { difficulty: pow, pubkey: ctx.activePublicKeyHex, timeoutMs: powTimeoutMs }).template;
                 }
@@ -32,18 +30,27 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool) {
                 reportWarnings(validation.issues);
                 const sign = ctx.getSigningFunction();
                 const event = await sign(template);
-                console.log(JSON.stringify(event, null, 2));
+                // --envelope emits the relay wire form, ready to paste into a socket
+                console.log(hasFlag('envelope')
+                    ? JSON.stringify(['EVENT', event])
+                    : JSON.stringify(event, null, 2));
+                if (hasFlag('nevent'))
+                    printNevent(event, relayOverrides);
                 break;
             }
-            out(await handlePublishEvent(ctx, pool, {
+            const result = await handlePublishEvent(ctx, pool, {
                 kind,
                 content,
                 tags: tagValues,
+                createdAt,
                 relays: relayOverrides.length ? relayOverrides : undefined,
                 validationMode,
                 pow,
                 powTimeoutMs,
-            }));
+            });
+            out(result);
+            if (hasFlag('nevent'))
+                printNevent(result.event, relayOverrides);
             break;
         }
         case 'publish-raw': {
@@ -102,3 +109,45 @@ function reportWarnings(issues) {
             console.error(`validation warning [${entry.code}]: ${entry.message}`);
     }
 }
+/**
+ * Merge `--tag k=v` entries with the single-letter shortcuts.
+ *
+ * Shortcuts come after the explicit tags so that `-t p=<x> -p <y>` yields both,
+ * in the order written, rather than one silently replacing the other.
+ */
+function collectTags(tagArgs, shortcuts) {
+    const tags = tagArgs.map(t => {
+        const eq = t.indexOf('=');
+        if (eq === -1)
+            return [t];
+        // A value may itself contain '=', so only split on the first one
+        return [t.slice(0, eq), t.slice(eq + 1)];
+    });
+    for (const [name, values] of Object.entries(shortcuts)) {
+        for (const v of values)
+            tags.push([name, v]);
+    }
+    return tags;
+}
+/** Parse a created_at: a unix timestamp, an ISO date, or `now`. */
+function parseTimestamp(value) {
+    if (value === 'now')
+        return Math.floor(Date.now() / 1000);
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Could not read "${value}" as a timestamp. Use a unix time, an ISO date, or "now".`);
+    }
+    return Math.floor(parsed / 1000);
+}
+/** Print the nevent code to stderr, so stdout stays parseable. */
+function printNevent(event, relays) {
+    const code = nip19.neventEncode({
+        id: event.id,
+        author: event.pubkey,
+        kind: event.kind,
+        ...(relays.length ? { relays } : {}),
+    });
+    console.error(code);
+}

package/dist/cli/commands/relay.js

@@ -29,12 +29,20 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool, _activeNpub) {
             out(await handleRelayInfo(req(1, 'relay-info <wss://url>')));
             break;
         case 'req': {
-            // Support JSON filter on stdin when stdin is a pipe
+            // Support a JSON filter on stdin when stdin is a pipe. Not being a TTY
+            // does not guarantee stdin is readable — under a test runner, or a
+            // service manager that hands over a closed descriptor, the read throws
+            // EAGAIN and there is no filter to find anyway.
             let stdinFilter;
-            const isTTY = process.stdin.isTTY;
-            if (!isTTY) {
+            if (!process.stdin.isTTY) {
                 const { readFileSync } = await import('node:fs');
-                const raw = readFileSync(0, 'utf-8').trim();
+                let raw = '';
+                try {
+                    raw = readFileSync(0, 'utf-8').trim();
+                }
+                catch {
+                    raw = '';
+                }
                 if (raw)
                     stdinFilter = JSON.parse(raw);
             }
@@ -60,6 +68,59 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool, _activeNpub) {
             const paginate = hasFlag('paginate');
             const paginateIntervalMs = flag('paginate-interval') ? parseInt(flag('paginate-interval'), 10) : undefined;
             const maxPages = flag('max-pages') ? parseInt(flag('max-pages'), 10) : undefined;
+            // NIP-77 paths run before the normal REQ: both reconcile IDs with one
+            // relay rather than transferring events, which is the whole point.
+            if (hasFlag('ids-only') || hasFlag('only-missing')) {
+                const target = relayOverrides[0] ?? pool.getRelays(ctx.activeNpub).read[0];
+                if (!target)
+                    throw new Error('--ids-only and --only-missing need a relay: pass --relay <url>');
+                const negFilter = {
+                    ...(kindsRaw ? { kinds: kindsRaw.split(',').map(Number) } : {}),
+                    ...(authorsRaw ? { authors: authorsRaw.split(',') } : {}),
+                    ...(since !== undefined ? { since } : {}),
+                    ...(until !== undefined ? { until } : {}),
+                };
+                // Reconcile against what we already hold: nothing for --ids-only, the
+                // supplied jsonl for --only-missing.
+                let local = [];
+                if (hasFlag('only-missing')) {
+                    const { readFileSync } = await import('node:fs');
+                    const { validateInputPath } = await import('../../validation.js');
+                    const path = flag('only-missing');
+                    if (!path)
+                        throw new Error('Usage: req --only-missing <events.jsonl> [--relay url]');
+                    local = readFileSync(validateInputPath(path), 'utf8')
+                        .split('\n')
+                        .filter(l => l.trim())
+                        .map(l => {
+                        const e = JSON.parse(l);
+                        return { id: e.id, createdAt: e.created_at };
+                    });
+                }
+                const recon = await pool.reconcileDirect(target, local, negFilter, {
+                    timeoutMs: flag('timeout') ? parseInt(flag('timeout'), 10) : undefined,
+                    maxIds: limit,
+                });
+                if (recon.truncated) {
+                    console.error(`note: result truncated at ${recon.remoteOnlyIds.length} ids; raise --limit to see more`);
+                }
+                if (hasFlag('ids-only')) {
+                    for (const id of recon.remoteOnlyIds)
+                        console.log(id);
+                    break;
+                }
+                // --only-missing: fetch just the events we do not already have
+                if (recon.remoteOnlyIds.length === 0)
+                    break;
+                const missing = await handleRelayQuery(pool, ctx.activeNpub, {
+                    ids: recon.remoteOnlyIds,
+                    relays: [target],
+                    limit: recon.remoteOnlyIds.length,
+                });
+                for (const ev of missing)
+                    console.log(JSON.stringify(ev));
+                break;
+            }
             const queryArgs = {
                 ...(stdinFilter ?? {
                     ...(kindsRaw ? { kinds: kindsRaw.split(',').map(Number) } : {}),

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.d.ts

@@ -8,6 +8,10 @@ export interface Helpers {
     flag(name: string, fallback?: string): string | undefined;
     flags(name: string): string[];
     hasFlag(name: string): boolean;
+    /** First value of whichever alias is present. Single-character names take one dash. */
+    flagAny(...names: string[]): string | undefined;
+    /** Every value across all the given aliases, in command-line order. */
+    flagsAny(...names: string[]): string[];
     out(data: unknown, humanFormatter?: (d: any) => string): void;
 }
 export type OutputMode = 'json' | 'human' | 'jsonl' | 'csv' | 'tsv';

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',
@@ -121,6 +123,26 @@ export function makeHelpers(cmdArgs, outputMode) {
         }
         return result;
     }
+    // `-k` and `--kind` should behave identically, so aliases are resolved by
+    // dash count rather than requiring every callsite to spell out both forms.
+    const asSwitch = (name) => (name.length === 1 ? `-${name}` : `--${name}`);
+    function flagAny(...names) {
+        const wanted = names.map(asSwitch);
+        for (let i = 0; i < cmdArgs.length - 1; i++) {
+            if (wanted.includes(cmdArgs[i]))
+                return cmdArgs[i + 1];
+        }
+        return undefined;
+    }
+    function flagsAny(...names) {
+        const wanted = names.map(asSwitch);
+        const result = [];
+        for (let i = 0; i < cmdArgs.length - 1; i++) {
+            if (wanted.includes(cmdArgs[i]))
+                result.push(cmdArgs[i + 1]);
+        }
+        return result;
+    }
     function out(data, humanFormatter) {
         switch (outputMode) {
             case 'jsonl':
@@ -150,7 +172,7 @@ export function makeHelpers(cmdArgs, outputMode) {
                 }
         }
     }
-    return { req, flag, flags, hasFlag, out };
+    return { req, flag, flags, hasFlag, flagAny, flagsAny, out };
 }
 /** Parse a shell line into args, respecting quotes */
 export function parseShellLine(line) {

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
@@ -189,7 +203,16 @@ Safety:
 
 Utility:
   req [--kinds N,N] [--authors hex,hex] [--since ts] [--limit N] [--relay url] [--min-trust level]  Query events
-  event --kind N [--tag k=v] [--content s] [--relay url] [--validation strict-known|off]  Validate, sign and publish an arbitrary event
+      [--paginate]                    Walk 'until' backwards until --limit is met
+                                      (--max-pages N caps round-trips, default 20;
+                                       --paginate-interval ms waits between pages)
+      [--ids-only]                    Fetch only event IDs, via NIP-77 negentropy
+      [--only-missing <events.jsonl>] Fetch only events absent from that file (NIP-77)
+  event -k <number|name> [-c content] [-t k=v] [-p pk] [-e id] [-d ident] [-h group]
+        [--relay url] [--pow N] [--created-at ts|ISO|now] [--envelope] [--nevent]
+        [--validation strict-known|off] [--no-publish]
+                                      Validate, sign and publish an arbitrary event.
+                                      -k takes a kind number or a registry name, e.g. -k "short text note"
   validate-event [event-json|--file path] [--validation strict-known|off]  Semantic protocol validation (no signature check)
   publish-raw [--file path] [--report] [--timeout ms] [--quorum n] [--validation strict-known|off]  Validate, sign+broadcast event
   subscribe [--kinds N,N] [--authors hex] [--relay url]  Live-tail events to stdout (JSONL) until SIGINT
@@ -206,6 +229,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 +245,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 +408,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 +425,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 +482,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 +490,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/event-validation/kind-lookup.d.ts

@@ -46,3 +46,14 @@ export declare function lookupKind(kind: number): KindInfo;
  * dozens of kinds whose descriptions merely contain "note".
  */
 export declare function searchKinds(query: string, limit?: number): KindInfo[];
+/**
+ * Resolve a kind given either a number or a description.
+ *
+ * `-k 1` and `-k "short text note"` should both work, which is what nak does
+ * and what makes the CLI usable without memorising kind numbers. An ambiguous
+ * name is an error rather than a guess: silently picking one of several
+ * matching kinds would publish the wrong thing.
+ *
+ * @throws if the name matches no kind, or more than one.
+ */
+export declare function resolveKind(input: string): number;

package/dist/event-validation/kind-lookup.js

@@ -84,3 +84,44 @@ export function searchKinds(query, limit = 20) {
     scored.sort((a, b) => a.score - b.score || a.kind - b.kind);
     return scored.slice(0, limit).map(s => lookupKind(s.kind));
 }
+/**
+ * Resolve a kind given either a number or a description.
+ *
+ * `-k 1` and `-k "short text note"` should both work, which is what nak does
+ * and what makes the CLI usable without memorising kind numbers. An ambiguous
+ * name is an error rather than a guess: silently picking one of several
+ * matching kinds would publish the wrong thing.
+ *
+ * @throws if the name matches no kind, or more than one.
+ */
+export function resolveKind(input) {
+    const trimmed = input.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const q = trimmed.toLowerCase();
+    const exact = [];
+    const partial = [];
+    for (const [k, schema] of Object.entries(PINNED_KIND_REGISTRY.kinds)) {
+        const desc = (schema.description ?? '').toLowerCase();
+        if (!desc)
+            continue;
+        if (desc === q)
+            exact.push(Number(k));
+        else if (desc.includes(q))
+            partial.push(Number(k));
+    }
+    if (exact.length === 1)
+        return exact[0];
+    if (exact.length > 1) {
+        throw new Error(`Kind name "${input}" matches several kinds: ${exact.join(', ')}. Use the number.`);
+    }
+    if (partial.length === 1)
+        return partial[0];
+    if (partial.length > 1) {
+        const shown = partial.slice(0, 8)
+            .map(k => `${k} (${PINNED_KIND_REGISTRY.kinds[String(k)].description})`)
+            .join(', ');
+        throw new Error(`Kind name "${input}" is ambiguous — matches ${partial.length}: ${shown}${partial.length > 8 ? ', …' : ''}. Use the number.`);
+    }
+    throw new Error(`No kind matches "${input}". Try: nostr-bray kind "${input}"`);
+}

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/social/handlers.d.ts

@@ -274,6 +274,8 @@ export declare function handlePublishEvent(ctx: SigningContext, pool: RelayPool,
     pow?: number;
     /** Wall-clock budget for mining, in milliseconds. */
     powTimeoutMs?: number;
+    /** Unix timestamp for created_at. Defaults to now. */
+    createdAt?: number;
 }): Promise<ValidatedPostResult & {
     pow?: Omit<MinePowResult, 'template'>;
 }>;

package/dist/social/handlers.js

@@ -480,7 +480,7 @@ export async function handleContactsUnfollow(ctx, pool, args) {
 export async function handlePublishEvent(ctx, pool, args) {
     let template = {
         kind: args.kind,
-        created_at: Math.floor(Date.now() / 1000),
+        created_at: args.createdAt ?? Math.floor(Date.now() / 1000),
         tags: args.tags ?? [],
         content: args.content,
     };

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": "2.0.0",
+  "version": "2.2.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",