==========================
Keybase GPG Key Management
==========================


.. contents::

Use `Keybase <https://keybase.io>`_ as a portable store for your GPG private key. On any new machine,
pull the key from Keybase to provision GPG, and ``nimvault`` works immediately.

.. image:: ../images/keybase_flow.svg

Why Keybase
-----------

GPG private keys are the single point of failure for any vault system. Without
the private key, sealed blobs are unrecoverable. Keybase solves the
distribution problem: your key is stored encrypted on Keybase's servers, tied
to your identity, and retrievable on any machine where you can authenticate.

This avoids:

- Manual ``gpg --export-secret-keys`` / ``gpg --import`` over USB or SSH

- Storing private keys in dotfile repos (even encrypted, this is fragile)

- Losing access when a machine dies

One-time setup (existing key)
-----------------------------

If you already have a GPG key (as is typical when you already use ``nimvault``),
push it to Keybase:

.. code:: bash

    # List your GPG keys to find the fingerprint
    gpg --list-keys --keyid-format long

    # Push to Keybase (imports the secret half into Keybase's keyring)
    keybase pgp select --import

Keybase shows your key fingerprint and asks for confirmation. After this, the
key is stored in Keybase and tied to your identity proofs.

To verify the push worked:

.. code:: bash

    keybase pgp list

If you need to update the key after adding UIDs or extending expiry:

.. code:: bash

    keybase pgp update

One-time setup (new key)
------------------------

Generate a fresh key if you do not have one:

.. code:: bash

    gpg --full-generate-key
    # Choose: RSA 4096, no expiry (or long expiry), your email

Then push to Keybase with ``keybase pgp select --import`` as above.

Alternatively, generate the key directly inside Keybase:

.. code:: bash

    keybase pgp gen
    # This creates the key in Keybase AND imports it into local GPG

Provisioning a new machine
--------------------------

On the new machine, install GPG and Keybase, then:

.. code:: bash

    # 1. Authenticate with Keybase
    keybase login

    # 2. Export the secret key from Keybase into local GPG
    keybase pgp export --secret | gpg --import

    # 3. Also export the public half
    keybase pgp export | gpg --import

    # 4. Set trust level to ultimate (required for encryption without prompts)
    gpg --edit-key YOUR_KEY_FINGERPRINT
    # At the gpg> prompt: trust -> 5 (ultimate) -> quit

Replace ``YOUR_KEY_FINGERPRINT`` with the full fingerprint shown by
``keybase pgp list``, e.g. ``74B1F67D8E43A94A755407689CCCE36402CB49A6``.

After this, ``nimvault unseal`` works immediately because GPG has the private key.

Complete workflow
-----------------

A typical cross-machine workflow combining Keybase and nimvault:

.. code:: bash

    # Machine A: add secrets and push
    cd ~/dotfiles
    nimvault add ~/.config/secret/tokens.json
    nimvault seal
    git add .vault/ && git commit -m "vault: add tokens"
    git push

    # Machine B: provision GPG via Keybase and pull secrets
    keybase login
    keybase pgp export --secret | gpg --import
    keybase pgp export | gpg --import
    gpg --edit-key 74B1F67D8E43A94A  # trust -> 5 -> quit

    cd ~/dotfiles
    git pull
    nimvault unseal
    # ~/.config/secret/tokens.json is restored

Verifying the setup
-------------------

After provisioning, verify everything works:

.. code:: bash

    # GPG key is present with secret material
    gpg --list-secret-keys --keyid-format long
    # Should show your key with [ultimate] trust

    # nimvault can read the manifest
    nimvault list

    # Encrypted blobs can be decrypted
    nimvault status
    # All entries should show [in-sync] or [missing] (if not yet unsealed)

Security notes
--------------

- Keybase encrypts your secret key with your Keybase passphrase before storing it.
  Choose a strong passphrase.

- The ``keybase pgp export --secret`` command may prompt for your Keybase
  passphrase. Use ``--unencrypted`` only if piping directly into ``gpg --import``
  in a single command.

- On shared machines, remove the key after use: ``gpg --delete-secret-and-public-key YOUR_KEY_ID``.

- Keybase identity proofs (Twitter, GitHub, DNS) let others verify that the
  public key belongs to you, but for nimvault the important part is private key
  portability.