Feature: Import existing Nostr nsec into DID identity

[santyr]

Summary

Add an import-nsec command to Keymaster that allows importing an existing Nostr private key (nsec) into a DID identity, rather than only supporting derived keys via add-nostr.

Motivation

Currently, add-nostr derives a Nostr keypair from the DID HD key. This means users who already have an established Nostr identity (with followers, reputation, NIP-05 verification, etc.) cannot use that identity with their Archon DID. They must either:

1. Use set-property to link the pubkey as metadata only (no signing capability), or
2. Abandon their existing Nostr identity and use the Archon-derived one.

Neither option is ideal for users with established Nostr presences.

Proposed Solution

Add a new CLI command:

keymaster import-nsec <nsec> [id]

This would:

1. Decode the nsec (bech32) to raw private key bytes
2. Derive the corresponding public key (npub + hex pubkey)
3. Store the private key encrypted in the wallet under idInfo.nostr (or a new idInfo.nostrImported field to distinguish from derived keys)
4. Update didDocumentData.nostr with the npub and pubkey
5. Allow sign-nostr-event to use the imported key instead of the derived one

Security considerations

• The imported nsec should be encrypted at rest in the wallet (same protection as the mnemonic)
• export-nsec should work for imported keys as well
• Clear documentation that imported keys are stored (vs derived keys which are never stored)

API surface

Command	Description
import-nsec <nsec> [id]	Import existing Nostr private key
export-nsec [id]	Already exists — should also return imported keys
remove-nostr [id]	Already exists — should clean up imported keys too

Alternatives Considered

• Metadata-only linking: Works for discovery but not for signing Nostr events through Archon.
• NIP-46 remote signer: Would allow Archon to request signatures from an external signer, but adds complexity and requires the signer to be online.

Additional Context

This was identified during DID setup where a user wanted to link their existing Nostr identity (npub1...) to their Archon DID with full signing capability.

[santyr]

Alternative: nsecbunker as Remote Signing Oracle

After further discussion, there is a potentially better approach than storing imported nsecs directly in the Archon wallet: delegating Nostr signing to nsecbunker, an LNbits extension that acts as a NIP-46-style signing oracle.

How it works today

nsecbunker is already deployed on our LNbits instance (lnb.bolverker.com). It:

• Stores Nostr private keys encrypted at rest using the LNbits server secret (AES)
• Exposes a REST API for signing, NIP-04/NIP-44 encrypt/decrypt, and pubkey retrieval
• Gates signing by per-extension, per-kind permissions with optional rate limits
• Maintains a full audit log of all signing operations
• Supports key import, export, and generation
• Already serves other LNbits extensions (CyberHerd, LNURLp, etc.) — the same key is used across all of them

Why this is better than import-nsec

Concern	import-nsec (wallet-native)	nsecbunker (remote signer)
Key duplication	Yes — nsec copied into Archon wallet	No — single source of truth in LNbits
Key rotation	Must update every wallet that has a copy	Update once in nsecbunker, all consumers get it
Access control	All-or-nothing per DID	Per-extension, per-event-kind, with rate limits
Audit trail	None	Built-in signing log with timestamps
Encryption support	Would need to implement NIP-04/NIP-44 in Keymaster	Already implemented — just call the API
Existing ecosystem	Standalone	Same key already serves CyberHerd, LNURLp, split payments, etc.
Blast radius if wallet is compromised	nsec exposed	nsec stays in LNbits; Archon wallet only has API credentials

Architecture: Wallet-native config, LNbits-linked signing

The nsecbunker config should be stored inside the Archon wallet alongside the existing Lightning wallet credentials, linked to the same LNbits wallet that the DID already uses. This keeps the configuration portable, encrypted, and tied to the identity — not floating in environment variables.

Since each DID already has Lightning credentials bound to an LNbits wallet (via add-lightning), the nsecbunker config naturally lives alongside them. The LNbits wallet key that Archon already stores is the same key nsecbunker uses for authentication — so there is zero new credential management needed.

Wallet structure (extending existing idInfo.lightning):

{
  "ids": {
    "Sat": {
      "did": "did:cid:bagaaiera...",
      "lightning": {
        "http://127.0.0.1:4222": {
          "walletId": "c2c499...",
          "adminKey": "d67dc6...",
          "invoiceKey": "ac0dcb...",
          "nostrSigner": {
            "type": "nsecbunker",
            "keyId": "abc123",
            "extensionId": "archon"
          }
        }
      }
    }
  }
}

The nostrSigner block sits inside the per-URL Lightning config because:

• The LNbits base URL is already known (from the Drawbridge connection)
• The invoiceKey is already stored and is sufficient for nsecbunker signing operations
• The nsecbunker API lives at the same LNbits host (/nsecbunker/api/v1/...)
• No additional credentials needed — the wallet key is the auth

Automated setup via add-nostr --signer nsecbunker

Archon should handle all nsecbunker setup automatically when the user runs:

keymaster add-nostr --signer nsecbunker [--nsec <nsec>] [identity]

No manual nsecbunker configuration required. The command would call nsecbunker's own API to set everything up:

Step 1: Ensure a key exists in nsecbunker

If --nsec is provided (user has an existing Nostr identity):

POST /nsecbunker/api/v1/keys
X-Api-Key: <invoiceKey from wallet>
{"private_key": "<hex-encoded nsec>", "label": "archon:<did-suffix>"}

If no --nsec (generate a new Nostr identity):

POST /nsecbunker/api/v1/keys/generate
X-Api-Key: <invoiceKey from wallet>
{"label": "archon:<did-suffix>"}

Both return the key_id needed for subsequent calls.

Step 2: Get the public key

GET /nsecbunker/api/v1/pubkey?key_id=<key_id>
X-Api-Key: <invoiceKey from wallet>

Returns the hex pubkey, which Archon converts to npub for the DID metadata.

Step 3: Grant signing permissions for Archon

POST /nsecbunker/api/v1/permissions
X-Api-Key: <adminKey from wallet>
{
  "key_id": "<key_id>",
  "extension_id": "archon",
  "kind": 1,
  "kind_label": "Short Text Note",
  "rate_limit_count": 1000,
  "rate_limit_seconds": 86400
}

Repeated for each event kind Archon needs. Recommended default set:

Kind	Label	Use case
0	Profile Metadata	Publishing DID-linked Nostr profile
1	Short Text Note	General posting
4	Encrypted DM (NIP-04)	Direct messaging
6	Repost	Sharing content
7	Reaction	Likes/reactions
1059	Gift Wrap (NIP-44 DMs)	Modern encrypted DMs
30023	Long-form Content	Blog posts / articles

The admin key (already in the wallet) is required for permission grants. Invoice key suffices for signing.

Step 4: Store config in wallet and update DID

Save nostrSigner config in the wallet:

{
  "type": "nsecbunker",
  "keyId": "<key_id>",
  "extensionId": "archon"
}

Update didDocumentData.nostr with the pubkey:

{
  "npub": "npub1...",
  "pubkey": "5302cd2b..."
}

The entire flow is a single CLI command. User experience:

# Link existing Nostr identity
keymaster add-nostr --signer nsecbunker --nsec nsec1... Sat

# Or generate a new one
keymaster add-nostr --signer nsecbunker Sat

Signing integration

Modify signNostrEvent() in keymaster.ts (~20 lines):

async signNostrEvent(event: NostrEvent): Promise<NostrEvent> {
    const id = await this.fetchIdInfo();
    
    // Check for nsecbunker signer in Lightning config
    const lightningConfig = this.getLightningConfigWithSigner(id);
    if (lightningConfig?.nostrSigner?.type === "nsecbunker") {
        const { keyId, extensionId } = lightningConfig.nostrSigner;
        const lnbitsUrl = this.getDrawbridgeLnbitsUrl();
        const apiKey = lightningConfig.invoiceKey;
        
        const response = await fetch(`${lnbitsUrl}/nsecbunker/api/v1/sign`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "X-Api-Key": apiKey
            },
            body: JSON.stringify({
                extension_id: extensionId,
                key_id: keyId,
                event: {
                    kind: event.kind,
                    content: event.content,
                    tags: event.tags,
                    created_at: event.created_at
                }
            })
        });
        return response.json();
    }
    
    // Fall back to derived key signing (existing behavior)
    const keypair = await this.fetchKeyPair();
    // ... existing code ...
}

NIP-04/NIP-44 support

Comes free — Archon can call using the same wallet key and key_id:

• POST /nsecbunker/api/v1/nip04/encrypt and /decrypt
• POST /nsecbunker/api/v1/nip44/encrypt and /decrypt

This means Archon DIDs get encrypted Nostr DM capability without implementing any cryptography.

Removal

remove-nostr should clean up both sides:

1. DELETE /nsecbunker/api/v1/permissions/<id> — revoke Archon's signing permissions
2. Remove nostrSigner from the wallet
3. Clear didDocumentData.nostr

The key itself is not deleted from nsecbunker (other extensions may still use it). Only Archon's access is revoked.

nsecbunker changes required

None. All required API endpoints already exist:

Archon needs	nsecbunker endpoint	Auth level
Import existing key	POST /api/v1/keys	invoice key
Generate new key	POST /api/v1/keys/generate	invoice key
Get pubkey	GET /api/v1/pubkey?key_id=	invoice key
Grant permissions	POST /api/v1/permissions	admin key
Sign events	POST /api/v1/sign	invoice key
NIP-04 encrypt/decrypt	POST /api/v1/nip04/*	invoice key
NIP-44 encrypt/decrypt	POST /api/v1/nip44/*	invoice key
Revoke permissions	DELETE /api/v1/permissions/<id>	admin key

nsecbunker is ready as-is. The work is 100% on the Archon side.

What this enables

• Users with established Nostr identities can link them to their DID with full signing capability
• Config is portable — stored encrypted in the Archon wallet, travels with backup/restore
• No new credentials to manage — piggybacks on existing LNbits wallet key
• The same Nostr key serves all LNbits extensions + Archon without duplication
• Archon agents can post to Nostr, encrypt/decrypt DMs, all through the DID identity
• Rate limiting and permissions prevent runaway signing from any single consumer
• Key never leaves the LNbits server boundary
• Single CLI command sets up the entire chain: key → permissions → wallet config → DID metadata

Backward compatibility

This is purely additive. The existing add-nostr (derived keys) path remains the default. nsecbunker is an opt-in alternative for users who want to use existing keys or centralized key management. The nostrSigner field is optional — if absent, everything works exactly as before.

References

• nsecbunker repo: https://github.com/lightning-goats/nsecbunker
• NIP-46 (Nostr Connect): https://github.com/nostr-protocol/nips/blob/master/46.md

[santyr]

Implementation Complete

PR #264 implements the full nsecbunker integration as described above.

What was built and tested

1. add-nostr-signer CLI command — single command imports/generates key in nsecbunker, grants permissions, stores config in wallet, updates DID
2. signNostrEvent() nsecbunker delegation — checks for signer config, delegates via REST, falls back to derived keys
3. exportNsec() guard — blocked when nsecbunker is configured (prevents exposing unrelated DID-derived key)
4. addNostr() guard — blocked when nsecbunker is configured (prevents overwriting imported identity)
5. Dockerfile.keymaster — rebundled embedded client UI (restores serve-client from Move gatekeeper and keymaster clients to standalone containers #202)
6. REST API — POST /nostr/signer endpoint + KeymasterClient method

nsecbunker fixes (separate repo)

Three bugs were found and fixed in nsecbunker during testing:

• stored field crash — LNbits adds a dynamic stored attribute to Pydantic models; fixed with Config(extra="ignore") (c0bc5fe)
• model_config column error — Pydantic v2 ConfigDict was serialized as a DB column; reverted to v1 inner Config class
• public_key → pubkey — pynostr Event dataclass parameter name mismatch (86e48d2)
• Added pyproject.toml with pynostr and nostr_sdk dependencies (66a9934)

Testing results

All operations verified end-to-end against live nsecbunker instance:

• Key import ✅ | Key generate ✅ | Permission grants ✅ | Remote signing ✅
• npub bech32 encoding ✅ | Wallet persistence ✅ | DID metadata update ✅
• exportNsec guard ✅ | addNostr guard ✅ | Fallback to derived keys ✅
• Embedded UI at :4226 ✅ | Correct error message shown instead of wrong nsec ✅

[macterra]

Duplicates #135 and #239