Primitives API

Overview

The Primitives API provides low-level cryptographic functions for generating keypairs, creating signatures, and verifying signed requests. Unlike the Agent API, primitives do not read from environment variables and require all parameters to be explicitly provided.

const vestauth = require('vestauth')

// Generate keypair
const kp = vestauth.primitives.keypair()

// Generate headers
const headers = await vestauth.primitives.headers(
  'GET',
  'https://api.example.com/data',
  'agent-123',
  JSON.stringify(kp.privateJwk)
)

// Verify request
const result = await vestauth.primitives.verify(
  'GET',
  'https://api.example.com/data',
  headers,
  kp.publicJwk
)

primitives.keypair()

Generates an Ed25519 keypair for signing and verification. If an existing private key is provided, it is reused and the public key is derived.

Signature

primitives.keypair(
  existingPrivateJwk?: string,
  prefix?: string
): Keypair

Parameters

string

An existing private JWK as JSON string. If provided, the keypair is derived from this key instead of generating a new one.

string

default:"agent"

Prefix for the key (currently not used in key generation but reserved for future use)

Returns

PublicJwk

required

The public key in JWK format containing:

kty: Always "OKP" (Octet Key Pair)
crv: Always "Ed25519"
x: Base64url-encoded public key
kid: Key ID (thumbprint of the public key)

PrivateJwk

required

The private key in JWK format containing all public key fields plus:

d: Base64url-encoded private key material

Example: Generate New Keypair

const vestauth = require('vestauth')

const kp = vestauth.primitives.keypair()

console.log('Public key:', kp.publicJwk)
// {
//   kty: 'OKP',
//   crv: 'Ed25519',
//   x: 'QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo',
//   kid: 'ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc'
// }

console.log('Private key:', kp.privateJwk)
// {
//   kty: 'OKP',
//   crv: 'Ed25519',
//   d: 'RTyREuKAEfIMMs2ejwaKtFefZxt14HmsRR0rFj4U5iM',
//   x: 'QjutZ3_tt2jRD_XSOq4EFCDivnwEzKIrQB2yReddsNo',
//   kid: 'ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc'
// }

Example: Reuse Existing Private Key

const existingPrivateJwk = JSON.stringify({
  crv: 'Ed25519',
  d: 'eScKeQcawvvRiBuA_-gWaAP7PZ3UUGPqJv7jks5tFVI',
  x: 'MYf21IkWEi6dXOtzUdbll3SMCaFiSFi4KgqktFZinCE',
  kty: 'OKP'
})

const kp = vestauth.primitives.keypair(existingPrivateJwk)

// Returns the same keypair with computed kid
console.log(kp.privateJwk.kid) // Computed thumbprint

The kid (Key ID) is automatically computed as the JWK thumbprint of the public key, ensuring consistent identification across key usage.

primitives.headers()

Generates RFC 9421 HTTP Message Signature headers using explicit credentials.

Signature

primitives.headers(
  httpMethod: HttpMethod,
  uri: string,
  uid: string,
  privateJwk: string,
  tag?: string,
  nonce?: string | null
): Promise<SignatureHeaders>

Parameters

string

required

The HTTP method (e.g., GET, POST, PUT, DELETE)

string

required

The full request URI including scheme, host, and path

string

required

The agent UID (e.g., agent-4b94ccd425e939fac5016b6b)

string

required

The private JWK as JSON string

string

default:"web-bot-auth"

Signature tag for the request

string

Custom nonce value. If not provided, a random nonce is generated.

Returns

string

required

The signature header value

string

required

The signature input parameters

string

required

The agent discovery URL

Example

const vestauth = require('vestauth')

// Generate keypair
const kp = vestauth.primitives.keypair()

// Create signature headers
const headers = await vestauth.primitives.headers(
  'POST',
  'https://api.example.com/data',
  'agent-abc123',
  JSON.stringify(kp.privateJwk)
)

console.log(headers)
// {
//   Signature: 'sig1=:K7z3Nozcq1z5zfJhrd540DWYbjyQ1kR/S7ZDcMXE5gVhxe...==:',
//   'Signature-Input': 'sig1=("@authority");created=1770263541;keyid="_4GFBGmXKinLBoh3-GJ...";alg="ed25519";expires=1770263841;nonce="0eu7hVMVFm61lQvIry...";tag="web-bot-auth"',
//   'Signature-Agent': 'sig1="https://agent-abc123.api.vestauth.com"'
// }

Custom Tag and Nonce

const headers = await vestauth.primitives.headers(
  'GET',
  'https://api.example.com/data',
  'agent-xyz',
  JSON.stringify(privateJwk),
  'custom-tag',
  'my-custom-nonce-value'
)

The uid must match the agent identity registered with the Vestauth server, or verification will fail.

primitives.verify()

Verifies a signed HTTP request using an explicit public key or by fetching the key from the agent’s discovery endpoint.

Signature

primitives.verify(
  httpMethod: HttpMethod,
  uri: string,
  headers?: HeaderBag,
  publicJwk?: PublicJwk
): Promise<VerifyResult>

Parameters

string

required

The HTTP method of the request being verified

string

required

The full request URI that was signed

HeaderBag

The request headers containing:

Signature
Signature-Input
Signature-Agent

PublicJwk

The public key to verify against. If not provided, Vestauth will attempt to resolve it via the Signature-Agent discovery endpoint.

Returns

string

The agent UID (if Signature-Agent was provided)

string

The key ID used for signing

PublicJwk

The public key used for verification

string

The discovery URL (if key was fetched remotely)

Example: Verify with Explicit Public Key

const vestauth = require('vestauth')

// Generate keypair
const kp = vestauth.primitives.keypair()

// Create signed headers
const headers = await vestauth.primitives.headers(
  'GET',
  'https://api.example.com/test',
  'agent-test',
  JSON.stringify(kp.privateJwk)
)

// Verify using the public key
const result = await vestauth.primitives.verify(
  'GET',
  'https://api.example.com/test',
  headers,
  kp.publicJwk
)

console.log('Verification successful:', result)
// {
//   kid: 'ZCa5pijSUCw7QKgBs6nkvBBzbEjTMKYSt6iwCDQdIYc',
//   public_jwk: { ... }
// }

Example: Verify with Discovery

// Verify by fetching public key from Signature-Agent endpoint
const result = await vestauth.primitives.verify(
  'GET',
  'https://api.example.com/test',
  headers
  // No publicJwk provided - will fetch from discovery
)

console.log('Agent UID:', result.uid)
console.log('Discovered from:', result.well_known_url)

Example: Server-Side Verification

const express = require('express')
const vestauth = require('vestauth')

const app = express()

app.post('/verify', async (req, res) => {
  try {
    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
    
    // Verify without providing public key (uses discovery)
    const result = await vestauth.primitives.verify(
      req.method,
      url,
      req.headers
    )
    
    res.json({
      success: true,
      agent: result.uid,
      keyId: result.kid
    })
  } catch (err) {
    res.status(401).json({
      success: false,
      error: err.message
    })
  }
})

Differences from Higher-Level APIs

vs. Agent API

Feature	Agent API	Primitives API
Reads from `.env`	✅ Yes	❌ No
Requires explicit params	❌ Optional	✅ Required
Writes to `.env`	✅ Yes (`init`, `rotate`)	❌ No
Use case	Application code	Custom implementations

vs. Tool API

Feature	Tool API	Primitives API
SSRF protection	✅ Yes	⚠️ Configurable
Domain validation	✅ Automatic	❌ Manual
Use case	Production tools	Testing, custom logic

Type Definitions

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD' | (string & {})

type HeaderValue = string | string[]
type HeaderBag = Record<string, HeaderValue | undefined>

interface PublicJwk {
  kty: 'OKP'
  crv: 'Ed25519'
  x: string
  kid?: string
  [prop: string]: unknown
}

interface PrivateJwk extends PublicJwk {
  d: string
}

interface Keypair {
  publicJwk: PublicJwk
  privateJwk: PrivateJwk
}

interface SignatureHeaders {
  Signature: string
  'Signature-Input': string
  'Signature-Agent': string
}

interface VerifyResult {
  uid?: string
  kid?: string
  public_jwk?: PublicJwk
  well_known_url?: string
}

Testing and Development

The Primitives API is ideal for testing authentication flows:

const vestauth = require('vestauth')
const assert = require('assert')

// Test signature generation and verification
async function testSignatureFlow() {
  // 1. Generate test keypair
  const kp = vestauth.primitives.keypair()
  
  // 2. Create signed headers
  const headers = await vestauth.primitives.headers(
    'GET',
    'https://api.test.com/endpoint',
    'agent-test-123',
    JSON.stringify(kp.privateJwk)
  )
  
  // 3. Verify the signature
  const result = await vestauth.primitives.verify(
    'GET',
    'https://api.test.com/endpoint',
    headers,
    kp.publicJwk
  )
  
  // 4. Assertions
  assert.strictEqual(result.kid, kp.publicJwk.kid)
  assert.deepStrictEqual(result.public_jwk, kp.publicJwk)
  
  console.log('✓ Signature test passed')
}

testSignatureFlow().catch(console.error)

Advanced: Custom Discovery

You can implement custom key discovery logic using primitives:

const vestauth = require('vestauth')

// Custom key storage
const keyStore = new Map()

// Store agent's public key
function registerAgent(uid, publicJwk) {
  keyStore.set(uid, publicJwk)
}

// Verify with custom key lookup
async function verifyWithCustomDiscovery(httpMethod, uri, headers) {
  // Parse Signature-Agent to get UID
  const signatureAgent = headers['Signature-Agent'] || headers['signature-agent']
  const uidMatch = signatureAgent.match(/agent-[a-f0-9]+/)
  const uid = uidMatch?.[0]
  
  // Look up public key from custom store
  const publicJwk = keyStore.get(uid)
  
  if (!publicJwk) {
    throw new Error('Agent not registered')
  }
  
  // Verify with explicit public key
  return vestauth.primitives.verify(httpMethod, uri, headers, publicJwk)
}

// Usage
const kp = vestauth.primitives.keypair()
registerAgent('agent-custom-123', kp.publicJwk)

const headers = await vestauth.primitives.headers(
  'GET',
  'https://api.example.com/test',
  'agent-custom-123',
  JSON.stringify(kp.privateJwk)
)

const result = await verifyWithCustomDiscovery('GET', 'https://api.example.com/test', headers)
console.log('Verified:', result.kid)

Get Started

Core Concepts

CLI Reference

Library Reference

Self-Hosting

Advanced

Resources

Overview

primitives.keypair()

Signature

Parameters

Returns

Example: Generate New Keypair

Example: Reuse Existing Private Key

primitives.headers()

Signature

Parameters

Returns

Example

Custom Tag and Nonce

primitives.verify()

Signature

Parameters

Returns

Example: Verify with Explicit Public Key

Example: Verify with Discovery

Example: Server-Side Verification

Differences from Higher-Level APIs

vs. Agent API

vs. Tool API

Type Definitions

Testing and Development

Advanced: Custom Discovery

See Also

​Overview

​primitives.keypair()

​Signature

​Parameters

​Returns

​Example: Generate New Keypair

​Example: Reuse Existing Private Key

​primitives.headers()

​Signature

​Parameters

​Returns

​Example

​Custom Tag and Nonce

​primitives.verify()

​Signature

​Parameters

​Returns

​Example: Verify with Explicit Public Key

​Example: Verify with Discovery

​Example: Server-Side Verification

​Differences from Higher-Level APIs

​vs. Agent API

​vs. Tool API

​Type Definitions

​Testing and Development

​Advanced: Custom Discovery

​See Also

Overview

primitives.keypair()

Signature

Parameters

Returns

Example: Generate New Keypair

Example: Reuse Existing Private Key

primitives.headers()

Signature

Parameters

Returns

Example

Custom Tag and Nonce

primitives.verify()

Signature

Parameters

Returns

Example: Verify with Explicit Public Key

Example: Verify with Discovery

Example: Server-Side Verification

Differences from Higher-Level APIs

vs. Agent API

vs. Tool API

Type Definitions

Testing and Development

Advanced: Custom Discovery

See Also