git-bug User Management Design Document

Problem Statement

Currently, git-bug requires creating a new identity on every machine. There is no mechanism to:

1. View remote identities (those that exist on a remote but not locally).
2. Adopt a remote identity, asserting ownership by proving possession of the corresponding private key in the local keyring.
3. Adopt from an arbitrary repository — adopt an identity from a different project's git-bug repository by URL, without requiring a configured remote.
4. Generate a key pair during identity creation (the GenerateKey() function in entities/identity/key.go is not exposed via CLI).
5. Import an externally-created PGP private key (e.g. a sub-key of an existing master key) into a git-bug identity.
6. Delegate signing authority from a human identity to an agent identity via PGP sub-keys, with cryptographically verifiable binding.

This document details the changes needed to the CLI commands in commands/user/ and the key infrastructure in entities/identity/key.go to support these workflows.

Key Portability Model

Private keys are stored in the git-bug keyring, which defaults to ~/.config/git-bug/keyring/ on Linux (an encrypted file-backend provided by github.com/99designs/keyring). git-bug does not provide commands to export private keys from the keyring. Instead, users are expected to copy the keyring files between machines directly, or manage them with a dotfile manager such as chezmoi. This keeps key material handling entirely outside of git-bug and avoids git-bug becoming a vector for accidental key exposure.

Each keyring item is a separate file within the keyring directory, keyed by the key's fingerprint. This file-per-key layout is what makes external management (chezmoi, rsync, etc.) practical — individual key files can be selectively copied to specific machines without moving the entire keyring.

Human Users

Workflows

Workflow A — Portable Identity (same key, multiple machines)

1. On Machine A: git bug user new --generate-key — creates an identity with a key pair; the private key is stored in the local keyring.
2. Copy ~/.config/git-bug/keyring/ from Machine A to Machine B (directly, or via chezmoi, rsync, etc.).
3. On Machine B: git bug user --remote — list remote identities to find the target identity's ID.
4. On Machine B: git bug user adopt --remote <USER_ID> — adopts the remote identity after verifying that the matching private key exists in the local keyring.

Workflow B — Adopt Identity from a Different Project

1. User has an identity in project A and wants to use the same identity in project B.
2. Copy the keyring from Machine A to Machine B (if not already present).
3. On Machine B (in project B's repo): git bug user --url https://github.com/org/project-a.git — list identities from project A's repository to find the target ID.
4. On Machine B: git bug user adopt --url https://github.com/org/project-a.git <USER_ID> — fetches and adopts the identity after verifying the private key is in the local keyring.

Workflow C — External PGP Sub-Key

1. User generates a PGP sub-key externally (e.g. via gpg --add-key).
2. git bug user key import USER_ID --file subkey.asc — imports the sub-key's private key into the git-bug keyring for the specified identity and (if needed) adds the corresponding public key to that identity.

Command Changes

New: --remote and --url flags on git bug user (list identities) — commands/user/user.go

Add a new --remote boolean flag. When set, the command fetches identity refs from all configured remotes into an in-memory store and lists them instead of local identities.

Add a new --url string flag. When set, the command fetches identity refs from the specified git URL into an in-memory store and lists them. This allows browsing identities from any git-bug repository without configuring a remote. --url and --remote are mutually exclusive — --url targets a single explicit URL, while --remote targets all configured remotes.

• Display which remote (or URL) each identity comes from.
• Display a marker (e.g. [local]) next to identities that also exist locally, so the user can see which ones are candidates for adoption.

New: --remote and --url flags on git bug user show [USER_ID] — commands/user/user_show.go

Add a new --remote boolean flag. When set, resolve the identity from remote refs (via identity.ReadRemote) instead of the local cache.

Add a new --url string flag. When set, fetch identity refs from the specified git URL and resolve the identity from that store. Mutually exclusive with --remote.

Additional changes (regardless of --remote):

• Add a "keys" entry to the --field flag's valid values. When selected, list the public key fingerprints associated with the identity.
• In the default (no --field) output, add a Keys: section showing key fingerprints and whether the corresponding private key is available in the local keyring.

git bug user new — commands/user/user_new.go

Add a new --generate-key (-k) boolean flag. When set:

1. Generate a key pair via identity.GenerateKey().
2. Pass the key to the identity at creation time (the NewRaw call on line 70 currently passes nil for keys — pass []*identity.Key{key} instead).
3. After the identity is committed, store the private key in the keyring via key.StorePrivate(repo).

Implementation sketch (in runUserNew):

var keys []*identity.Key
if opts.generateKey {
    key := identity.GenerateKey()
    keys = append(keys, key)
    defer func() {
        if err == nil {
            _ = key.StorePrivate(env.Backend)
        }
    }()
}
id, err := env.Backend.Identities().NewRaw(opts.name, opts.email, "", opts.avatarURL, keys, nil)

New: --remote and --url flags on git bug user adopt USER_ID — commands/user/user_adopt.go

Add a new --remote boolean flag and a new --url string flag. These are mutually exclusive. When either is set, the adoption flow changes to:

1. Fetch identity refs from the source:
   • --remote: from all configured remotes.
   • --url <git-url>: from the specified git URL. This allows adopting an identity from any git-bug repository without configuring a remote — e.g. adopting your identity from a different project.
2. Find the matching remote identity by prefix.
3. Require that the identity has at least one key whose corresponding private key is present in the local keyring. For each key in the identity's key set, attempt key.EnsurePrivateKey(repo). If no key yields a private key, abort with an error:

   Error: cannot adopt remote identity <ID>: no matching private key found in the local keyring.
   Copy the keyring from a machine that has the private key (e.g. ~/.config/git-bug/keyring/) and try again.
   

4. Merge/copy the remote identity ref into the local store (via repo.CopyRef to create a local ref from the remote ref). Copy referenced commit object, tree and blobs if using --url, otherwise fetch one remote identity.
5. Set the newly-local identity as the user identity via env.Backend.SetUserIdentity.

When neither --remote nor --url is set, keep the existing behavior: resolve from the local cache and adopt directly (no key check required, since local identities may predate key support).

New: git bug user key subcommand tree

Add a new subcommand group under git bug user:

git bug user key USER_ID            — List keys for the current user identity
git bug user key generate USER_ID   — Generate a new key pair and add it to the current identity
git bug user key import USER_ID     — Import a private key into the local keyring for the given identity
git bug user key revoke USERID FINGERPRINT — Revoke a key by fingerprint

git bug user key USER_ID (list)

• Lists all public key fingerprints for the current (or specified) identity.
• Shows whether each key's private counterpart is available in the local keyring.

git bug user key generate USER_ID

• Calls identity.GenerateKey().
• Mutates the current identity to add the new public key (via Identity.Mutate()).
• Stores the private key in the keyring via key.StorePrivate(repo).
• Commits the identity.

git bug user key import USER_ID

Arguments:

• USER_ID — required human ID or full ID of the target identity (as shown by git bug user or git bug user show).

Flags:

• --file / -i — input file path containing an armored PGP private key (required).

Behavior:

1. Resolve the identity by the provided USER_ID prefix (same resolution logic as git bug user show).
2. Read and decode the armored private key from the file.
3. Extract the corresponding public key from the private key.
4. Check whether the resolved identity already has a matching public key in its key set. If not, mutate the identity to add it (with user confirmation in interactive mode).
5. Store the private key in the local keyring via key.StorePrivate(repo).

git bug user key revoke USERID FINGERPRINT

Arguments:

• USER_ID — required human ID or full ID of the target identity (as shown by git bug user or git bug user show).
• FINGERPRINT — the fingerprint of the key to revoke (as shown by git bug user key).

Behavior:

1. Resolve the current user identity.
2. Find the key matching the given fingerprint in the identity's key set.
3. Create a new identity version with the key removed from the active key set. The key remains present in prior identity versions for historical verification — ValidKeysAtTime() returns keys based on the lamport time of each version, so signatures made before the revocation version continue to verify.
4. Optionally remove the private key from the local keyring (with confirmation in interactive mode).
5. Commit the identity.

For delegated sub-keys (Entity-based keys), this command adds a PGP sub-key revocation signature to the Entity (via entity.RevokeSubkey()) rather than removing the sub-key, preserving the cryptographic audit trail. See the Delegated Users — Revocation section for details.

Changes to entities/identity/key.go

Export currently-private methods

The following methods are currently unexported and need to be exported for use by the command layer:

Export error sentinel

Export errNoPrivateKey as ErrNoPrivateKey so command-layer code can check for it:

var ErrNoPrivateKey = fmt.Errorf("no private key")

New functions

KeyFromPrivateArmored(armoredData []byte) (*Key, error)

Parse an armored PGP private key block and return a Key with both private and public fields populated. This supports the key import workflow.

func KeyFromPrivateArmored(armoredData []byte) (*Key, error) {
    block, err := armor.Decode(bytes.NewReader(armoredData))
    if err != nil {
        return nil, fmt.Errorf("no armored data found: %w", err)
    }
    if block.Type != openpgp.PrivateKeyType {
        return nil, fmt.Errorf("expected private key block, got %s", block.Type)
    }
    p, err := packet.Read(block.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read private key packet: %w", err)
    }
    priv, ok := p.(*packet.PrivateKey)
    if !ok {
        return nil, fmt.Errorf("not a private key packet")
    }
    priv.CreationTime = time.Time{}
    return &Key{
        public:  &priv.PublicKey,
        private: priv,
    }, nil
}

(k *Key) Fingerprint() string

Return a human-readable fingerprint for display in CLI output.

func (k *Key) Fingerprint() string {
    return fmt.Sprintf("%X", k.public.Fingerprint)
}

(k *Key) KeyIdString() string

Expose the public key's ID string (currently only used internally via k.public.KeyIdString()).

func (k *Key) KeyIdString() string {
    return k.public.KeyIdString()
}

(k *Key) HasPrivate() bool

Check whether the key has a private component loaded in memory.

func (k *Key) HasPrivate() bool {
    return k.private != nil
}

(k *Key) MatchesPublic(other *Key) bool

Compare two keys by their public key ID. Used during import to verify the imported private key matches a public key in the identity.

func (k *Key) MatchesPublic(other *Key) bool {
    return k.public.KeyId == other.public.KeyId
}

Changes to entities/identity/identity.go

FindKeyByFingerprint

Add a helper to find a key in the identity's current key set by fingerprint:

func (i *Identity) FindKeyByFingerprint(fingerprint string) *Key {
    for _, key := range i.Keys() {
        if key.Fingerprint() == fingerprint {
            return key
        }
    }
    return nil
}

AddKey

Convenience method that wraps Mutate to append a key:

func (i *Identity) AddKey(repo repository.RepoClock, key *Key) error {
    return i.Mutate(repo, func(orig *Mutator) {
        orig.Keys = append(orig.Keys, key)
    })
}

RevokeKey

Remove a key from the active key set by creating a new identity version without it. The key remains in prior versions, so ValidKeysAtTime() continues to return it for lamport times before the revocation:

func (i *Identity) RevokeKey(repo repository.RepoClock, fingerprint string) error {
    return i.Mutate(repo, func(orig *Mutator) {
        filtered := make([]*Key, 0, len(orig.Keys))
        for _, k := range orig.Keys {
            if k.Fingerprint() != fingerprint {
                filtered = append(filtered, k)
            }
        }
        orig.Keys = filtered
    })
}

Interaction between revocation and ValidKeysAtTime

ValidKeysAtTime() (in identity.go) already walks identity versions in order and returns the key set from the latest version whose lamport time is ≤ the queried time. This means:

• Signatures made before revocation: the queried lamport time falls within a version that still includes the key → verification succeeds.
• Signatures made after revocation: the queried lamport time falls within the version where the key was removed → the key is not in the returned set → verification fails.

No changes to ValidKeysAtTime are needed — the existing version-walk semantics naturally support time-scoped revocation.

File Layout for New Commands

commands/user/
├── user.go              (modified — add --remote flag, key subcommand)
├── user_adopt.go        (modified — add --remote flag, require private key)
├── user_new.go          (modified — add --generate-key flag)
├── user_show.go         (modified — add --remote flag, keys display)
├── user_key.go          (new — "git bug user key" parent + list)
├── user_key_generate.go (new — "git bug user key generate")
├── user_key_import.go   (new — "git bug user key import")
├── user_key_revoke.go   (new — "git bug user key revoke")
├── remote.go            (existing — shared remote-fetch helpers)
└── remote_test.go       (existing)

Security Considerations

• No key export from git-bug. Private keys never leave the keyring through git-bug commands. Users manage keyring portability out of band (direct copy, chezmoi, etc.).
• Remote adoption requires private key proof. The user adopt --remote command refuses to proceed unless a matching private key is already present in the local keyring, preventing unauthorized identity claims.
• Key import validates structure. The key import command validates that the imported file is a well-formed armored PGP private key and that its public component matches (or can be added to) the identity before storing anything.
• The existing keyring uses a hardcoded password ("git-bug" in repository/keyring.go). This is a known limitation noted in the existing code. Improving keyring security is out of scope for this change.

Testing Strategy

• entities/identity/key_test.go: Add tests for KeyFromPrivateArmored, Fingerprint, MatchesPublic, HasPrivate, and round-trip generate/store/load.
• commands/user/: Add integration tests for:
  • user new --generate-key — verify identity is created with a key and private key is in keyring.
  • user key generate — verify key is added to existing identity.
  • user key import — verify imported key is stored and matched.
  • user key revoke — verify key is removed from active set, prior signatures still verify, post-revocation signatures fail.
  • user adopt --remote — verify adoption succeeds when private key is present, and fails with a clear error when it is not.
  • user adopt --url — verify adoption from an arbitrary git URL works, including cross-project adoption.
  • user --remote, user --url, user show --remote, user show --url — verify remote/URL identity listing/display.
• commands/user/remote_test.go: Extend existing remote tests to cover the adoption flow with and without private keys.
• Use repository.NewMockRepoKeyring() for all keyring-dependent tests.

Summary of Changes

Delegated Users

Overview

A human identity can delegate signing authority to an agent identity (e.g. a CI bot, an AI coding agent) by creating a PGP signing sub-key bound to the human's primary key. The agent signs operations with the sub-key; verifiers check the signature against the human's full public key (which includes the sub-key and its binding signature), establishing a cryptographic chain of trust from agent back to human.

Delegation Workflow

1. Human creates a signing sub-key for the agent, using identity.CreateSigningSubkey() in key.go (not exposed via CLI — this is a library operation invoked programmatically or by future tooling).
2. The human's identity is mutated to include the updated public key Entity (primary key + sub-key + binding signature). This is committed as a new identity version.
3. The sub-key's private key file is copied from the human's keyring to the agent's keyring (out of band — via chezmoi, rsync, etc.). Only the sub-key file needs to be copied; the human's primary private key stays on the human's machine.
4. The agent's identity is created (or mutated) to include the human's full public key (primary + sub-key + binding signatures) so that verifiers can trace the agent's signatures back to the human.
5. The agent's identity should include metadata referencing the delegating human's identity ID: "delegated-from": "<human-identity-id>". This makes the delegation relationship explicit and queryable.

Keyring Layout for Delegation

The file-per-key keyring model supports delegation naturally:

~/.config/git-bug/keyring/
├── <human-primary-fingerprint>     # human's primary private key (human's machine only)
├── <agent-subkey-fingerprint>      # sub-key private key (copied to agent's machine)
└── ...

On the human's machine, both files are present. On the agent's machine, only the sub-key file is present. The agent does not need (and should not have) the human's primary private key.

Changes to entities/identity/key.go — Entity-Based Key Model

The current Key struct stores bare packet.PublicKey / packet.PrivateKey packets, which cannot represent the primary-to-sub-key binding relationship. Supporting delegation requires moving to a model based on openpgp.Entity, which natively carries primary keys, sub-keys, binding signatures, and revocations.

Rework the Key struct

Replace the internal representation to use *openpgp.Entity as the authoritative data:

type Key struct {
    entity *openpgp.Entity
}

The Entity carries:

• PrimaryKey / PrivateKey — the primary key pair
• Subkeys []openpgp.Subkey — sub-keys with their binding signatures (Subkey.Sig)
• Identities — UID packets with self-signatures

Accessors like Public(), Private(), PGPEntity() are updated to delegate to the internal Entity. PGPEntity() becomes a trivial accessor instead of fabricating a synthetic Entity (which is the current behavior and is incompatible with delegation since it generates new self-signatures requiring the primary private key).

Update public key serialization (JSON / Git)

MarshalJSON must serialize the full public Entity (primary + sub-keys + binding signatures + UIDs) using entity.Serialize(w) into a standard PGP PUBLIC KEY BLOCK. This replaces the current single-packet serialization.

UnmarshalJSON must read back the full Entity using openpgp.ReadKeyRing (after armor decode). Backward compatibility: if the armored block decodes to a lone packet.PublicKey (legacy format), wrap it in a minimal Entity for read-only use (no delegation support for legacy keys).

Update private key serialization (keyring)

Keep the existing one-item-per-key approach, but store each private key (primary and sub-keys) as separate keyring items keyed by fingerprint (not KeyIdString(), which is a 64-bit key ID and risks collisions):

This is a change from the current scheme which uses key.public.KeyIdString() as the keyring item key. Existing keyring items will need migration or dual-lookup during a transition period.

Loading private material works by:

1. Loading the public Entity from the identity version (Git).
2. For each key in the Entity (primary + sub-keys), attempting to load a private key from the keyring by fingerprint.
3. Attaching any found private material to the corresponding entity.PrivateKey or entity.Subkeys[i].PrivateKey.
4. Signing succeeds if any signing-capable private key is present.

New function: CreateSigningSubkey

func (k *Key) CreateSigningSubkey(config *packet.Config) (*Key, error)

Creates a signing sub-key on the Key's Entity using entity.AddSigningSubkey(config). Returns a new Key representing the sub-key (with its private material) for storage in the keyring. The calling code is responsible for:

• Storing the sub-key's private key in the keyring via StorePrivate.
• Committing the updated identity version (which now includes the sub-key's public key and binding signature).

This function is not exposed via CLI. It is a library operation for programmatic use.

Update ensurePrivateKey / SigningKey

ensurePrivateKey must iterate all keys in the Entity (primary + sub-keys) and attempt to load private material by fingerprint. It should succeed if any signing-capable private key is found.

Identity.SigningKey() should prefer a signing-capable sub-key over the primary key (standard OpenPGP practice), falling back to the primary if no sub-key private material is available.

Update Validate and Clone

• Validate() must check that sub-keys have valid binding signatures issued by the primary key, and that signing sub-keys have KeyFlagSign set in their binding signature.
• Clone() must deep-copy the full Entity including sub-keys and binding signatures.

Verification Path

The verification path in entity/dag/operation_pack.go builds an openpgp.EntityList from PGPEntity() calls and passes it to openpgp.CheckDetachedSignature. Since CheckDetachedSignature natively understands sub-keys and binding signatures, no changes are needed to the verification code — as long as PGPEntity() returns a complete Entity with sub-keys, signatures made by sub-keys will verify automatically.

Revocation

Revocation must work for both human primary keys and delegated sub-keys, and must never invalidate signatures made before the revocation. git-bug uses two complementary mechanisms to achieve this:

Mechanism 1 — Identity version history (lamport-scoped)

ValidKeysAtTime() walks identity versions and returns the key set from the latest version whose lamport time is ≤ the queried time. When a key is revoked by publishing a new identity version (with the key removed or marked revoked), signatures made at earlier lamport times still verify because the earlier version's key set is used. This mechanism works identically for human primary keys and delegated sub-keys.

Mechanism 2 — PGP sub-key revocation signatures (Entity-scoped)

For Entity-based keys (delegated sub-keys), revocation also produces a PGP sub-key revocation signature via entity.RevokeSubkey(). This preserves the full cryptographic audit trail within the Entity:

• The sub-key public packet and binding signature remain present in the Entity (so external PGP tooling like gpg --verify can still verify historical signatures).
• The revocation signature marks the sub-key as invalid for new signatures.
• openpgp.CheckDetachedSignature respects revocation signatures when checking the Subkey.Revocations list.

Revoking a human primary key

1. The user runs git bug user key revoke <FINGERPRINT>.
2. A new identity version is created with the key removed from the active key set.
3. The key remains in prior identity versions — ValidKeysAtTime() returns it for lamport times before the revocation.
4. The private key is optionally removed from the local keyring.

Revoking a delegated sub-key

1. The human runs git bug user key revoke <SUBKEY_FINGERPRINT>.
2. A sub-key revocation signature is added to the Entity (via entity.RevokeSubkey()).
3. A new identity version is published containing the updated Entity. The sub-key packet remains present but is marked revoked.
4. The agent's identity should also be updated with the revised public key (including the revocation signature).
5. ValidKeysAtTime() excludes the revoked sub-key from the valid set for lamport times at or after the revocation version.
6. External PGP verifiers (gpg, git verify-commit) also see the revocation and reject new signatures from the sub-key, while still being able to verify historical ones (the sub-key packet and binding signature are preserved).

Backward Compatibility

Summary of Delegated User Changes