Primitives Commands

Low-level cryptographic operations for advanced use cases

Overview

Primitives are low-level commands for cryptographic operations. Use these when you need fine-grained control over keypairs, signatures, and verification without the higher-level abstractions.

Most users should use Agent Commands instead. Primitives are for advanced use cases and library development.

primitives keypair

Generate a new Ed25519 public/private keypair.

vestauth primitives keypair

Output:

{
  "public_jwk": {
    "crv": "Ed25519",
    "x": "QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo",
    "kty": "OKP",
    "kid": "ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc"
  },
  "private_jwk": {
    "crv": "Ed25519",
    "d": "RTyREuKAEfIMMs2ejwaKtFefZxt14HmsRR0rFj4U5iM",
    "x": "QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo",
    "kty": "OKP",
    "kid": "ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc"
  }
}

Options

--private-jwk · string

Use an existing private JWK instead of generating a new one. Useful for deriving the public key from a known private key.

--prefix · string · default: "agent"

UID prefix type: agent, tool, or none.

• agent - Generates UID like agent-4b94ccd425e939fac5016b6b
• tool - Generates UID like tool-4b94ccd425e939fac5016b6b
• none - No prefix, just the hash

--pp · boolean

Pretty-print JSON output.

Alias: --pretty-print

Examples

Generate New Keypair

vestauth primitives keypair --pp

Key Format (JWK)

Vestauth uses JSON Web Key (JWK) format for Ed25519 keys:

Public JWK:

{
  "crv": "Ed25519",        // Curve type
  "x": "BASE64URL",         // Public key bytes
  "kty": "OKP",             // Key type (Octet Key Pair)
  "kid": "KEY_ID"           // Key identifier (SHA-256 hash)
}

Private JWK:

{
  "crv": "Ed25519",
  "d": "BASE64URL",          // Private key bytes (secret!)
  "x": "BASE64URL",          // Public key bytes
  "kty": "OKP",
  "kid": "KEY_ID"
}

Never share the private JWK (d field). This is your secret signing key.

---

primitives headers

Generate HTTP Message Signature headers for a request.

vestauth primitives headers <httpMethod> <uri>

Example:

vestauth primitives headers GET http://example.com --pp

Output:

{
  "Signature": "sig1=:K7z3Nozcq1z5zfJhrd540DWYbjyQ1kR/S7ZDcMXE5gVhxezvG6Rn9BxEvfteiAnBuQhOkvbpGtF83WpQQerGBw==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770263541;keyid=\"_4GFBGmXKinLBoh3-GJZCiLBt-84GP9Fb0iBzmYncUg\";alg=\"ed25519\";expires=1770263841;nonce=\"0eu7hVMVFm61lQvIryKNmZXIbzkkgpVocoKvN0de5QO8Eu5slTxklJAcVLQs0L_UTVtx4f8qJcqYZ21JTeOQww\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-35e4a794a904d227ee2373b6.api.vestauth.com"
}

Arguments

httpMethod · string · required

HTTP method: GET, POST, PUT, DELETE, etc.

uri · string · required

Full URI including scheme and authority (e.g., https://api.example.com/path)

Options

--uid · string

Agent or tool UID. Defaults to AGENT_UID or AGENT_ID environment variable.

If not provided, generates a new random UID.

Alias: --id

--private-jwk · string

Private JWK for signing. Defaults to AGENT_PRIVATE_JWK environment variable.

If not provided, generates a new keypair.

--tag · string · default: "web-bot-auth"

Signature tag value per Web-Bot-Auth draft.

--nonce · string

Custom nonce value. By default, a cryptographically random 64-byte nonce is generated.

--pp · boolean

Pretty-print JSON output.

Alias: --pretty-print

Examples

Basic

vestauth primitives headers GET https://api.example.com/endpoint --pp

Signature Components

Signature Header:

Signature: sig1=:BASE64_SIGNATURE:

The cryptographic signature of the request using Ed25519.

Signature-Input Header:

Signature-Input: sig1=("@authority");created=1770263541;keyid="...";alg="ed25519";expires=1770263841;nonce="...";tag="web-bot-auth"

Contains:

• Covered components: @authority (hostname)
• created - Unix timestamp when signature was created
• keyid - Public key identifier
• alg - Signature algorithm (ed25519)
• expires - Unix timestamp when signature expires (created + 5 minutes)
• nonce - Random value to prevent replay attacks
• tag - Protocol identifier (web-bot-auth)

Signature-Agent Header:

Signature-Agent: sig1=AGENT_UID.HOSTNAME

Identifies the agent and provides the discovery domain.

---

primitives verify

Verify HTTP Message Signature headers using a public key.

vestauth primitives verify <httpMethod> <uri> --signature <sig> --signature-input <input> [--signature-agent <agent>] [--public-jwk <key>]

Example:

vestauth primitives verify GET https://api.vestauth.com/whoami \
  --signature "sig1=:UHqXQbWZmyYW40JRcdCl+NLccLgPmcoirUKwLtdcpEcIgxG2+i+Q2U3yIYeMquseON3fKm29WSL2ntHeRefHBQ==:" \
  --signature-input "sig1=(\"@authority\");created=1770395703;keyid=\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\";alg=\"ed25519\";expires=1770396003;nonce=\"O8JOC1reBofwbpPcdD-MRRCdrtAf4khvJTuhpRI_RiaH_hpU93okLkmPZVFFcUEdYtYfcduaB8Sca54GTd2GXA\";tag=\"web-bot-auth\"" \
  --signature-agent "sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com"

Output:

{"uid":"agent-609a4fd2ebf4e6347108c517", ...}

Arguments

httpMethod · string · required

HTTP method of the request being verified.

uri · string · required

Full URI of the request being verified.

Options

--signature · string · required

Value of the Signature header.

--signature-input · string · required

Value of the Signature-Input header.

--signature-agent · string

Value of the Signature-Agent header.

If provided, fetches the public key from the agent’s .well-known discovery endpoint.

If omitted, you must provide --public-jwk.

--public-jwk · string

Public JWK to verify against. Defaults to AGENT_PUBLIC_JWK environment variable.

Required if --signature-agent is not provided.

--pp · boolean

Pretty-print JSON output.

Alias: --pretty-print

Verification Modes

Mode 1: With Agent Discovery

Provide --signature-agent to fetch the public key automatically:

vestauth primitives verify GET https://api.example.com/endpoint \
  --signature "sig1=:..." \
  --signature-input "sig1=..." \
  --signature-agent "sig1=agent-123.api.vestauth.com"

Mode 2: With Known Public Key

Provide --public-jwk directly:

vestauth primitives verify GET https://api.example.com/endpoint \
  --signature "sig1=:..." \
  --signature-input "sig1=..." \
  --public-jwk '{"crv":"Ed25519","x":"...","kty":"OKP","kid":"..."}'

What Gets Verified

1. Signature Validity: Cryptographic signature matches the request
2. Expiration: Signature has not expired
3. Algorithm: Uses supported algorithm (Ed25519)
4. Key ID: Matches the public key
5. Components: Signed components match the request

Error Codes

Verification fails with specific errors:

• Invalid signature: Signature does not match
• Expired: Current time > expires timestamp
• Invalid key: Public key format is invalid
• Algorithm mismatch: Signature algorithm not supported
• Missing components: Required signature components missing

---

Use Cases

Custom Agent Implementation

Build your own agent in any language:

import subprocess
import json
import requests

# Generate keypair
result = subprocess.run(
    ['vestauth', 'primitives', 'keypair', '--pp'],
    capture_output=True,
    text=True
)
keys = json.loads(result.stdout)

# Generate headers for request
result = subprocess.run([
    'vestauth', 'primitives', 'headers',
    'POST', 'https://api.example.com/endpoint',
    '--uid', 'agent-custom',
    '--private-jwk', json.dumps(keys['private_jwk']),
    '--pp'
], capture_output=True, text=True)

headers = json.loads(result.stdout)

# Make request
response = requests.post(
    'https://api.example.com/endpoint',
    headers=headers,
    json={'data': 'value'}
)

Custom Tool Verification

Verify signatures in any language:

require 'json'
require 'open3'

def verify_agent(method, uri, headers)
  stdout, stderr, status = Open3.capture3(
    'vestauth', 'primitives', 'verify',
    method, uri,
    '--signature', headers['Signature'],
    '--signature-input', headers['Signature-Input'],
    '--signature-agent', headers['Signature-Agent']
  )
  
  if status.success?
    JSON.parse(stdout)
  else
    raise "Verification failed: #{stderr}"
  end
end

Testing Signatures

Test signature generation and verification:

# Generate keypair
KEYS=$(vestauth primitives keypair --pp)
PRIVATE_JWK=$(echo $KEYS | jq -r '.private_jwk')
PUBLIC_JWK=$(echo $KEYS | jq -r '.public_jwk')

# Sign request
HEADERS=$(vestauth primitives headers GET https://api.example.com/test \
  --uid agent-test \
  --private-jwk "$PRIVATE_JWK" \
  --pp)

SIGNATURE=$(echo $HEADERS | jq -r '.Signature')
SIGNATURE_INPUT=$(echo $HEADERS | jq -r '."Signature-Input"')

# Verify signature
vestauth primitives verify GET https://api.example.com/test \
  --signature "$SIGNATURE" \
  --signature-input "$SIGNATURE_INPUT" \
  --public-jwk "$PUBLIC_JWK" \
  --pp

Standards Compliance

Primitives implement these standards:

• RFC 9421 - HTTP Message Signatures
• RFC 8032 - Edwards-Curve Digital Signature Algorithm (EdDSA)
• RFC 7517 - JSON Web Key (JWK)
• Web-Bot-Auth Draft - Agent authentication headers

Related

• Agent Commands - High-level agent operations
• Tool Commands - High-level tool verification
• Library Reference - Programmatic primitives API