vestauth

v0.23.1

Published

18 days ago

web-bot-auth for agents–from the creator of dotenvx

Downloads

2,270

0High
0Medium
0Low

motdotla

motdotenv

vestauth web-bot-auth webbotauth cryptography ai-agent agent-auth rfc9421 http-signatures

web-bot-auth for agents–from the creator of dotenv and dotenvx.

identity (web-bot-auth)
tools!
authentication

💬 Ask ChatGPT: When should I use Vestauth?

Quickstart

Give your agents identities and call tools!

npm i -g vestauth

vestauth agent init
vestauth agent curl https://api.vestauth.com/whoami --pp
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
vestauth agent curl https://sfs.vestauth.com/list
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"[email protected]", "text":"hello from agent"}'

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

curl -L -o vestauth.tar.gz "https://github.com/vestauth/vestauth/releases/latest/download/vestauth-$(uname -s)-$(uname -m).tar.gz"
tar -xzf vestauth.tar.gz
./vestauth agent init

Download the windows executable directly from the releases page.

vestauth-windows-amd64.zip
vestauth-windows-x86_64.zip

(unzip to extract vestauth.exe)

Identity

Give agents cryptographic identities.

$ mkdir your-agent
$ cd your-agent

$ vestauth agent init
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

Your agent's identity lives in a simple .env file.

# .env
AGENT_UID="agent-4b94ccd425e939fac5016b6b"
AGENT_PUBLIC_JWK="{"crv":"Ed25519","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}"
AGENT_PRIVATE_JWK="{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72yiAaQ","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}"

💬 Ask ChatGPT: Are HTTP message signatures more secure than API keys?

Tools

Call tools!

vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
vestauth agent curl https://sfs.vestauth.com/list

First Party

SFS is a simple file system for vestauth agents.
sfs.vestauth.com

# write a file
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'

# delete a file
vestauth agent curl https://sfs.vestauth.com/delete -d '{"filepath":"/hello.md"}'

# list files
vestauth agent curl https://sfs.vestauth.com/list

# read a file
vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'

SAM is a simple way to send email for vestauth agents.
sam.vestauth.com

# send an email
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"[email protected]", "text":"i am agent"}'

GEO returns the current latitude and longitude of a vestauth agent.
geo.vestauth.com

# return latitude and longitude
vestauth agent curl https://geo.vestauth.com/geo

Third Party

AS2 is a simple, agent-friendly secret storage.
as2.dotenvx.com

# set a secret
vestauth agent curl https://as2.dotenvx.com/set -d '{"KEY":"value"}'

# get all secrets
vestauth agent curl "https://as2.dotenvx.com/get"

# get single secret
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY"

# get multiple secrets
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY,TWILIO"

Check if an email address is real before you hit send. Verifies syntax, DNS, MX records, SMTP mailbox existence, and cross-references multiple providers. All in real time, no signup required.
github.com/treadiehq/docle

# verify an email
vestauth agent curl https://docle.co/api/verify -d '{"emails":["[email protected]"]}'

# check your usage
vestauth agent curl https://docle.co/api/agent/usage

Geo IP - coming soon
Send/Receive Email - coming
Send/Receive SMS - coming
Send/Receive Telegram - coming
Send/Receive WhatsApp - coming
Human-in-the-loop - coming
Rotate NPM Tokens - coming
Rotate GitHub Tokens - coming
Working on a tool? Tell us and we'll list it.

Authentication

Build your own tools. Authenticate them with a single line of code – vestauth.tool.verify…

...
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 }})
  }
})
...

…the agents sign HTTP requests with a drop-in curl wrapper.

> SIGNED - 200
$ vestauth agent curl https://api.vestauth.com/whoami
{"uid":"agent-4b94ccd425e939fac5016b6b",...}

vestauth agent curl autosigns curl requests – injecting valid signed headers according to the web-bot-auth draft. You can peek these with the built-in headers primitive.

$ vestauth primitives headers GET https://api.vestauth.com/whoami --pp
{
  "Signature": "sig1=:d4Id5SXhUExsf1XyruD8eBmlDtWzt/vezoCS+SKf0M8CxSkhKBtdHH7KkYyMN6E0hmxmNHsYus11u32nhvpWBQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770247189;keyid=\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\";alg=\"ed25519\";expires=1770247489;nonce=\"NURxn28X7zyKJ9k5bHxuOyO5qdvF9L5s2qHmhTrGUzbwGSIoUCHmwSlwiiCRgTDGuum83yyWMHJU4jmrVI_XPg\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-4b94ccd425e939fac5016b6b.api.vestauth.com"
}

Vestauth handles usage, payments, and spam protection for your tool!

Self-hosting

Run your own Vestauth server.

| | |---| | |

Initialize the server and run migrations (postgres).

$ curl -sSf https://vestauth.sh | sh
$ vestauth server init
$ vestauth server db:create
$ vestauth server db:migrate

Start the server.

$ vestauth server start
vestauth server listening on http://localhost:3000

And use your server's hostname when creating agents.

$ mkdir your-agent
$ cd your-agent

$ vestauth agent init --hostname http://localhost:3000
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

That's it. Your Vestauth (web-bot-auth) infrastructure is now running under your control.

More details

Edit the .env file to configure your server.

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

For example, in production:

Change HOSTNAME to its production url - e.g. vestauth.yoursite.com
Change DATABASE_URL to a managed postgres - e.g. postgresql://USER:[email protected]:5432/postgres

[!WARNING]
Production note: Configure a wildcard DNS record for *.${HOSTNAME}.
Example: if HOSTNAME=vestauth.yourapp.com, add *.vestauth.yourapp.com.
Required for .well-known discovery per the web-bot-auth spec.

Advanced

Become a vestauth power user.

CLI 📟

Advanced CLI commands.

Create agent.

$ vestauth agent init
✔ agent created (.env/AGENT_UID=agent-609a4fd2ebf4e6347108c517)
⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]

Use --hostname to override the agent API hostname (defaults to AGENT_HOSTNAME, then api.vestauth.com): When no scheme is provided, https:// is assumed. For local non-TLS endpoints, pass http://... explicitly.

$ vestauth agent init --hostname https://vestauth.yoursite.com
✔ agent created (.env/AGENT_UID=agent-609a4fd2ebf4e6347108c517)
⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]

Run curl as agent.

$ vestauth agent curl https://api.vestauth.com/whoami
{"uid":"agent-609a4fd2ebf4e6347108c517", ...}

Pretty print curl json output.

$ vestauth agent curl https://api.vestauth.com/whoami --pp
{
  "uid": "agent-609a4fd2ebf4e6347108c517",
  "kid": "FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM",
  "public_jwk": {
    ...
  },
  "well_known_url": "https://agent-609a4fd2ebf4e6347108c517.api.vestauth.com/.well-known/http-message-signatures-directory"
}

Generate signed headers as agent.

$ vestauth agent headers GET https://api.vestauth.com/whoami --pp
{
  "Signature": "sig1=:UW6A7j8jo+gQxd+EeVgDddY51ZOc9plrSaupW/N53hQnQFvP9BuwQHgL7SVPLQIu4cnRzLgvwm7Yu9YMO+HUDQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770396357;keyid=\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\";alg=\"ed25519\";expires=1770396657;nonce=\"PrE7A6I_5fWnxBsBigNvxjp3-YangXl71V1uM3hPZavh918JqzjMSRcjHv_n5XIb3N8WivZEeigCBH6QGDSqgA\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com"
}

Change the AGENT_UID.

$ vestauth agent headers GET https://api.vestauth.com/whoami --uid agent-1234 --pp
{
  "Signature": "sig1=:UW6A7j8jo+gQxd+EeVgDddY51ZOc9plrSaupW/N53hQnQFvP9BuwQHgL7SVPLQIu4cnRzLgvwm7Yu9YMO+HUDQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770396357;keyid=\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\";alg=\"ed25519\";expires=1770396657;nonce=\"PrE7A6I_5fWnxBsBigNvxjp3-YangXl71V1uM3hPZavh918JqzjMSRcjHv_n5XIb3N8WivZEeigCBH6QGDSqgA\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-1234.api.vestauth.com"
}

Change the AGENT_PRIVATE_JWK used to sign the headers.

$ vestauth agent headers GET https://api.vestauth.com/whoami --private-jwk '{"crv":"Ed25519","d":"RyFk7QTOk_bMjFQKjyAR-vJDp7BITn9U0YBFNdpR9wE","x":"hyAxNMbuTcFQq420Dr46ucF0dRZ_FIyxgsujruEoklM","kty":"OKP","kid":"UfHTArlyLsqM8cB8sNfH2z6XOwc0RmJIq2CAPGfvMjk"}' --pp
{
  "Signature": "sig1=:PZUVVjqiECYuk8Hg1GZKKeJmwhLrcRdRA7nm1R595UFK9cx0q9atNFBzKP5wBEmszMIgvpYdMrIQbPEeKz4tCQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770396546;keyid=\"UfHTArlyLsqM8cB8sNfH2z6XOwc0RmJIq2CAPGfvMjk\";alg=\"ed25519\";expires=1770396846;nonce=\"BSIugautfZvN3u5QUgl1mMuyxgmeRsRy9XxX7GXxjJxq1mI0kJl4F-C1nITtOfSeEt6xR1YBfyxsffNKy_wKSA\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com"
}

Rotate your AGENT_PRIVATE_JWK and AGENT_PUBLIC_JWK.

$ vestauth agent rotate
✔ agent keys rotated (.env/AGENT_UID=agent-8f1b347e2e58899f3147c05b)
⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]

Verify agent.

$ vestauth tool verify GET https://api.vestauth.com/whoami --signature "sig1=:H1kxwSRWFbIzKbHaUy4hQFp/JrmVTX//72JPHcW4W7cPt9q6LytRJgx5pUgWrrr7DCcMWgx/jpTPc8Ht8SZ3CQ==:" --signature-input "sig1=(\"@authority\");created=1770396709;keyid=\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\";alg=\"ed25519\";expires=1770397009;nonce=\"BZSDVktdkjO6XH5jafAdPDttsB6eytXO7u8KXJN1tMtd5bprE3rp08HiaTRo7H6gZGtYb4_qtL7RiGi8P2Gq7w\";tag=\"web-bot-auth\"" --signature-agent "sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com"
{"uid":"agent-609a4fd2ebf4e6347108c517",...}

Create/update server .env for self-hosting (PORT, HOSTNAME, DATABASE_URL).

$ vestauth server init
✔ ready (.env/HOSTNAME=http://localhost:3000)
⮕ next run: [vestauth server start]

Create vestauth_production database.

$ vestauth server db:create 
Created database 'vestauth_production'

Run vestauth_production migrations.

$ vestauth server db:migrate 
== 20260223204000 CreateAgentsTable: migrating ================================================
== 20260223204000 CreateAgentsTable: migrated (0.0160s) ===========================
== 20260223205500 CreatePublicJwksTable: migrating ================================================
== 20260223205500 CreatePublicJwksTable: migrated (0.0100s) ===========================

Drop vestauth_production table.

$ vestauth server db:drop
Dropped database 'vestauth_production'

Start vestauth server.

$ vestauth server start 
vestauth server listening on http://localhost:3000

Start vestauth server on specific port.

$ vestauth server start --port 4567
vestauth server listening on http://localhost:4567

Specify hostname for vestauth server (default: localhost:3000).

$ vestauth server start --hostname vestauth.yoursite.com
vestauth server listening on https://vestauth.yoursite.com

Specify database url for vestauth server (default: localhost/vestauth_production).

$ vestauth server start --database-url postgresql://USER:[email protected]:5432/postgres
vestauth server listening on http://localhost:3000

Generate public/private keypair.

$ vestauth primitives keypair --pp
{
  "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"
  }
}

Generate signed headers.

$ vestauth primitives headers GET http://example.com --pp
{
  "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"
}

Verify signed headers.

$ 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"
{"uid":"agent-609a4fd2ebf4e6347108c517", ...}

Library 📦

Use vestauth directly in code.

Verify and authenticate an agent's cryptographic identity.

const agent = await vestauth.tool.verify(httpMethod, url, headers)

Verify and authenticate a signed http request.

await vestauth.primitives.verify(httpMethod, url, headers, publicJwk)

Standards

Vestauth gives agents a cryptographic identity and a simple way to authenticate HTTP requests. Most agent systems rely on API keys, bearer tokens, or username/passwords. These approaches are difficult to rotate, easy to leak, and hard to attribute to a specific agent. Vestauth replaces shared secrets with public/private key cryptography. Agents sign requests using a private key, and tools verify those requests using the agent's public key. All built on open internet standards. It's elegant and the future.

| Specification | Purpose | |------------|------------| | RFC 9421 | Defines how requests are cryptographically signed and verified | | Web-Bot-Auth Draft | Defines headers and authentication architecture for autonomous agents |

Vestauth follows these specifications to ensure interoperability between agents and tools while avoiding vendor lock-in. Vestauth focuses on developer ergonomics while staying compliant with these emerging standards.

Compare

Agent + Tool Matrix – Compare Vestauth vs existing auth.

| Capability | Vestauth | API Keys | OAuth | Cookies | |---|---|---|---|---| | Agent: no browser required | ✅ | ✅ | ⚠️ (depends on flow) | ❌ | | Agent: easy to automate | ✅ | ✅ | ⚠️ | ❌ | | Agent: no shared secret | ✅ | ❌ | ⚠️ (bearer tokens) | ❌ | | Agent: per‑request identity proof | ✅ | ❌ | ⚠️ (token‑based) | ❌ | | Agent: easy key/token rotation | ✅ | ⚠️ | ⚠️ | ⚠️ | | Tool: no secret storage | ✅ (public keys only) | ❌ | ❌ | ❌ | | Tool: strong attribution to agent | ✅ | ⚠️ | ⚠️ | ❌ | | Tool: stateless verification | ✅ | ✅ | ✅ | ❌ | | Tool: simple to implement | ⚠️ (sig verification) | ✅ | ❌ | ✅ | | Tool: revocation control | ✅ | ⚠️ | ✅ | ⚠️ |

Legend: ✅ strong fit, ⚠️ partial/conditional, ❌ poor fit

How It Works

An agent generates a public/private keypair.
The agent signs each HTTP request with its private key.
The tool verifies the signature using the agent’s public key.
Requests are attributable, auditable, and do not require shared secrets or browser sessions.

FAQ

Vestauth gives agents a cryptographic identity and a simple way to authenticate HTTP requests.
Most agent systems rely on API keys, bearer tokens, or username/passwords. These approaches are difficult to rotate, easy to leak, and hard to attribute to a specific agent.
Vestauth replaces shared secrets with public/private key cryptography. Agents sign requests using a private key, and tools verify those requests using the agent's public key.

Yes
Watch the demo

API keys are shared secrets. Anyone who obtains the key can impersonate the client, and keys are difficult to rotate safely.
Vestauth uses cryptographic signing instead of shared secrets. This allows tools to verify identity without storing or distributing sensitive credentials.

Agent keys are generated locally and stored in the agent's environment configuration (.env).
AGENT_PRIVATE_JWK is used to sign requests and must never be shared.
AGENT_PUBLIC_JWK is safe to publish and is used by tools for verification.

No.
Vestauth can authenticate any automated system including:
developer tools
CLIs
automation services
bots
infrastructure tools

Yes.
Vestauth provides libraries and primitives that can be integrated into any HTTP client or framework. The CLI simply makes it easy to adopt and demonstrate.

No.
Vestauth is primarily a client-side and verification library. Agents generate keys locally and sign requests directly. Tools verify requests using public keys exposed via .well-known discovery endpoints.
There is no central authentication server required.

Yes.
To host your own Vestauth server create the database, run the migrations, and start the server.
$ vestauth server db:create
$ vestauth server db:migrate
$ vestauth server start
vestauth server listening on http://localhost:3000

Ed25519 provides:
Strong modern cryptographic security
Fast signing and verification
Small key sizes
Wide ecosystem support

Vestauth uses HTTP Message Signatures (RFC 9421). Each request is signed using the agent's private key. The request includes signed headers such as:
Signature
Signature-Input
Signature-Agent
Tools verify the request by retrieving the agent's public key from a discovery endpoint and verifying the signature cryptographically.
If the signature is valid, the tool knows the request was created by the agent that owns that private key.

Vestauth prevents replay attacks using multiple mechanisms built into HTTP Message Signatures.
Each signed request includes:
created timestamp - limits how old a signature can be
expires timestamp - defines a short validity window
nonce value - ensures each request is unique
Tools verify that:
The signature is still within the allowed time window
The nonce has not been used before
The signature cryptographically matches the request
Because signatures are short-lived and tied to unique nonce values, an intercepted request cannot be reused successfully.
Tools may optionally store nonce values for additional replay protection.

Public key discovery allows tools to verify agent signatures without manual key exchange. Each agent hosts its public keys in a standardized .well-known directory.
This enables dynamic agent onboarding while preserving cryptographic verification.

No.
Vestauth signs requests using private keys locally. Only public keys are shared for verification.

Vestauth prevents Server-Side Request Forgery (SSRF) by restricting public key discovery to trusted domains.
By default, Vestauth only resolves agent discovery endpoints inside the controlled namespace:
*.api.vestauth.com
When a tool verifies a request, Vestauth converts the agent identity into a fixed .well-known endpoint within this trusted domain. Because this domain is controlled by Vestauth, tools never fetch attacker-supplied URLs or internal network addresses.
This removes the most common SSRF attack vector during signature verification.
Custom trusted discovery domains
Tools can optionally configure additional trusted discovery domains using:
TOOL_FQDN_REGEX
This allows organizations to:
Host their own agent discovery infrastructure
Support private internal agents
Implement federated trust models
For example:
TOOL_FQDN_REGEX=".*\.agents\.vestauth\.com|.*\.agents\.example\.internal"
Only discovery endpoints matching this allowlist will be fetched.
Defense in depth
Even with domain scoping, tools may optionally add safeguards such as:
HTTPS-only enforcement
Request timeouts
Response size limits
Public key caching
Vestauth removes SSRF by design, while still allowing controlled federation when needed.

Vestauth uses .well-known discovery to keep requests small, enable key rotation, and support long-term identity management.
Embedding public keys directly in every request would increase header size, reduce caching opportunities, and make key rotation difficult. By publishing keys through a discovery endpoint, Vestauth allows tools to fetch and cache keys independently from individual requests.
This approach provides several benefits:
Efficient requests
Public keys are retrieved once and can be cached by tools. Agents do not need to send large key material with every request.
Key rotation support
Agents can rotate signing keys without changing their identity. Tools simply refresh keys from the discovery endpoint.
Multi-key support
Agents can safely publish multiple active keys (for rotation or staged rollouts) using the standard HTTP Message Signatures directory format.
Standards alignment
Vestauth follows the discovery model used in:
HTTP Message Signatures directories
OAuth / OpenID Connect key discovery
Web identity federation systems

Contributing

You can fork this repo and create pull requests or if you have questions or feedback:

github.com/vestauth/vestauth - bugs and discussions
@vestauth 𝕏 (DMs are open)