nostr-bray 1.40.1 → 1.42.2

package/dist/admin/handlers.d.ts

@@ -7,7 +7,20 @@
  * Reference: https://github.com/nostr-protocol/nips/blob/master/86.md
  */
 import type { SigningContext } from '../signing-context.js';
-export type AdminMethod = 'allowpubkey' | 'banpubkey' | 'listallowedpubkeys' | 'listbannedpubkeys' | 'allowkind' | 'bankind' | 'listallowedkinds' | 'listbannedkinds' | 'blockip' | 'unblockip' | 'listblockedips';
+/** Method names defined by NIP-86, plus widely-implemented extensions. */
+export type AdminMethod = 'supportedmethods' | 'allowpubkey' | 'unallowpubkey' | 'banpubkey' | 'unbanpubkey' | 'listallowedpubkeys' | 'listbannedpubkeys' | 'allowkind' | 'disallowkind' | 'listallowedkinds' | 'allowevent' | 'banevent' | 'listbannedevents' | 'listeventsneedingmoderation' | 'changerelayname' | 'changerelaydescription' | 'changerelayicon' | 'createrole' | 'editrole' | 'deleterole' | 'assignrole' | 'unassignrole' | 'grantadmin' | 'revokeadmin' | 'blockip' | 'unblockip' | 'listblockedips' | 'listdisallowedkinds';
+/**
+ * Legacy bray subcommand names retained as aliases.
+ *
+ * `bankind` and `listbannedkinds` were never NIP-86 method names, so requests
+ * using them were rejected by spec-compliant relays. They are still accepted as
+ * input and rewritten to the correct wire method.
+ */
+export declare const ADMIN_METHOD_ALIASES: Record<string, AdminMethod>;
+/** Resolve a user-supplied method name to its NIP-86 wire name. */
+export declare function resolveAdminMethod(method: string): AdminMethod;
+/** Coerce the parameters a given method expects as numbers, leaving the rest alone. */
+export declare function coerceAdminParams(method: AdminMethod, params: Array<string | number>): Array<string | number>;
 export interface AdminCallOptions {
     /** Relay HTTP URL (e.g. https://relay.example.com) */
     relay: string;

package/dist/admin/handlers.js

@@ -6,6 +6,48 @@
  *
  * Reference: https://github.com/nostr-protocol/nips/blob/master/86.md
  */
+/**
+ * Legacy bray subcommand names retained as aliases.
+ *
+ * `bankind` and `listbannedkinds` were never NIP-86 method names, so requests
+ * using them were rejected by spec-compliant relays. They are still accepted as
+ * input and rewritten to the correct wire method.
+ */
+export const ADMIN_METHOD_ALIASES = {
+    bankind: 'disallowkind',
+    listbannedkinds: 'listdisallowedkinds',
+};
+/**
+ * Positions (zero-indexed) whose parameter is a number rather than a string.
+ *
+ * Everything else is passed through verbatim. Blanket numeric coercion is
+ * unsafe here because an all-digit 64-character pubkey would be mangled by
+ * `Number()`.
+ */
+const NUMERIC_PARAM_POSITIONS = {
+    allowkind: [0],
+    disallowkind: [0],
+    createrole: [4],
+    editrole: [4],
+};
+/** Resolve a user-supplied method name to its NIP-86 wire name. */
+export function resolveAdminMethod(method) {
+    return ADMIN_METHOD_ALIASES[method] ?? method;
+}
+/** Coerce the parameters a given method expects as numbers, leaving the rest alone. */
+export function coerceAdminParams(method, params) {
+    const numeric = NUMERIC_PARAM_POSITIONS[method];
+    if (!numeric)
+        return params;
+    return params.map((p, i) => {
+        if (!numeric.includes(i) || typeof p === 'number')
+            return p;
+        const n = Number(p);
+        if (!Number.isFinite(n))
+            throw new Error(`${method}: parameter ${i + 1} must be a number, got "${p}"`);
+        return n;
+    });
+}
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 /**
  * Build a NIP-98 HTTP Auth header value for the given URL and HTTP method.
@@ -40,9 +82,11 @@ async function buildNip98Header(ctx, url, httpMethod, payloadHash) {
 export async function handleAdminCall(ctx, opts) {
     // NIP-86 always POSTs to the relay root URL
     const url = opts.relay.replace(/\/$/, '');
+    // Rewrite legacy aliases so SDK callers get the spec method name on the wire too
+    const method = resolveAdminMethod(opts.method);
     const body = JSON.stringify({
-        method: opts.method,
-        params: opts.params ?? [],
+        method,
+        params: coerceAdminParams(method, opts.params ?? []),
     });
     // Hash the request body for the NIP-98 payload tag (SHA-256 hex)
     const { createHash } = await import('node:crypto');
@@ -65,7 +109,7 @@ export async function handleAdminCall(ctx, opts) {
         throw new Error(`Relay error: ${json.error}`);
     return {
         relay: opts.relay,
-        method: opts.method,
+        method,
         result: json.result,
     };
 }

package/dist/bunker-context.d.ts

@@ -16,6 +16,13 @@ import { BunkerSigner } from 'nostr-tools/nip46';
 import { SimplePool } from 'nostr-tools/pool';
 import type { PublicIdentity, SignFn } from './types.js';
 import type { SigningContext } from './signing-context.js';
+/**
+ * Reject if `promise` does not settle within `ms`. Converts a silent NIP-46
+ * hang into a catchable error so callers can fail fast or retry with backoff
+ * instead of wedging -- which, at startup under an MCP health check, becomes a
+ * respawn loop that floods the signer.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
 export interface BunkerConfig {
     pubkey: string;
     /**
@@ -73,9 +80,29 @@ export declare class BunkerContext implements SigningContext {
     protected pool: SimplePool;
     protected pubkeyHex: string | undefined;
     private clientSk;
-    protected constructor(signer: BunkerSigner, pool: SimplePool, clientSk: Uint8Array);
+    private config;
+    protected constructor(signer: BunkerSigner, pool: SimplePool, clientSk: Uint8Array, config: ReturnType<typeof parseBunkerUri>);
+    /**
+     * Construct a BunkerContext WITHOUT performing the network handshake.
+     * Lets a caller bring its process up immediately and connect in the
+     * background (see {@link establish}), so a slow or unreachable signer
+     * cannot wedge startup. Under an MCP stdio health check that respawns
+     * "failed to connect" servers, a wedged startup turns a flaky signer into
+     * a respawn loop that floods the bunker with `connect` requests.
+     */
+    static create(uri: string, stateDir?: string): BunkerContext;
+    /**
+     * Perform the NIP-46 `connect` handshake, bounded by `timeoutMs`.
+     *
+     * nostr-tools' BunkerSigner has no per-request timeout, so a signer that is
+     * offline or whose relays are unreachable makes `signer.connect()` hang
+     * forever. We race it against a timer and reject on expiry so the caller can
+     * retry with backoff. Ping is redundant (a successful connect proves the
+     * signer is alive) and getPublicKey is deferred to first access.
+     */
+    establish(timeoutMs?: number): Promise<void>;
     /** Connect to a remote bunker. Blocks until the connection is established. */
-    static connect(uri: string, _timeoutMs?: number, stateDir?: string): Promise<BunkerContext>;
+    static connect(uri: string, timeoutMs?: number, stateDir?: string): Promise<BunkerContext>;
     /**
      * Resolve the signing identity pubkey from the remote bunker.
      * Called lazily on first access so startup stays fast (no extra

package/dist/bunker-context.js

@@ -19,6 +19,25 @@ import { npubEncode } from 'nostr-tools/nip19';
 import WebSocket from 'ws';
 import { readStateFile, writeStateFile } from './state.js';
 useWebSocketImplementation(WebSocket);
+/** Bound the NIP-46 connect handshake. nostr-tools' BunkerSigner has no
+ *  per-request timeout, so an offline signer or unreachable relays make the
+ *  connect hang forever. */
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Bound individual signer round-trips (sign_event, get_public_key, nip44). */
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Reject if `promise` does not settle within `ms`. Converts a silent NIP-46
+ * hang into a catchable error so callers can fail fast or retry with backoff
+ * instead of wedging -- which, at startup under an MCP health check, becomes a
+ * respawn loop that floods the signer.
+ */
+export function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
 /** Parse a bunker:// URI */
 export function parseBunkerUri(uri) {
     // bunker://<pubkey>?relay=<url>&relay=<url>...&secret=<hex>
@@ -74,13 +93,22 @@ export class BunkerContext {
     pool;
     pubkeyHex;
     clientSk;
-    constructor(signer, pool, clientSk) {
+    config;
+    constructor(signer, pool, clientSk, config) {
         this.signer = signer;
         this.pool = pool;
         this.clientSk = clientSk;
+        this.config = config;
     }
-    /** Connect to a remote bunker. Blocks until the connection is established. */
-    static async connect(uri, _timeoutMs = 15_000, stateDir) {
+    /**
+     * Construct a BunkerContext WITHOUT performing the network handshake.
+     * Lets a caller bring its process up immediately and connect in the
+     * background (see {@link establish}), so a slow or unreachable signer
+     * cannot wedge startup. Under an MCP stdio health check that respawns
+     * "failed to connect" servers, a wedged startup turns a flaky signer into
+     * a respawn loop that floods the bunker with `connect` requests.
+     */
+    static create(uri, stateDir) {
         const config = parseBunkerUri(uri);
         const clientSk = resolveClientKey(config, stateDir);
         const pool = new SimplePool();
@@ -93,18 +121,39 @@ export class BunkerContext {
             // request will require a manual approval on the signer side.
             secret: config.connectSecret ?? null,
         }, { pool });
-        // Only the `connect` handshake is needed at startup. Ping is
-        // redundant (if connect succeeded the signer is alive), and
-        // getPublicKey is deferred to first access so startup stays fast.
-        // Sent via sendRequest (not signer.connect()) so params[3] can carry
-        // the client-name metadata that signer approval screens display.
-        // nostr-tools' connect() is literally sendRequest('connect', [pubkey,
-        // secret]) — semantics are otherwise identical.
-        await signer.sendRequest('connect', buildConnectParams(config));
-        const ctx = new BunkerContext(signer, pool, clientSk);
-        // Do NOT use config.pubkey here — that is the bunker's transport
-        // key from the URI, not the signing identity. The actual identity
-        // pubkey is resolved lazily via getPublicKey() on first access.
+        // Do NOT use config.pubkey as the identity -- it is the bunker's
+        // transport key from the URI, not the signing identity. The actual
+        // identity pubkey is resolved lazily via resolvePublicKey().
+        // The parsed config is retained so establish() can send the connect
+        // handshake with its client-name metadata.
+        return new BunkerContext(signer, pool, clientSk, config);
+    }
+    /**
+     * Perform the NIP-46 `connect` handshake, bounded by `timeoutMs`.
+     *
+     * nostr-tools' BunkerSigner has no per-request timeout, so a signer that is
+     * offline or whose relays are unreachable makes `signer.connect()` hang
+     * forever. We race it against a timer and reject on expiry so the caller can
+     * retry with backoff. Ping is redundant (a successful connect proves the
+     * signer is alive) and getPublicKey is deferred to first access.
+     */
+    async establish(timeoutMs = CONNECT_TIMEOUT_MS) {
+        // Sent via sendRequest (not signer.connect()) so params[3] can carry the
+        // client-name metadata that signer approval screens display. nostr-tools'
+        // connect() is literally sendRequest('connect', [pubkey, secret]);
+        // semantics are otherwise identical.
+        await withTimeout(this.signer.sendRequest('connect', buildConnectParams(this.config)), timeoutMs, 'bunker connect');
+    }
+    /** Connect to a remote bunker. Blocks until the connection is established. */
+    static async connect(uri, timeoutMs = CONNECT_TIMEOUT_MS, stateDir) {
+        const ctx = BunkerContext.create(uri, stateDir);
+        try {
+            await ctx.establish(timeoutMs);
+        }
+        catch (e) {
+            ctx.destroy();
+            throw e;
+        }
         return ctx;
     }
     /**
@@ -114,7 +163,7 @@ export class BunkerContext {
      */
     async resolvePublicKey() {
         if (!this.pubkeyHex) {
-            this.pubkeyHex = await this.signer.getPublicKey();
+            this.pubkeyHex = await withTimeout(this.signer.getPublicKey(), REQUEST_TIMEOUT_MS, 'bunker get_public_key');
         }
         return this.pubkeyHex;
     }
@@ -135,7 +184,7 @@ export class BunkerContext {
     /** Sign an event via the remote bunker */
     getSigningFunction() {
         return async (template) => {
-            return this.signer.signEvent(template);
+            return withTimeout(this.signer.signEvent(template), REQUEST_TIMEOUT_MS, 'bunker sign_event');
         };
     }
     /** List identities — bunker mode only has one (the remote key) */
@@ -144,11 +193,11 @@ export class BunkerContext {
     }
     /** NIP-44 encrypt via the remote bunker */
     async nip44Encrypt(recipientPubkey, plaintext) {
-        return this.signer.nip44Encrypt(recipientPubkey, plaintext);
+        return withTimeout(this.signer.nip44Encrypt(recipientPubkey, plaintext), REQUEST_TIMEOUT_MS, 'bunker nip44_encrypt');
     }
     /** NIP-44 decrypt via the remote bunker */
     async nip44Decrypt(senderPubkey, ciphertext) {
-        return this.signer.nip44Decrypt(senderPubkey, ciphertext);
+        return withTimeout(this.signer.nip44Decrypt(senderPubkey, ciphertext), REQUEST_TIMEOUT_MS, 'bunker nip44_decrypt');
     }
     /** Clean up */
     destroy() {

package/dist/cli/commands/admin.d.ts

@@ -1,2 +1,6 @@
+import type { AdminMethod } from '../../exports.js';
 import type { Helpers } from '../dispatch.js';
+export declare const ADMIN_METHODS: Set<AdminMethod>;
+/** Legacy subcommand spellings still accepted on the CLI. */
+export declare const ADMIN_ALIASES: string[];
 export declare function dispatch(cmd: string, cmdArgs: string[], h: Helpers, ctx: any): Promise<void>;

package/dist/cli/commands/admin.js

@@ -1,26 +1,37 @@
-import { handleAdminCall } from '../../exports.js';
-const ADMIN_METHODS = new Set([
-    'allowpubkey', 'banpubkey', 'listallowedpubkeys', 'listbannedpubkeys',
-    'allowkind', 'bankind', 'listallowedkinds', 'listbannedkinds',
+import { handleAdminCall, coerceAdminParams, resolveAdminMethod, ADMIN_METHOD_ALIASES } from '../../exports.js';
+export const ADMIN_METHODS = new Set([
+    'supportedmethods',
+    'allowpubkey', 'unallowpubkey', 'banpubkey', 'unbanpubkey',
+    'listallowedpubkeys', 'listbannedpubkeys',
+    'allowkind', 'disallowkind', 'listallowedkinds', 'listdisallowedkinds',
+    'allowevent', 'banevent', 'listbannedevents', 'listeventsneedingmoderation',
+    'changerelayname', 'changerelaydescription', 'changerelayicon',
+    'createrole', 'editrole', 'deleterole', 'assignrole', 'unassignrole',
+    'grantadmin', 'revokeadmin',
     'blockip', 'unblockip', 'listblockedips',
 ]);
+/** Legacy subcommand spellings still accepted on the CLI. */
+export const ADMIN_ALIASES = Object.keys(ADMIN_METHOD_ALIASES);
 export async function dispatch(cmd, cmdArgs, h, ctx) {
     // cmd is always 'admin'; subcommand is cmdArgs[1] (already sliced by normaliser)
     // After COMPOUND_COMMANDS normalisation: cmd = 'admin-<subcommand>'
     const { req, out } = h;
-    // Extract the method from the compound command name
-    const method = cmd.replace(/^admin-/, '');
-    if (!ADMIN_METHODS.has(method)) {
-        throw new Error(`Unknown admin subcommand: ${method}. Valid: ${[...ADMIN_METHODS].join(', ')}`);
+    // Extract the method from the compound command name, mapping legacy spellings.
+    // A bare `admin` means the subcommand was not recognised during normalisation.
+    const requested = cmd === 'admin' ? (cmdArgs[1] ?? '') : cmd.replace(/^admin-/, '');
+    const method = resolveAdminMethod(requested);
+    if (!requested || !ADMIN_METHODS.has(method)) {
+        throw new Error(`${requested ? `Unknown admin subcommand: ${requested}.` : 'admin needs a subcommand.'}\n` +
+            `Usage: admin <subcommand> <relay-url> [param...]\n` +
+            `Valid: ${[...ADMIN_METHODS].join(', ')}`);
+    }
+    if (requested !== method) {
+        console.error(`note: "admin ${requested}" is not a NIP-86 method name; sending "${method}" instead`);
     }
     const relay = req(1, `admin ${method} <relay-url> [param...]`);
     // Remaining positional args after relay URL are method params
     const params = cmdArgs.slice(2).filter(a => !a.startsWith('--'));
-    // allowkind / bankind take integer params
-    const coercedParams = params.map(p => {
-        const n = Number(p);
-        return isNaN(n) ? p : n;
-    });
+    const coercedParams = coerceAdminParams(method, params);
     out(await handleAdminCall(ctx, {
         relay,
         method,

package/dist/cli/commands/event.js

@@ -15,13 +15,19 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool) {
             const content = flag('content') ?? '';
             const validationMode = parseValidationMode(flag('validation'));
             const relayOverrides = flags('relay');
+            const pow = flag('pow') ? parseInt(flag('pow'), 10) : undefined;
+            const powTimeoutMs = flag('pow-timeout') ? parseInt(flag('pow-timeout'), 10) : undefined;
             if (hasFlag('no-publish')) {
-                const template = {
+                const { minePow } = await import('../../event/pow.js');
+                let template = {
                     kind,
                     created_at: Math.floor(Date.now() / 1000),
                     tags: tagValues,
                     content,
                 };
+                if (pow !== undefined) {
+                    template = minePow(template, { difficulty: pow, pubkey: ctx.activePublicKeyHex, timeoutMs: powTimeoutMs }).template;
+                }
                 const validation = assertEventSemanticallyValid(template, validationMode);
                 reportWarnings(validation.issues);
                 const sign = ctx.getSigningFunction();
@@ -35,6 +41,8 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool) {
                 tags: tagValues,
                 relays: relayOverrides.length ? relayOverrides : undefined,
                 validationMode,
+                pow,
+                powTimeoutMs,
             }));
             break;
         }
@@ -56,6 +64,8 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool) {
                 timeoutMs,
                 quorum,
                 validationMode,
+                pow: flag('pow') ? parseInt(flag('pow'), 10) : undefined,
+                powTimeoutMs: flag('pow-timeout') ? parseInt(flag('pow-timeout'), 10) : undefined,
             });
             if (report) {
                 const { accepted, rejected, errors } = result.publish;

package/dist/cli/commands/relay.js

@@ -57,15 +57,24 @@ export async function dispatch(cmd, cmdArgs, h, ctx, pool, _activeNpub) {
                     tags[k].push(v);
                 }
             }
-            const queryArgs = stdinFilter ?? {
-                ...(kindsRaw ? { kinds: kindsRaw.split(',').map(Number) } : {}),
-                ...(authorsRaw ? { authors: authorsRaw.split(',') } : {}),
-                ...(since !== undefined ? { since } : {}),
-                ...(until !== undefined ? { until } : {}),
-                ...(limit !== undefined ? { limit } : {}),
-                ...(search ? { search } : {}),
-                ...(Object.keys(tags).length ? { tags } : {}),
-                ...(relayOverrides.length ? { relays: relayOverrides } : {}),
+            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;
+            const queryArgs = {
+                ...(stdinFilter ?? {
+                    ...(kindsRaw ? { kinds: kindsRaw.split(',').map(Number) } : {}),
+                    ...(authorsRaw ? { authors: authorsRaw.split(',') } : {}),
+                    ...(since !== undefined ? { since } : {}),
+                    ...(until !== undefined ? { until } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                    ...(search ? { search } : {}),
+                    ...(Object.keys(tags).length ? { tags } : {}),
+                    ...(relayOverrides.length ? { relays: relayOverrides } : {}),
+                }),
+                // Pagination is a transport concern, so it applies to a stdin filter too
+                ...(paginate ? { paginate } : {}),
+                ...(paginateIntervalMs !== undefined ? { paginateIntervalMs } : {}),
+                ...(maxPages !== undefined ? { maxPages } : {}),
             };
             let events = await handleRelayQuery(pool, ctx.activeNpub, queryArgs);
             const minTrust = flag('min-trust');

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, } from '../../exports.js';
+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 { 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 'kind': {
+            const arg = req(1, 'kind <number|search text>');
+            if (/^\d+$/.test(arg)) {
+                out(lookupKind(Number(arg)), fmt.formatKindInfo);
+            }
+            else {
+                const results = searchKinds(cmdArgs.slice(1).filter(a => !a.startsWith('--')).join(' '));
+                if (results.length === 0)
+                    throw new Error(`No kind matches "${arg}"`);
+                out(results, rs => rs.map(fmt.formatKindInfo).join('\n\n'));
+            }
+            break;
+        }
         case 'encrypt': {
             const skHex = Buffer.from(ctx.activePrivateKey).toString('hex');
             console.log(handleEncrypt(skHex, req(1, 'encrypt <pubkey-hex> "plaintext"'), req(2, 'encrypt <pubkey-hex> "plaintext"')));

package/dist/cli/dispatch.d.ts

@@ -1,4 +1,6 @@
 /** Shared dispatch helpers shared across all CLI command modules. */
+export declare const ADMIN_SUBCOMMANDS: readonly ["supportedmethods", "allowpubkey", "unallowpubkey", "banpubkey", "unbanpubkey", "listallowedpubkeys", "listbannedpubkeys", "allowkind", "disallowkind", "listallowedkinds", "listdisallowedkinds", "allowevent", "banevent", "listbannedevents", "listeventsneedingmoderation", "changerelayname", "changerelaydescription", "changerelayicon", "createrole", "editrole", "deleterole", "assignrole", "unassignrole", "grantadmin", "revokeadmin", "blockip", "unblockip", "listblockedips", "bankind", "listbannedkinds"];
+export declare const ADMIN_COMMANDS: string[];
 export declare const COMPOUND_COMMANDS: Set<string>;
 export declare const OFFLINE_COMMANDS: Set<string>;
 export interface Helpers {

package/dist/cli/dispatch.js

@@ -1,4 +1,21 @@
 /** Shared dispatch helpers shared across all CLI command modules. */
+// NIP-86 relay management subcommands, plus the two legacy bray spellings
+// (`bankind`, `listbannedkinds`) kept as aliases. Declared once and reused for
+// compound-command normalisation, routing, and shell completion.
+export const ADMIN_SUBCOMMANDS = [
+    'supportedmethods',
+    'allowpubkey', 'unallowpubkey', 'banpubkey', 'unbanpubkey',
+    'listallowedpubkeys', 'listbannedpubkeys',
+    'allowkind', 'disallowkind', 'listallowedkinds', 'listdisallowedkinds',
+    'allowevent', 'banevent', 'listbannedevents', 'listeventsneedingmoderation',
+    'changerelayname', 'changerelaydescription', 'changerelayicon',
+    'createrole', 'editrole', 'deleterole', 'assignrole', 'unassignrole',
+    'grantadmin', 'revokeadmin',
+    'blockip', 'unblockip', 'listblockedips',
+    // legacy aliases
+    'bankind', 'listbannedkinds',
+];
+export const ADMIN_COMMANDS = ADMIN_SUBCOMMANDS.map(s => `admin-${s}`);
 // Known two-word commands: `noun subverb` → normalised to `noun-subverb` internally.
 // Enumerated explicitly to avoid swallowing positional args (e.g. `profile <pubkey>`).
 export const COMPOUND_COMMANDS = new Set([
@@ -16,9 +33,7 @@ export const COMPOUND_COMMANDS = new Set([
     // sync
     'sync-plan', 'sync-pull', 'sync-push',
     // admin (NIP-86 relay management)
-    'admin-allowpubkey', 'admin-banpubkey', 'admin-listallowedpubkeys', 'admin-listbannedpubkeys',
-    'admin-allowkind', 'admin-bankind', 'admin-listallowedkinds', 'admin-listbannedkinds',
-    'admin-blockip', 'admin-unblockip', 'admin-listblockedips',
+    ...ADMIN_COMMANDS,
     // wallet (NIP-47 Nostr Wallet Connect)
     'wallet-connect', 'wallet-disconnect', 'wallet-status', 'wallet-pay', 'wallet-balance', 'wallet-history',
 ]);
@@ -29,10 +44,12 @@ 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',
+    'validate-event', 'kind',
     'musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate',
     // wallet config subcommands don't touch the relay
     'wallet-connect', 'wallet-disconnect', 'wallet-status',
+    // NIP-86 admin calls are plain HTTP to the target relay; the pool is not used
+    ...ADMIN_COMMANDS,
 ]);
 export function resolveOutputMode(cmdArgs, envDefault) {
     if (cmdArgs.includes('--jsonl'))

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { IdentityContext } from '../context.js';
 import { RelayPool } from '../relay-pool.js';
 import { Nip65Manager } from '../nip65.js';
 import { getCommandHelp } from '../help.js';
-import { COMPOUND_COMMANDS, OFFLINE_COMMANDS, makeHelpers, resolveOutputMode, parseShellLine } from './dispatch.js';
+import { COMPOUND_COMMANDS, OFFLINE_COMMANDS, ADMIN_COMMANDS, makeHelpers, resolveOutputMode, parseShellLine } from './dispatch.js';
 import * as identity from './commands/identity.js';
 import * as social from './commands/social.js';
 import * as trust from './commands/trust.js';
@@ -28,6 +28,18 @@ for (const flag of ['--bunker', '--key']) {
         args.splice(i, 2);
     }
 }
+// Boolean global flags, recognised only in the leading position (`--auth req ...`)
+// so they can be stripped before command detection. Anything after the command
+// belongs to that command: `relay curl <url> --auth` means NIP-98, not NIP-42.
+let authFlagPresent = false;
+let eagerAuthFlagPresent = false;
+while (args[0] === '--auth' || args[0] === '--eager-auth') {
+    if (args[0] === '--eager-auth')
+        eagerAuthFlagPresent = true;
+    else
+        authFlagPresent = true;
+    args.shift();
+}
 const command = args[0];
 // No command = start MCP server.
 if (!command) {
@@ -136,10 +148,23 @@ Sync (NIP-77 reconciliation, then explicit REQ/EVENT transfer):
   Options: --protocol auto|nip77|req-fallback --timeout ms --max-remote N
 
 Admin (NIP-86 relay management):
-  admin allowpubkey|banpubkey <relay-url> <pubkey-hex>
+  admin supportedmethods <relay-url>                    List methods the relay implements
+  admin allowpubkey|unallowpubkey <relay-url> <pubkey> [reason]
+  admin banpubkey|unbanpubkey <relay-url> <pubkey> [reason]
   admin listallowedpubkeys|listbannedpubkeys <relay-url>
-  admin allowkind|bankind <relay-url> <kind>   (list: listallowedkinds|listbannedkinds)
-  admin blockip|unblockip <relay-url> <ip>     (list: listblockedips)
+  admin allowkind|disallowkind <relay-url> <kind>
+  admin listallowedkinds|listdisallowedkinds <relay-url>
+  admin allowevent|banevent <relay-url> <event-id> [reason]
+  admin listbannedevents|listeventsneedingmoderation <relay-url>
+  admin changerelayname|changerelaydescription|changerelayicon <relay-url> <value>
+  admin createrole|editrole <relay-url> <id> <label> <description> <colour> <order>
+  admin deleterole <relay-url> <id>
+  admin assignrole|unassignrole <relay-url> <pubkey> <role-id>
+  admin grantadmin|revokeadmin <relay-url> <pubkey>
+  admin blockip|unblockip <relay-url> <ip> [reason]
+  admin listblockedips <relay-url>
+  (bankind and listbannedkinds are accepted as aliases for disallowkind and
+   listdisallowedkinds; they were never NIP-86 method names)
 
 Wallet (NIP-47 Nostr Wallet Connect):
   wallet connect <nwc-url>            Store NWC URI for the active identity
@@ -180,6 +205,7 @@ Utility:
   filter <event-json> <filter-json>   Test if event matches filter
   nips                                List all official NIPs
   nip <number>                        Show a specific NIP
+  kind <number|text>                  Look up an event kind: required tags, value shapes
   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
@@ -207,6 +233,7 @@ Environment:
   NOSTR_SECRET_KEY_FILE         Path to secret key file
   BUNKER_URI / BUNKER_URI_FILE  bunker:// URI (use INSTEAD of secret key)
   NOSTR_RELAYS                  Comma-separated relay URLs
+  NOSTR_AUTH                    NIP-42 policy: off (default), on-demand, eager
   NWC_URI / NWC_URI_FILE        Nostr Wallet Connect URI
   TOR_PROXY                     SOCKS5h proxy URL
   NOSTR_BRAY_OUTPUT             Default output: "human" (default) or "json"
@@ -223,6 +250,8 @@ Quick examples:
 Flags:
   --bunker <uri>                      Use bunker:// URI (overrides env/config)
   --key <nsec|hex|mnemonic>           Use this secret key (overrides env/config)
+  --auth                              Answer NIP-42 AUTH after an auth-required rejection
+  --eager-auth                        Answer the NIP-42 AUTH challenge as soon as it arrives
   --json                              Output raw JSON (for piping/scripts)
   --human                             Force human-readable output
   --jsonl | --csv | --tsv             Structured list output (line-, comma- or tab-delimited)
@@ -304,11 +333,16 @@ if (command === 'validate-event') {
 const config = await loadConfig();
 const { configureHttpClient } = await import('../http-client.js');
 configureHttpClient({ torProxy: config.torProxy });
+// `--auth` / `--eager-auth` override the NOSTR_AUTH env default for one run.
+const authMode = eagerAuthFlagPresent
+    ? 'eager'
+    : authFlagPresent ? 'on-demand' : config.authMode;
 const pool = new RelayPool({
     torProxy: config.torProxy,
     allowClearnet: config.allowClearnetWithTor || !config.torProxy,
     defaultRelays: config.relays,
     allowPrivateRelays: config.allowPrivateRelays,
+    authMode,
 });
 const nip65 = new Nip65Manager(pool, config.relays);
 let ctx;
@@ -325,6 +359,8 @@ if (config.bunkerUri) {
 else {
     ctx = new IdentityContext(config.secretKey, config.secretFormat);
 }
+// NIP-42: the pool answers AUTH challenges with the active identity's key.
+pool.setAuthSigner(async (evt) => ctx.getSigningFunction()(evt));
 const globalNwcUri = config.nwcUri;
 const walletsFile = config.walletsFile;
 config.secretKey = '';
@@ -362,15 +398,12 @@ 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', 'encrypt', 'decrypt', 'count', 'fetch',
+    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', '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']);
-const ADMIN_CMDS = new Set([
-    'admin-allowpubkey', 'admin-banpubkey', 'admin-listallowedpubkeys', 'admin-listbannedpubkeys',
-    'admin-allowkind', 'admin-bankind', 'admin-listallowedkinds', 'admin-listbannedkinds',
-    'admin-blockip', 'admin-unblockip', 'admin-listblockedips',
-]);
+// Bare `admin` is routed too so an unrecognised subcommand gets a useful error
+const ADMIN_CMDS = new Set(['admin', ...ADMIN_COMMANDS]);
 const WALLET_CMDS = new Set([
     'wallet-connect', 'wallet-disconnect', 'wallet-status', 'wallet-pay', 'wallet-balance', 'wallet-history',
 ]);
@@ -429,12 +462,10 @@ 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', 'encrypt', 'decrypt', 'count', 'fetch',
+    'key-public', 'key-encrypt', 'key-decrypt', 'filter', 'nips', 'nip', 'verify', 'validate-event', 'kind', 'encrypt', 'decrypt', 'count', 'fetch',
     'musig2-key', 'musig2-nonce', 'musig2-partial-sign', 'musig2-aggregate',
     'sync-plan', 'sync-pull', 'sync-push',
-    'admin-allowpubkey', 'admin-banpubkey', 'admin-listallowedpubkeys', 'admin-listbannedpubkeys',
-    'admin-allowkind', 'admin-bankind', 'admin-listallowedkinds', 'admin-listbannedkinds',
-    'admin-blockip', 'admin-unblockip', 'admin-listblockedips',
+    ...ADMIN_COMMANDS,
     'wallet-connect', 'wallet-disconnect', 'wallet-status', 'wallet-pay', 'wallet-balance', 'wallet-history',
     'relay-curl',
     'bunker',