nostr-bray 3.3.0 → 3.4.0

package/README.md

@@ -215,6 +215,7 @@ Search order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.
 | `NOSTR_NCRYPTSEC_PASSWORD` | Password for ncryptsec |
 | `NWC_URI_FILE` | Path to a private `0600` file containing the NWC bearer URI |
 | `NOSTR_RELAYS` | Comma-separated relay URLs |
+| `NOSTR_FORBID_PUBKEY` | Comma-separated npubs or hex this process must never sign as. See below. |
 | `TOR_PROXY` | SOCKS5h proxy for Tor |
 | `NIP04_ENABLED` | Set `1` to enable legacy NIP-04 DMs |
 | `TRANSPORT` | `stdio` (default) or `http` |
@@ -225,6 +226,32 @@ Raw `NWC_URI` is refused; use `NWC_URI_FILE` or `wallet connect <nwc-file>` so
 the bearer credential never appears in a process environment, command argument
 or MCP tool argument.
 
+### Keys this process must never be
+
+An agent that comes up holding the wrong key is indistinguishable from one
+working correctly. Every signature verifies, every tool succeeds, and the
+only symptom is that `whoami` quietly answers with somebody else's npub —
+which the driving model has no reason to doubt, because it is its own tool
+telling it.
+
+The worst version is a **principal's** key: a person's own. An agent signing
+as its principal can attest that it belongs to itself, and approve its own
+requests, because it *is* the principal those checks look for.
+
+```bash
+NOSTR_FORBID_PUBKEY=npub1yourownkey...,npub1anotherhuman...
+```
+
+or `forbidPubkeys` in the config file. Either takes npubs or hex. Activating
+one of those keys throws instead — at startup, on `identity-switch`, and on
+`bunker --persona` alike, because the check sits at the moment an identity
+becomes active rather than at any one entry point. An entry that cannot be
+parsed is an error too: a list nobody can read must not silently permit
+everything.
+
+The active npub is printed on stderr on every start, so the answer to "which
+key is this?" does not depend on asking the agent.
+
 ## Handing out a wallet connection
 
 `zap-send` spends through the NWC URI you configured. That URI is an

package/dist/cli/index.js

@@ -384,7 +384,7 @@ if (config.bunkerUri) {
     console.error(`Connected to ${hw ? 'Heartwood' : 'bunker'} — signing as ${ctx.activeNpub}`);
 }
 else {
-    ctx = new IdentityContext(config.secretKey, config.secretFormat);
+    ctx = new IdentityContext(config.secretKey, config.secretFormat, { forbidPubkeys: config.forbidPubkeys });
 }
 // NIP-42: the pool answers AUTH challenges with the active identity's key.
 pool.setAuthSigner(async (evt) => ctx.getSigningFunction()(evt));

package/dist/config.d.ts

@@ -36,6 +36,8 @@ interface ConfigFile {
     trustCacheTtl?: number;
     trustCacheMax?: number;
     dispatchIdentities?: string;
+    /** Public keys this process must never sign as. See ContextOptions. */
+    forbidPubkeys?: string[];
 }
 /**
  * Load config from a JSON file. Searches in order:

package/dist/config.js

@@ -283,6 +283,14 @@ export async function loadConfig() {
         : 'weekly';
     // --- Dispatch identities file ---
     const dispatchIdentities = process.env.DISPATCH_IDENTITIES ?? file.dispatchIdentities ?? undefined;
+    // Comma-separated npubs or hex. A list nobody can parse is rejected at
+    // startup by resolvePubkeyRef rather than silently permitting everything.
+    const forbidPubkeys = [
+        ...(process.env.NOSTR_FORBID_PUBKEY ?? '').split(','),
+        ...(file.forbidPubkeys ?? []),
+    ]
+        .map((s) => s.trim())
+        .filter(Boolean);
     // --- Wallets file ---
     const walletsFile = process.env.BRAY_WALLETS_FILE
         ?? file.walletsFile
@@ -309,5 +317,6 @@ export async function loadConfig() {
         port,
         bindAddress,
         dispatchIdentities,
+        forbidPubkeys,
     };
 }

package/dist/context.d.ts

@@ -3,14 +3,41 @@ import type { PublicIdentity, SignFn } from './types.js';
 import type { ExtendedSigningContext } from './signing-context.js';
 export interface ContextOptions {
     maxCache?: number;
+    /** Public keys this process must never sign as, hex or npub.
+     *
+     *  For PRINCIPALS - a person's own key. An agent that comes up holding one
+     *  is indistinguishable from one working correctly: every signature
+     *  verifies, every tool succeeds, and the only symptom is that `whoami`
+     *  quietly answers with a human's npub. Listing them here turns that into
+     *  a refusal at the moment of activation, which covers startup, an
+     *  `identity-switch`, and `bunker --persona` alike. */
+    forbidPubkeys?: string[];
 }
+/** An npub or 64-hex pubkey as lowercase hex. Throws on anything else, so a
+ *  forbidden entry nobody can parse fails loudly rather than silently
+ *  permitting everything. */
+export declare function resolvePubkeyRef(ref: string): string;
 export declare class IdentityContext implements ExtendedSigningContext {
     private root;
     private cache;
     private masterEntry;
     private activeEntry;
     private maxCacheSize;
+    private forbidden;
     constructor(secretKey: string, format: 'nsec' | 'hex' | 'mnemonic', opts?: ContextOptions);
+    /**
+     * Make an identity the active one, refusing a forbidden key.
+     *
+     * Every assignment to `activeEntry` goes through here - the constructor,
+     * `use()`, `switch()` and the persona paths - so there is no route to
+     * signing as a forbidden key, and no new route can be added by accident.
+     *
+     * Throws rather than falling back to the master identity. A process asked
+     * to be a key it must not be has been misconfigured, and quietly running
+     * as something else is how the misconfiguration survives to do damage.
+     * Only the npub is in the message; it is public, and nothing else is.
+     */
+    private activate;
     /** Current active identity's npub (bech32) */
     get activeNpub(): string;
     /** Derivation path of the current active identity, for reporting to a human */

package/dist/context.js

@@ -2,6 +2,7 @@ import { fromNsec, fromMnemonic, derive, zeroise } from 'nsec-tree';
 import { createBlindProof, createFullProof } from 'nsec-tree/proof';
 import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
 import { decode, npubEncode, nsecEncode } from 'nostr-tools/nip19';
+import { decode as decodeNip19 } from 'nostr-tools/nip19';
 /** Build an Identity-compatible object from raw key bytes */
 function rawIdentity(privateKey) {
     const publicKeyHex = getPublicKey(privateKey);
@@ -15,14 +16,45 @@ function rawIdentity(privateKey) {
         index: 0,
     };
 }
+/** An npub or 64-hex pubkey as lowercase hex. Throws on anything else, so a
+ *  forbidden entry nobody can parse fails loudly rather than silently
+ *  permitting everything. */
+export function resolvePubkeyRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('forbidPubkeys entry is empty');
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed))
+        return trimmed.toLowerCase();
+    if (trimmed.toLowerCase().startsWith('nsec1')) {
+        throw new Error('forbidPubkeys wants a PUBLIC key; that is an nsec. Treat it as exposed.');
+    }
+    try {
+        const decoded = decodeNip19(trimmed);
+        if (decoded.type === 'npub')
+            return decoded.data;
+        throw new Error(`forbidPubkeys entry "${trimmed}" is a ${decoded.type}, not an npub`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('forbidPubkeys'))
+            throw err;
+        throw new Error(`forbidPubkeys entry "${trimmed}" is neither an npub nor 64 hex characters`);
+    }
+}
 export class IdentityContext {
     root;
     cache = new Map();
     masterEntry;
+    // Definite-assignment asserted: every branch of the constructor assigns it
+    // through activate(), and TypeScript does not track assignments made
+    // inside a called method.
     activeEntry;
     maxCacheSize;
+    forbidden;
     constructor(secretKey, format, opts) {
         this.maxCacheSize = opts?.maxCache ?? 5;
+        // Built before anything is activated, so the constructor's own
+        // activation is checked too.
+        this.forbidden = new Set((opts?.forbidPubkeys ?? []).map(resolvePubkeyRef));
         // Parse the raw secret key bytes — this IS the user's actual Nostr identity
         let rawKeyBytes;
         if (format === 'mnemonic') {
@@ -30,7 +62,7 @@ export class IdentityContext {
             this.root = fromMnemonic(secretKey);
             const derived = derive(this.root, 'master', 0);
             this.masterEntry = { identity: derived, purpose: 'master', index: 0, lastUsed: Date.now() };
-            this.activeEntry = this.masterEntry;
+            this.activate(this.masterEntry);
             return;
         }
         else if (format === 'hex') {
@@ -47,10 +79,32 @@ export class IdentityContext {
             index: 0,
             lastUsed: Date.now(),
         };
-        this.activeEntry = this.masterEntry;
+        this.activate(this.masterEntry);
         // nsec-tree root for child derivation
         this.root = fromNsec(rawKeyBytes);
     }
+    /**
+     * Make an identity the active one, refusing a forbidden key.
+     *
+     * Every assignment to `activeEntry` goes through here - the constructor,
+     * `use()`, `switch()` and the persona paths - so there is no route to
+     * signing as a forbidden key, and no new route can be added by accident.
+     *
+     * Throws rather than falling back to the master identity. A process asked
+     * to be a key it must not be has been misconfigured, and quietly running
+     * as something else is how the misconfiguration survives to do damage.
+     * Only the npub is in the message; it is public, and nothing else is.
+     */
+    activate(entry) {
+        const hex = Buffer.from(entry.identity.publicKey).toString('hex');
+        if (this.forbidden.has(hex)) {
+            throw new Error(`Refusing to activate ${entry.identity.npub}: it is on this process's forbidden list. ` +
+                'That list is for principals - a person\'s key, never an agent\'s. An agent signing as its ' +
+                'principal can attest that it belongs to itself and approve its own requests, because it is ' +
+                'the principal those checks look for. Point NOSTR_SECRET_KEY at the agent\'s own key.');
+        }
+        this.activeEntry = entry;
+    }
     /** Current active identity's npub (bech32) */
     get activeNpub() {
         return this.activeEntry.identity.npub;
@@ -90,14 +144,14 @@ export class IdentityContext {
         for (const [, entry] of this.cache) {
             if (entry.purpose === purpose && entry.index === index && !entry.personaName) {
                 entry.lastUsed = Date.now();
-                this.activeEntry = entry;
+                this.activate(entry);
                 return;
             }
         }
         const identity = derive(this.root, purpose, index);
         const entry = { identity, purpose, index, lastUsed: Date.now() };
         this.putCache(identity.npub, entry);
-        this.activeEntry = entry;
+        this.activate(entry);
     }
     /** Derive a named persona */
     async derivePersona(name, index) {
@@ -123,7 +177,7 @@ export class IdentityContext {
     /** Switch active identity by purpose+index, persona name, or "master" */
     async switch(purposeOrName, index) {
         if (purposeOrName === 'master') {
-            this.activeEntry = this.masterEntry;
+            this.activate(this.masterEntry);
             this.masterEntry.lastUsed = Date.now();
             return;
         }
@@ -133,7 +187,7 @@ export class IdentityContext {
             const matchesPersona = entry.personaName === purposeOrName && (index === undefined || entry.index === index);
             if (matchesPurpose || matchesPersona) {
                 entry.lastUsed = Date.now();
-                this.activeEntry = entry;
+                this.activate(entry);
                 return;
             }
         }
@@ -160,7 +214,7 @@ export class IdentityContext {
             lastUsed: Date.now(),
         };
         this.putCache(identity.npub, entry);
-        this.activeEntry = entry;
+        this.activate(entry);
     }
     /** Get a signing function bound to the current active identity */
     getSigningFunction() {

package/dist/index.js

@@ -104,7 +104,12 @@ if (config.bunkerUri) {
     void establishBunkerInBackground(base);
 }
 else {
-    ctx = new IdentityContext(config.secretKey, config.secretFormat);
+    ctx = new IdentityContext(config.secretKey, config.secretFormat, { forbidPubkeys: config.forbidPubkeys });
+    // Said out loud, on stderr, every start. The alternative is asking the
+    // agent which identity it holds, and an agent whose key is wrong will
+    // answer that confidently and wrongly - it has no reason to doubt its
+    // own tools. stdout is reserved for JSON-RPC.
+    console.error(`Signing as ${ctx.activeNpub}`);
     // Local key is ready immediately -- load its relay list now.
     loadIdentityRelays(ctx.activeNpub);
 }

package/dist/types.d.ts

@@ -61,6 +61,11 @@ export interface BrayConfig {
     readonly port: number;
     readonly bindAddress: string;
     readonly dispatchIdentities?: string;
+    /** Public keys this process must never sign as, hex or npub. For
+     *  principals: an agent holding one can attest that it belongs to itself
+     *  and approve its own requests. Enforced in IdentityContext, at the
+     *  moment an identity is activated. */
+    readonly forbidPubkeys?: string[];
 }
 export type { SigningContext, ExtendedSigningContext } from './signing-context.js';
 export { hasExtendedIdentity } from './signing-context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "3.3.0",
+  "version": "3.4.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",