fips/docs/how-to/persistent-identity.md

Provision a Persistent Identity

A FIPS node's identity is a Nostr keypair. Its public key (npub) determines the node's fd00::/8 mesh address; peers and configs reference the node by that npub. Out of the box the daemon generates a fresh identity on every start (node.identity.persistent: false), which is fine for one-off testing but useless when other nodes need to refer to this one across restarts.

This guide covers the three ways to give a node a stable identity. For the configuration keys involved, see ../reference/configuration.md.

First time? If you have just installed FIPS and want a hand-held walkthrough of the package-default path (set persistent: true, restart, observe the keys land), the persistent-identity tutorial is the gentler entry point. This guide assumes an operator picking among Options A/B/C for a deployment.

When to use

Use a persistent identity for any node that:

• Other operators reference by npub (in their peers lists, hosts files, or ACL allow-lists).
• Acts as a discoverable bootstrap or rendezvous (Nostr advert, static peer entry, gateway).
• Is expected to keep its fd00::/8 mesh address across restarts.

Stay with the ephemeral default for throw-away clients, sandbox nodes, and tests where you actively want a fresh identity per run.

Option A: Let the package do it

The Debian/Ubuntu .deb and the Arch fips AUR package both ship a default /etc/fips/fips.yaml with node.identity.persistent left as the upstream default (false), so the daemon writes a fresh keypair to /etc/fips/fips.{key,pub} on every start until you set persistent: true. To pin the current keypair:

1. Install the package and start the daemon once so it generates fips.key / fips.pub:

   sudo systemctl start fips
   sudo systemctl status fips     # confirm it came up
   

2. Edit /etc/fips/fips.yaml and set:

   node:
     identity:
       persistent: true
   

3. Restart the daemon and verify the identity is reused:

   sudo systemctl restart fips
   fipsctl show status | grep -E '"npub"|"node_addr"'
   cat /etc/fips/fips.pub
   

   The npub printed by fipsctl show status should match /etc/fips/fips.pub and remain stable across subsequent restarts.

The package's postinst script does not generate the keypair — the daemon does, on first start. This means the keypair is only present after the first successful daemon start. If the daemon never came up cleanly (config error, permission problem), the key files will be missing.

macOS note

The macOS package (.pkg) installs config and keys under /usr/local/etc/fips/ instead of /etc/fips/. The paths above become:

Linux / other Unix	macOS
/etc/fips/fips.yaml	/usr/local/etc/fips/fips.yaml
/etc/fips/fips.key	/usr/local/etc/fips/fips.key
/etc/fips/fips.pub	/usr/local/etc/fips/fips.pub

fipsctl keygen writes to /usr/local/etc/fips/ by default on macOS. The daemon still probes /etc/fips/fips.yaml as a fallback (so an existing install is not broken by an upgrade), but the macOS packaging only installs files under /usr/local/etc/fips/.

If you have files in /etc/fips/ from a manual install, move them:

sudo mv /etc/fips/fips.yaml /usr/local/etc/fips/fips.yaml
sudo mv /etc/fips/fips.key /usr/local/etc/fips/fips.key
sudo mv /etc/fips/fips.pub /usr/local/etc/fips/fips.pub
sudo mv /etc/fips/peers.allow /usr/local/etc/fips/peers.allow 2>/dev/null || true
sudo mv /etc/fips/peers.deny /usr/local/etc/fips/peers.deny 2>/dev/null || true
sudo mv /etc/fips/hosts /usr/local/etc/fips/hosts 2>/dev/null || true

The daemon logs a warning at startup if any of peers.allow, peers.deny, or hosts exist at the old /etc/fips/ path but not at /usr/local/etc/fips/. fips.yaml is deliberately not included: both directories stay on the config search path, so a config file left at /etc/fips/ is still read and is not a stranded file.

fips.key is handled differently again, because losing it is worse than not reading it. The daemon derives the key directory from whichever config file loaded last, so a host carrying fips.yaml at both locations resolves the key to /usr/local/etc/fips/. If no key is there and one exists at /etc/fips/fips.key, the daemon uses the old key and warns, rather than generating a new identity: a fresh keypair would change the node's npub, routing address and mesh IPv6 with no migration path. Move the key when you see that warning; the fallback exists to make the upgrade survivable, not to be relied on.

File layout and permissions

Path	Mode	Owner	Contents
/etc/fips/fips.key	0600	root:root	Bech32 nsec (one line).
/etc/fips/fips.pub	0644	root:root	Bech32 npub (one line).

Both files live next to the highest-priority fips.yaml the daemon loaded. For non-systemd installs that use a different config path, the key files are placed in that config's directory.

Option B: Generate manually

For from-source installs, custom config paths, or any deployment where you want to mint the keypair before the daemon ever runs.

With fipsctl keygen

sudo fipsctl keygen --dir /etc/fips

This writes /etc/fips/fips.key (mode 0600) and /etc/fips/fips.pub (mode 0644), prints the new npub on stderr, and reminds you to set persistent: true. Add --force to overwrite an existing fips.key. Add --stdout to print nsec then npub to stdout instead of writing files.

To put the keypair in a non-default directory (e.g., a per-deployment config tree), pass --dir and point your fips.yaml search at the matching directory.

Without the daemon installed

If you cannot run fipsctl (e.g., scripting on a build host), any nostr-tools-equivalent that emits a bech32 nsec works. Write the nsec to fips.key (mode 0600) and the corresponding npub to fips.pub (mode 0644).

Hooking the keypair into the config

node:
  identity:
    persistent: true

persistent: true plus a fips.key next to the loaded config is the intended steady-state setup.

Option C: Provision from an existing nsec

To migrate an existing Nostr identity into a FIPS node — for example, re-using a personal npub for a node you operate.

1. Obtain the bech32 nsec for the identity.

2. Write it to the config-adjacent key file:

   sudo install -m 0600 -o root -g root /dev/null /etc/fips/fips.key
   sudo bash -c 'printf "%s\n" nsec1... > /etc/fips/fips.key'
   

3. Derive the matching npub and write fips.pub:

   # compute the npub with any nostr tool, then:
   sudo bash -c 'printf "%s\n" npub1... > /etc/fips/fips.pub'
   sudo chmod 0644 /etc/fips/fips.pub
   

4. Set persistent: true and restart:

   node:
     identity:
       persistent: true
   

   sudo systemctl restart fips
   fipsctl show status | grep '"npub"'
   

The reported npub should match the one you wrote to fips.pub.

Verifying

The daemon prints the resolved identity at startup; the same value is queryable via the control socket:

fipsctl show status | jq '{npub, node_addr, ipv6_addr}'
cat /etc/fips/fips.pub

The npub field of show status and the contents of fips.pub should match. The node_addr is the SHA-256 prefix used internally by FMP/FSP; the ipv6_addr is the routable fd00::/8 mesh address derived from the node addr. Together they are stable for the lifetime of the keypair.

The journal also records the source on every start:

INFO Loaded persistent identity from key file path=/etc/fips/fips.key

(Generated persistent identity, saved to key file on the first start; Using ephemeral identity (new keypair each start) when persistence is off.)

Rotating

Key rotation is a destructive operation: every cached (node_addr → npub) mapping on every other node points at the old key, every Nostr advert and every static peer entry references the old npub, and every existing FSP session was authenticated under the old keypair. There is no in-protocol "key change" message.

To rotate:

1. Stop the daemon.

   sudo systemctl stop fips
   

2. Remove the existing key files.

   sudo rm /etc/fips/fips.key /etc/fips/fips.pub
   

3. Start the daemon. With persistent: true, the daemon generates a new keypair and writes new fips.key / fips.pub.

   sudo systemctl start fips
   cat /etc/fips/fips.pub   # the new npub
   

4. Update every downstream reference: peer configs that name this node by npub, hosts files, ACL allow-lists, Nostr adverts pinned by other operators.

There is no recovery from a lost fips.key — the npub is gone with the secret. Treat key rotation as a coordinated event; do not rotate production identities ad hoc.

See also

• ../reference/configuration.md — node.identity.* keys.
• ../reference/cli-fipsctl.md — fipsctl keygen.
• ../design/fips-architecture.md — identity model, npub-to-NodeAddr derivation.