Docker image / build-and-push-image (push) Has been cancelled

Details

fix(daemon): autounlock walks config.allKeys, not prisma.key (#16 )

The first cut of `maybeAutounlock` enumerated `prisma.key` based on
the design issue's pseudocode. Empirically that's the wrong source:
the Prisma `Key` table is only populated by the NIP-05
`create_account` path, which stores keys *plain-at-rest* in
`nsecbunker.json` (no encryption involved). The `create_new_key`
flow that lnbits's `RemoteBunkerSigner` uses provisions encrypted
`{iv, data}` blobs directly into the JSON `keys` map without
touching the Prisma table at all.

Result of the v1 enumeration on regtest:

  🔓 autounlock: enabled (source=NSEC_BUNKER_AUTOUNLOCK_PASSPHRASE),
     unlocked 0/0 keys in 0ms

…despite 67 encrypted blobs sitting in nsecbunker.json. The Prisma
table was empty because none of the regtest keys came from
`create_account`. Greg's key would have been a no-op even with the
autounlock env set; the manual `unlock_key` admin RPC would still
have been required.

Fix: enumerate `this.config.allKeys` (the in-memory snapshot of
`nsecbunker.json`'s `keys` map, populated at daemon-fork time per
`src/commands/start.ts:144`) filtered to entries with the `iv`+`data`
shape. That's the canonical "what's encrypted at rest" set —
exactly the rows for which manual `unlock_key` was previously
required per restart.

Plain-key entries (`{key: ...}` from `create_account`) are skipped
here for log clarity — they were already loaded by `startKeys`'
second pass and live in `activeKeys`; `unlockKey`'s post-#16
idempotency guard would no-op them anyway, but emitting "unlocked"
log lines for keys that didn't need unlocking is noise.

Updates `docs/AUTOUNLOCK.md` accordingly so the description matches
the implementation.

Refs aiolabs/nsecbunkerd#16.

2026-05-31 15:34:51 +02:00

6.8 KiB

Raw Permalink Blame History

Boot-time autounlock

nsecbunkerd stores each managed key encrypted at rest in nsecbunker.db. By default, every key is locked after the daemon starts — clients must drive an unlock_key admin RPC against the bunker before signing / encrypting / decrypting works for that key.

Autounlock is an opt-in feature that, when enabled, reads a passphrase from a configured source at boot and unlocks every non-soft-deleted key in the Key table automatically. This trades operational simplicity for a documented security weakening; read this whole document before enabling.

Configuration

Two mutually-exclusive environment variables:

Var	Meaning
`NSEC_BUNKER_AUTOUNLOCK_PASSPHRASE`	Literal passphrase string. Useful for dev / `docker compose .env` flows.
`NSEC_BUNKER_AUTOUNLOCK_PASSPHRASE_FILE`	Path to a file containing the passphrase (newline-trimmed at read). Idiomatic for sops / systemd-LoadCredential / k8s-secret / external secrets-manager flows where the passphrase comes from a separate credential store.

If both are set, the daemon fails loud at boot with an explicit error. Ambiguous config is never allowed to silently pick one.

If neither is set, autounlock is off — behavior is identical to pre-#16: keys remain locked until an admin unlock_key RPC fires per key per restart.

What happens at boot when autounlock is on

After the daemon's existing key-loading passes complete (unencrypted keys from in-process config, plain-key entries in nsecbunker.json), the autounlock pass runs:

Read the passphrase from the configured source. Failure to read (missing file, no permission) is fatal at boot.
Enumerate the encrypted-at-rest entries in nsecbunker.json's keys map — entries carrying the {iv, data} shape from create_new_key. Plain-key entries ({key: ...} shape from create_account) are already loaded by the existing startKeys() passes and are skipped here for log clarity.
For each candidate, call unlockKey(keyName, passphrase). unlockKey is idempotent post-#16: if the key was already unlocked by a prior pass, it's a no-op.
Log per-key INFO on success, WARN on unlockKey → false (typically: wrong passphrase, possibly the key was created under a historical passphrase that differs from the current one), ERROR on throw (typically: corrupted blob).
Log one summary line: 🔓 autounlock: enabled (source=<env>), unlocked N/M keys in <Xms>.

The loop is sequential — log clarity > parallelism, the unlock op itself is cheap (one ChaCha20 decrypt per key). For 100 keys it's milliseconds. If a fleet ever needs the thousands, parallelize then.

The NIP-46 client channel doesn't accept RPCs that route to a key until that key's Backend.start() resolves — which happens inside unlockKey. So there's no race window where a freshly-restarted bunker would say "key locked" to a client while the loop is in flight on that key.

The security trade-off

Enabling autounlock means whoever can read the passphrase source can recover any key from the bunker disk. Specifically:

The encrypt-at-rest property of nsecbunker.db is preserved against cat /var/lib/nsecbunker/*.db alone — the database holds ciphertext + IV per key, not plaintext.
The encrypt-at-rest property is lost if the attacker also has access to the passphrase source. Anyone with read access to the passphrase env var, the passphrase file, or the process memory at the moment of autounlock can decrypt every key.

This is the same trade today's deployments already make when they hold the passphrase in lnbits's env to drive unlock_key RPCs post-restart. Autounlock makes the trade explicit at the bunker level and visible per-deployment, but it doesn't introduce a new trust requirement that didn't already exist for any deployment using external automation to drive unlocks.

Recommendations by deployment shape

Dev / regtest / single-host: literal NSEC_BUNKER_AUTOUNLOCK_PASSPHRASE in docker compose .env is fine. The threat model on a dev box doesn't justify the file-source ceremony.
Single-tenant production: passphrase file on a separate volume / mount with stricter access. Mount via systemd-LoadCredential so the file is only readable by the bunker process and is materialized from a sops-decrypted source at boot. Avoid baking the passphrase into the container image or process env list (which leaks into ps aux, container labels, etc.).
Multi-tenant / high-security: leave autounlock off. Orchestrate unlock per-restart from an external process that prompts for the passphrase out-of-band (hardware token, HSM-derived secret, human approval). This preserves the property that bunker startup alone doesn't restore crypto capability — a deliberate human action is required.

What's not in scope

These are deliberately out of scope for the autounlock feature. Separate issues to file if needed:

Per-key passphrase support. The current Key table doesn't carry per-key passphrase metadata; every create_new_key(name, passphrase) in our usage today uses the same passphrase (LNBITS_NSEC_BUNKER_KEYSTORE_PASSPHRASE). The autounlock passphrase covers every encrypted key by virtue of this single-passphrase invariant. If a deployment ever needs per-key passphrases, that's a separate feature (per-key passphrase-selector column + per-key passphrase map).
Passphrase rotation. Re-encrypting every key under a new passphrase belongs in a dedicated admin RPC (rotate_keystore), not in autounlock.
HSM / hardware-derived passphrase delivery. Orthogonal to where the passphrase comes from at unlock time — autounlock just reads a string. An HSM integration would land between the hardware and the file the bunker reads from.

Observability hooks

The autounlock pass emits:

🔓 autounlock: unlocked <keyName> (INFO, one per success)
⚠️ autounlock: unlockKey returned false for <keyName> ... (WARN, one per soft failure)
❌ autounlock: <keyName> failed: <err.message> (ERROR, one per throw)
🔓 autounlock: enabled (source=<env>), unlocked N/M keys in <Xms> (summary, once)

When the optional Prometheus exporter lands, counters nsecbunkerd_keys_unlocked_total and nsecbunkerd_keys_locked_total will be reported from the autounlock summary state. The current implementation doesn't export metrics — the log line is the canonical signal.

6.8 KiB Raw Permalink Blame History