Vestauth Web-Bot-Auth Framework

Vestauth replaces shared secrets (like API keys or bearer tokens) with public/private key cryptography based on open standards.

The Workflow:

1. Key Generation: An agent generates a public/private keypair.
2. Signing: The agent signs each HTTP request using its private key.
3. Verification: The tool (the receiver) verifies the signature using the agent's public key.

Standards Compliance:

• RFC 9421: Defines how requests are cryptographically signed and verified.
• Web-Bot-Auth Draft: Defines headers and authentication architecture for autonomous agents.

This approach provides per-request identity proof, strong attribution, and stateless verification without requiring shared secrets or browser sessions.

To avoid manual key exchange and keep HTTP requests small, Vestauth uses a .well-known discovery model.

Agents host their public keys in a standardized directory. This approach provides:

• Efficient requests: Tools can fetch and cache public keys once, rather than receiving large key material in every request.
• Key rotation: Agents can rotate signing keys without changing their identity; tools simply refresh the keys from the discovery endpoint.
• Multi-key support: Agents can publish multiple active keys (e.g., for staged rollouts) using the standard HTTP Message Signatures directory format.
• Standards alignment: Follows patterns used in OAuth/OpenID Connect and Web identity federation.

Vestauth mitigates replay attacks by leveraging built-in mechanisms of the HTTP Message Signatures standard. Each signed request includes:

• created timestamp: Limits the age of the signature.
• expires timestamp: Defines a short validity window.
• nonce value: Ensures every request is unique.

To prevent reuse, tools should verify that the signature is within the allowed time window, that the nonce has not been used previously, and that the signature matches the request. Tools may optionally store used nonce values for additional protection.

To prevent Server-Side Request Forgery (SSRF) during public key discovery, Vestauth restricts discovery to trusted domains.

By default, discovery is only allowed for endpoints within the controlled namespace:

*.api.vestauth.com

Tools convert the agent identity into a fixed .well-known endpoint within this trusted domain, ensuring they never fetch attacker-supplied URLs or internal network addresses.

Configuring Custom Trusted Domains

Organizations can host their own discovery infrastructure or support private agents by configuring the TOOL_FQDN_REGEX environment variable. Only discovery endpoints matching this regex will be fetched.

Example configuration for multiple internal domains:

TOOL_FQDN_REGEX=".*\\.agents\\.vestauth\\.com|.*\\.agents\\.example\\.internal"

You can install the vestauth CLI globally via npm, or use a shell script for quick installation. There are also manual installation methods for GitHub releases and Windows.

npm i -g vestauth

Or using curl:

curl -sfS https://vestauth.sh | sh

While Vestauth is primarily a client-side and verification library, you can host your own server by setting up a database and running migrations. Use the vestauth server CLI commands to manage the lifecycle:

1. Create the database
2. Run migrations
3. Start the server

$ vestauth server db:create
$ vestauth server db:migrate
$ vestauth server start

The vestauth agent curl command is a drop-in wrapper for curl that automatically signs requests using the agent's identity. This allows agents to interact with authenticated tools (like SFS, SAM, or AS2) by injecting valid signed headers according to the web-bot-auth draft.

To inspect the signed headers being sent, use the primitives headers command.

# Call an authenticated API
vestauth agent curl https://api.vestauth.com/whoami

# Inspect the signed headers
vestauth primitives headers GET https://api.vestauth.com/whoami --pp

To give an agent a cryptographic identity, navigate to your agent's directory and run vestauth agent init. This creates a .env file containing the agent's unique identifier (AGENT_UID) and its public/private JWKs (JSON Web Keys) based on the Ed25519 curve. This identity is used to sign HTTP requests.

$ mkdir your-agent
$ cd your-agent
$ vestauth agent init

The Vestauth server is configured using environment variables in a .env file.

Required/Common Keys:

• PORT: The port the server listens on (default 3000).
• HOSTNAME: The base URL of your server (e.g., vestauth.yoursite.com).
• DATABASE_URL: The connection string for your PostgreSQL database.

Important Production Note: You must configure a wildcard DNS record for *.${HOSTNAME} (e.g., *.vestauth.yoursite.com) to support .well-known discovery required by the web-bot-auth spec.

PORT="3000"
HOSTNAME="http://localhost:3000"
DATABASE_URL="postgres://localhost/vestauth_production"

Agent keys are generated locally and should be stored in the agent's environment configuration (e.g., a .env file).

Key roles:

• AGENT_PRIVATE_JWK: Used to sign requests. Must never be shared.
• AGENT_PUBLIC_JWK: Safe to publish. Used by tools for verification.

Use the primitives.verify() method to verify and authenticate a signed HTTP request using a specific public JWK.

// Verifies and authenticates a signed http request
await vestauth.primitives.verify(httpMethod, url, headers, publicJwk)

You can protect your own API endpoints by using the vestauth.tool.verify method. This method validates the HTTP request signature and returns the agent's identity if the signature is valid.

const vestauth = require('vestauth')

app.post('/whoami', async (req, res) => {
  try {
    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
    const agent = await vestauth.tool.verify(req.method, url, req.headers)

    res.json(agent)
  } catch (err) {
    res.status(401).json({ code: 401, error: { message: err.message }})
  }
})