docs: explain encrypted consensus signing keys

src/pages/cli/node.mdx

@@ -33,6 +33,7 @@ Flags grouped by function:
 | Flag | Description |
 | --- | --- |
 | `--consensus.signing-key <path>` | Path to validator signing key |
+| `--consensus.secret <path>` | Path to the secret used to decrypt an encrypted validator signing key. Prefer a named pipe (FIFO) or shell process substitution. |
 | `--consensus.fee-recipient <addr>` | Deprecated validator fee-recipient flag. Migrate to on-chain fee-recipient management via Validator Config V2. |
 | `--consensus.datadir <path>` | Separate volume for consensus data |
 
@@ -65,6 +66,7 @@ Start a validator:
 tempo node --datadir /data/tempo \
   --chain mainnet \
   --consensus.signing-key /etc/tempo/key \
+  --consensus.secret /run/tempo/consensus-secret \
   --consensus.fee-recipient 0x...
 ```
 

src/pages/guide/node/validator-keys.mdx

@@ -30,19 +30,81 @@ Never share your private signing key. Anyone with access to it can impersonate y
 Use a different key for each network rather than reusing the same validator identity on testnet and mainnet.
 :::
 
-Generate an ed25519 keypair:
+Generate an encrypted ed25519 keypair. The `--secret` argument points to a file-like input that contains the encryption key. Prefer a named pipe (FIFO) or shell process substitution for this path: a FIFO lets one process stream bytes directly to another process without storing those bytes as a regular file, and it keeps the secret out of environment variables and command-line arguments. See [Why FIFOs and not env vars](#why-fifos-and-not-env-vars).
 
 ```bash
-tempo consensus generate-private-key --output <path>
+mkfifo /run/tempo/consensus-secret
+<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
+tempo consensus generate-signing-key \
+  --output <SIGNING_KEY_PATH> \
+  --secret /run/tempo/consensus-secret
 ```
 
 Verify the public key:
 
 ```bash
-tempo consensus calculate-public-key --private-key <path>
+<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
+tempo consensus show-verification-key \
+  --private-key <SIGNING_KEY_PATH> \
+  --secret /run/tempo/consensus-secret
 ```
 
-The public key should match the output of the `generate-private-key` command.
+The verification key should match the output of the `generate-signing-key` command.
+
+`<ENCRYPTION_KEY_CMD>` should be a command that retrieves the encryption key from your KMS or secret manager and writes the raw secret to stdout.
+
+### Encrypting an existing signing key
+
+If you already have an unencrypted ed25519 signing key, encrypt it with `tempo consensus encrypt-signing-key`. The command reads the existing plaintext key, reads the encryption key from `--secret`, and writes a new encrypted key file.
+
+```bash
+tempo consensus encrypt-signing-key \
+  --input <OLD_SIGNING_KEY_PATH> \
+  --output <ENCRYPTED_SIGNING_KEY_PATH> \
+  --secret <(<ENCRYPTION_KEY_CMD>)
+```
+
+Verify the encrypted key before replacing the old file:
+
+```bash
+tempo consensus show-verification-key \
+  --private-key <ENCRYPTED_SIGNING_KEY_PATH> \
+  --secret <(<ENCRYPTION_KEY_CMD>)
+```
+
+After the verification key matches the old signing key's public key, update `--consensus.signing-key` to point at the encrypted file and start `tempo node` with `--consensus.secret <ENCRYPTION_KEY_PATH>`.
+
+Once the encrypted key is verified and backed up, delete the old unencrypted key file. On Linux, you can use `shred` to overwrite and remove the file:
+
+```bash
+shred --remove --zero <OLD_SIGNING_KEY_PATH>
+```
+
+### Why FIFOs and not env vars
+
+`--secret` accepts any filesystem path. The `tempo node` binary does not place extra restrictions on where it reads the secret from, so a regular file works, but a named pipe (FIFO) or process-substitution path is preferred. A FIFO is a special filesystem entry used to pass data between processes; it has a path, but the bytes written to it are streamed through the kernel rather than stored as regular file contents.
+
+Use a FIFO so the encryption key is provided to `tempo` only when it is needed, without putting the key in the process environment or command-line arguments. Environment variables can be inherited by child processes and may be exposed through process inspection, crash dumps, shell history, or service-manager diagnostics. A FIFO also avoids leaving the secret behind in a regular file, though the producing command and `tempo` may still hold the value briefly in process memory while handling it.
+
+:::warning
+The `printf` example below is only a demonstration of how a FIFO works. Do not put production encryption keys directly in shell commands, shell history, scripts, or environment variables.
+:::
+
+```bash
+mkfifo /run/tempo/consensus-secret
+printf '%s' '<ENCRYPTION_KEY>' > /run/tempo/consensus-secret &
+tempo consensus show-verification-key \
+  --private-key <SIGNING_KEY_PATH> \
+  --secret /run/tempo/consensus-secret
+```
+
+With shell process substitution and a KMS-backed secret command:
+
+```bash
+tempo consensus generate-signing-key \
+  --output <SIGNING_KEY_PATH> \
+  --secret <(<ENCRYPTION_KEY_CMD>)
+```
 
 ## Signing key rotation
 

src/pages/guide/node/validator-setup.mdx

@@ -15,7 +15,7 @@ This guide walks through registering, generating your signing key, and starting
 
 Registering a validator takes three steps:
 
-1. **[Generate a signing keypair](#step-1-generate-a-signing-keypair)** — Create an ed25519 private key and derive the public key.
+1. **[Generate a signing keypair](#step-1-generate-a-signing-keypair)** — Create an encrypted ed25519 private key and derive the public key.
 2. **[Create the add-validator signature](#step-2-create-the-add-validator-signature)** — Prove ownership of the signing key by producing a signature over your registration details.
 3. **[Submit registration details](#step-3-submit-registration-details)** — Provide the Tempo team with all required values to add your validator on-chain.
 
@@ -25,19 +25,28 @@ Registering a validator takes three steps:
 Never share your private signing key. Anyone with access to it can impersonate your validator. The Tempo team will never ask for your private key.
 :::
 
-Generate an ed25519 keypair:
+Generate an encrypted ed25519 keypair. The `--secret` argument points to a file-like input that contains the encryption key. Prefer a named pipe (FIFO) or shell process substitution for this path: a FIFO lets one process stream bytes directly to another process without storing those bytes as a regular file, and it keeps the secret out of environment variables and command-line arguments. See [Why FIFOs and not env vars](/guide/node/validator-keys#why-fifos-and-not-env-vars).
 
 ```bash
-tempo consensus generate-private-key --output <path>
+mkfifo /run/tempo/consensus-secret
+<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
+tempo consensus generate-signing-key \
+  --output <SIGNING_KEY_PATH> \
+  --secret /run/tempo/consensus-secret
 ```
 
 Verify the public key:
 
 ```bash
-tempo consensus calculate-public-key --private-key <path>
+<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
+tempo consensus show-verification-key \
+  --private-key <SIGNING_KEY_PATH> \
+  --secret /run/tempo/consensus-secret
 ```
 
-The public key should match the output of the `generate-private-key` command.
+The public key should match the output of the `generate-signing-key` command.
+
+`<ENCRYPTION_KEY_CMD>` should be a command that retrieves the encryption key from your KMS or secret manager and writes the raw secret to stdout.
 
 ### Step 2: Create the add-validator signature
 
@@ -107,16 +116,18 @@ Once you've downloaded the snapshot and have been whitelisted on-chain, you can
 tempo node --datadir <datadir> \
     --chain mainnet \
     --consensus.signing-key <path> \
+    --consensus.secret <ENCRYPTION_KEY_FIFO> \
     --telemetry-url <TELEMETRY_URL>
 ```
 ```bash [Testnet]
 tempo node --datadir <datadir> \
     --chain moderato \
     --consensus.signing-key <path> \
+    --consensus.secret <ENCRYPTION_KEY_FIFO> \
     --telemetry-url <TELEMETRY_URL>
 ```
 ::::
-The notable difference between RPC nodes and validator nodes is the omission of the `--follow` argument and the addition of the `--consensus.signing-key` argument.
+The notable difference between RPC nodes and validator nodes is the omission of the `--follow` argument and the addition of the `--consensus.signing-key` argument. If the signing key is encrypted, provide the encryption key with `--consensus.secret`.
 
 Once your node is up, it may not start syncing immediately. This is because your node might not be part of the active set. In most cases, your validator will enter the active set in under 6 hours after the on-chain addition of the validator identity.
 
@@ -127,6 +138,7 @@ Once your node is up, it may not start syncing immediately. This is because your
 | `--telemetry-url <URL>` | Unified metrics and logs export. See [Telemetry endpoint](#telemetry-endpoint) below for details. **We ask all validators to configure this so we can support troubleshooting.** |
 | `--telemetry-metrics-interval <DURATION>` | Interval for pushing metrics (default: `10s`). |
 | `--consensus.datadir <PATH>` | Store consensus data on a separate volume (e.g., AWS EBS) while keeping execution state on high-performance local disks. Migrate by copying `<datadir>/consensus` to the new location. |
+| `--consensus.secret <PATH>` | Read the encrypted signing-key secret from a FIFO, process-substitution path, or regular file. Prefer FIFO or process substitution so the secret is streamed just in time and kept out of the process environment. |
 
 ### Telemetry endpoint