dokugent keygen¶

Generates a new Ed25519 keypair for signing agent specs. Keys are stored securely and include a fingerprint metadata file.

What It Does¶

Prompts for an agent or key name
Generates a keypair using Ed25519 algorithm
Saves .pem files and owner.json in .dokugent/keys/owners/<name>/latest/
Prevents overwrite if key with same name exists

Behavior Overview¶

Prompt¶

📛 Dokugent Keygen: Create a Signing Identity?

If left blank, defaults to "<ownerName>".

Key Files Generated¶

Each key is saved under:

.dokugent/keys/owners/<name>/
├── latest → <timestamped-folder>/
    ├── <name>.private.pem     # Private signing key
    ├── <name>.public.pem      # Public verification key
    ├── owner.json             # Metadata describing the *signing identity* (see note below)

Multiple keys can exist side-by-side:

.dokugent/keys/owners/
├── alice/
│   ├── latest → alice@2025-05-28_14-02-00/
│   └── alice@2025-05-28_14-02-00/
│       ├── alice.private.pem
│       ├── alice.public.pem
│       └── owner.json
├── bob/
│   ├── latest → bob@2025-05-27_10-45-12/
│   └── bob@2025-05-27_10-45-12/
│       ├── bob.private.pem
│       ├── bob.public.pem
│       └── owner.json

owner.json Example¶

{
  "signerName": "alice",
  "email": "alice@example.com",
  "organization": "dokugent",
  "trustLevel": "admin",
  "createdAt": "2025-05-28T14:02:00.000Z",
  "publicKey": "-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----",
  "fingerprint": "3038aeab97e9c07020f856d607276cfc124b38c9f6ad52c712320e6d51c8bd8f"
}

⚠️ Note: The keygen metadata file (owner.json) refers to the signing identity (signer), not the content owner. Ownership is declared separately in the Owner block.

Prevents Overwrites¶

If a key with the given name already exists, the command aborts:

⚠️ Key files already exist for 'agent'.

❌ Please choose a different name.

Cross-Platform Notes¶

Dokugent keygen works across macOS, Linux, and Windows. No setup rituals. No fuss. It just works—like it should.

Example CLI Flow¶

dokugent keygen

🔐 Keypair generated for "alice":
  - Public:   .dokugent/keys/owners/alice/latest/alice.public.pem
  - Private:  .dokugent/keys/owners/alice/latest/alice.private.pem
  - Metadata: .dokugent/keys/owners/alice/latest/owner.json