vestauth 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/vestauth/vestauth/compare/v0.21.0...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.22.0...main)
+
+## [0.22.0](https://github.com/vestauth/vestauth/compare/v0.21.1...v0.22.0) (2026-03-02)
+
+### Changed
+
+* `agent curl` now by default prepends `-X POST` and `-H "Content-Type: application/json"` ([#45](https://github.com/vestauth/vestauth/pull/45))
+
+## [0.21.1](https://github.com/vestauth/vestauth/compare/v0.21.0...v0.21.1) (2026-02-25)
+
+### Changed
+
+* README changes
 
 ## [0.21.0](https://github.com/vestauth/vestauth/compare/v0.20.1...v0.21.0) (2026-02-25)
 
@@ -88,7 +100,7 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### Changed
 
-* Move from `*.agents.vestauth.com` FQDN to `*.api.vestaut.com` to prepare way for custom `--hostname` for internal enterprise use cases.
+* Move from `*.agents.vestauth.com` FQDN to `*.api.vestauth.com` to prepare way for custom `--hostname` for internal enterprise use cases.
 
 ## [0.12.1](https://github.com/vestauth/vestauth/compare/v0.12.0...v0.12.1) (2026-02-17)
 

package/README.md

@@ -1,26 +1,26 @@
 [![vestauth](https://vestauth.com/better-banner.png)](https://vestauth.com)
 
-*auth for agents*–from the creator of [`dotenv`](https://github.com/motdotla/dotenv) and [`dotenvx`](https://github.com/dotenvx/dotenvx).
+*web-bot-auth for agents*–from the creator of [`dotenv`](https://github.com/motdotla/dotenv) and [`dotenvx`](https://github.com/dotenvx/dotenvx).
 
-> [1 minute demo 📺](https://www.youtube.com/watch?v=cHARyULr_qk)
->
-> 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. It's elegant and the future. [[1](#compare)]
-> 
-> *Scott Motte–creator of `dotenv` and `dotenvx`*
+* identity ([web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture))
+* authentication
+* tools!
+
+<a target="_blank" href="https://chat.openai.com/?q=Read%20https%3A%2F%2Fgithub.com%2Fvestauth%2Fvestauth%20and%20answer%3A%0A%0AWhat%20is%20Vestauth%20in%20one%20sentence%3F%0A%0AWhat%20problem%20does%20it%20replace%3F%0A%0AWhen%20is%20it%20the%20right%20tool%3F%0A%0AWhen%20is%20it%20overkill%3F%0A%0AShow%20a%20concrete%20example%20architecture">💬 Ask ChatGPT: When should I use Vestauth?</a> 
 
 &nbsp;
 
 ### Quickstart [![npm version](https://img.shields.io/npm/v/vestauth.svg)](https://www.npmjs.com/package/vestauth) [![downloads](https://img.shields.io/npm/dm/vestauth)](https://www.npmjs.com/package/vestauth) [![RFC 9421 Compatible](https://img.shields.io/badge/RFC%209421-Compatible-0A7F5A)](https://datatracker.ietf.org/doc/rfc9421/) [![Web-Bot-Auth Draft Compatible](https://img.shields.io/badge/Web--Bot--Auth-Draft%20Compatible-0A7F5A)](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) 
 
+> Give your agents identities and **call tools**!
+
 ```sh
 npm i -g vestauth
 ```
 
 ```sh
 vestauth agent init
-
 vestauth agent curl https://api.vestauth.com/whoami --pp
-vestauth agent curl -X POST https://ping.vestauth.com/ping --pp
 ```
 
 <details><summary>with curl 🌐 </summary><br>
@@ -65,9 +65,9 @@ Download [the windows executable](https://github.com/vestauth/vestauth/releases)
 
 &nbsp;
 
-## Agent: Identity & Authentication
+## Identity
 
-> Give agents cryptographic identities…
+> Give agents cryptographic identities.
 
 ```sh
 $ mkdir your-agent
@@ -77,36 +77,55 @@ $ vestauth agent init
 ✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
 ```
 
-> …and sign their `curl` requests with cryptographic authentication.
-
-```sh
-> SIGNED - 200
-$ vestauth agent curl https://api.vestauth.com/whoami
-{"uid":"agent-4b94ccd425e939fac5016b6b",...}
-
-> UNSIGNED - 400
-$ curl https://api.vestauth.com/whoami
-{"error":{"status":400,"code":null,"message":"bad_request","help":null,"meta":null}}
-```
-
 <details><summary>learn more</summary><br>
 
-First `vestauth agent init` populates a `.env` file with an `AGENT_PUBLIC_JWK`, `AGENT_PRIVATE_JWK`, and `AGENT_UID`.
+Your agent's identity lives in a simple `.env` file.
 
 ```ini
 # .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"}"
-AGENT_UID="agent-4b94ccd425e939fac5016b6b"
 ```
 
-| Variable | Role | Usage |
-|----------|------------|------------|
-| `AGENT_PUBLIC_JWK` | Verification | Published for tool signature validation |
-| `AGENT_PRIVATE_JWK` | Signing | Used locally to sign HTTP requests |
-| `AGENT_UID` | Identity | Builds discovery FQDN and identifies the agent |
+[💬 Ask ChatGPT: Are HTTP message signatures more secure than API keys?](https://chat.openai.com/?q=Are%20HTTP%20message%20signatures%20more%20secure%20than%20API%20keys%3F)
+
+</details>
+
+&nbsp;
+
+## Authentication
+
+> Authenticate agents – `vestauth.tool.verify`…
+
+```js
+...
+const vestauth = require('vestauth')
+
+app.get('/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.
+
+```sh
+> SIGNED - 200
+$ vestauth agent curl https://api.vestauth.com/whoami
+{"uid":"agent-4b94ccd425e939fac5016b6b",...}
+```
+
+<details><summary>learn more</summary><br>
 
-Then `vestauth agent curl` autosigns `curl` requests – injecting valid signed headers according to the [web-bot-auth draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture). You can peek these with the built-in `headers` primitive.
+`vestauth agent curl` autosigns `curl` requests – injecting valid signed headers according to the [web-bot-auth draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture). You can peek these with the built-in `headers` primitive.
 
 ```sh
 $ vestauth primitives headers GET https://api.vestauth.com/whoami --pp
@@ -117,73 +136,177 @@ $ vestauth primitives headers GET https://api.vestauth.com/whoami --pp
 }
 ```
 
-Vestauth turns `curl` into a powerful primitive for tool-side agent identity, verification, and authentication. See the next section.
+</details>
+
+&nbsp;
+
+## Tools
+
+> Call tools!
+
+```sh
+$ vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
+$ vestauth agent curl https://sfs.vestauth.com/list
+```
+
+#### First Party Tools
+
+<details><summary>`SFS` Simple File System</summary><br/>
+
+> SFS is a simple file system for vestauth agents.
+> [sfs.vestauth.com](https://sfs.vestauth.com)
+
+```sh
+# 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"}'
+```
+
+&nbsp;
 
 </details>
+<details><summary>`Ping` ping.vestauth.com</summary><br/>
+
+> Ping is a demonstration of vestauth.
+> [ping.vestauth.com](https://ping.vestauth.com)
+
+```sh
+# make a ping
+vestauth agent curl https://ping.vestauth.com/ping
+```
 
 &nbsp;
 
-## Tool: Verification 
+</details>
 
-> Verify requests and safely trust agent identity using cryptographic proof.
+#### Third Party Tools
 
-```js
-// index.js
-const express = require('express')
-const vestauth = require('vestauth')
-const app = express()
+<details><summary>`AS2` Agentic Secret Storage</summary><br/>
 
-// vestauth agent curl http://localhost:3000/whoami
-app.get('/whoami', async (req, res) => {
-  try {
-    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
+> AS2 is a simple, agent-friendly secret storage.
+> [as2.dotenvx.com](https://as2.dotenvx.com)
 
-    // --------------------------------------------------------------------------------
-    // 🪪 Reveal the agent's cryptographic identity.                                 //
-    // The `tool.verify` method turns your endpoint into a cryptographically     //
-    // authenticated tool — verifying signatures, keys, and returning the agent. //
-    // --------------------------------------------------------------------------------
-    const agent = await vestauth.tool.verify(req.method, url, req.headers)
+```sh
+# set a secret
+vestauth agent curl https://as2.dotenvx.com/set -d '{"KEY":"value"}'
 
-    res.json(agent)
-  } catch (err) {
-    res.status(401).json({ code: 401, error: { message: err.message }})
-  }
-})
+# get all secrets
+vestauth agent curl "https://as2.dotenvx.com/get"
 
-app.listen(3000, () => { console.log('listening on http://localhost:3000') })
+# 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"
 ```
 
+&nbsp;
+
+</details>
+<details><summary>`Docle` Check if email address is real</summary><br>
+
+> 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.
+> 
+> [learn more](https://github.com/treadiehq/docle) 
+
 ```sh
-$ npm install express vestauth --save
-$ node index.js
-listening on http://localhost:3000
+# verify an email
+vestauth agent curl https://docle.co/api/verify -d '{"emails":["test@example.com"]}'
+
+# check your usage
+vestauth agent curl https://docle.co/api/agent/usage -X GET
 ```
 
+&nbsp;
+
+</details>
+<details><summary>more coming soon</summary><br/>
+
+* 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 wel'll list it.
+
+</details>
+
+&nbsp;
+
+## Self-hosting
+
+> Run your own Vestauth server.
+
+| |
+|---|
+| <a target="_blank" href="https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7"><img src="https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7" alt="self-hosting vestauth" width="480"></a> |
+
+Initialize the server and run migrations (postgres).
+
 ```sh
-$ vestauth agent curl http://localhost:3000/whoami
-{"uid":"agent-4b94ccd425e939fac5016b6b",...}
+$ curl -sSf https://vestauth.sh | sh
+$ vestauth server init
+$ vestauth server db:create
+$ vestauth server db:migrate
 ```
 
-<details><summary>learn more</summary><br>
+Start the server.
 
 ```sh
-Agent → Signs Request → Tool → Discovers Keys → Verifies Signature → Trusted Agent
+$ vestauth server start
+vestauth server listening on http://localhost:3000
 ```
 
-Vestauth verifies requests using public key discovery and HTTP Message Signature validation.
+And use your server's hostname when creating agents.
 
-When a signed request is received, Vestauth:
+```sh
+$ mkdir your-agent
+$ cd your-agent
 
-1. Extracts the agent identity from the `Signature-Agent` header.
-2. Resolves the agent's discovery endpoint.
-3. Fetches the agent's public keys from its `.well-known/http-message-signatures-directory`.
-4. Verifies the request signature using RFC 9421.
-5. Validates timestamps and nonce protections to prevent replay attacks.
+$ vestauth agent init --hostname http://localhost:3000
+✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
+```
+
+That's it. Your Vestauth ([web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)) infrastructure is now running under your control.
+
+More details
+
+<details><summary>config</summary><br>
+
+Edit the `.env` file to configure your server.
+
+```ini
+PORT="3000"
+HOSTNAME="http://localhost:3000"
+DATABASE_URL="postgres://localhost/vestauth_production"
+```
 
-If verification succeeds, the tool can safely trust the agent's cryptographic identity.
+For example, in production:
 
-Vestauth intentionally separates identity discovery from verification to support key rotation and distributed agent infrastructure.
+* Change `HOSTNAME` to its production url - e.g. `vestauth.yoursite.com`
+* Change `DATABASE_URL` to a managed postgres - e.g. `postgresql://USER:PASS@aws-1-us-east-1.pooler.supabase.com:5432/postgres`
+
+</details>
+<details><summary>production note</summary><br>
+
+> [!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](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) spec.
 
 </details>
 
@@ -313,6 +436,17 @@ $ vestauth tool verify GET https://api.vestauth.com/whoami --signature "sig1=:H1
 {"uid":"agent-609a4fd2ebf4e6347108c517",...}
 ```
 
+</details>
+<details><summary>`server init`</summary><br>
+
+Create/update server `.env` for self-hosting (`PORT`, `HOSTNAME`, `DATABASE_URL`).
+
+```sh
+$ vestauth server init
+✔ ready (.env/HOSTNAME=http://localhost:3000)
+⮕ next run: [vestauth server start]
+```
+
 </details>
 <details><summary>`server db:create`</summary><br>
 
@@ -461,11 +595,16 @@ await vestauth.primitives.verify(httpMethod, url, headers, publicJwk)
 
 &nbsp;
 
-## Available Tools
+## Standards
 
-> List of tools. We're actively building tools and looking for others to help grow the vestauth ecosystem with calls for tools like sending email, sms, uploading files and more. Vestauth agents need more tools. A tool is just a sharp API call. Add your tool here.
+> 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.
 
-* AS2 (Agentic Secret Storage) - https://as2.dotenvx.com
+| Specification | Purpose |
+|------------|------------|
+| **[RFC 9421](https://datatracker.ietf.org/doc/rfc9421/)** | Defines how requests are cryptographically signed and verified |
+| **[Web-Bot-Auth Draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)** | 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.
 
 &nbsp;
 
@@ -497,26 +636,6 @@ Legend: ✅ strong fit, ⚠️ partial/conditional, ❌ poor fit
 
 &nbsp;
 
-## Standards
-
-Vestauth builds on open internet standards for agent authentication.
-
-| Specification | Purpose |
-|------------|------------|
-| **[RFC 9421 – HTTP Message Signatures](https://datatracker.ietf.org/doc/rfc9421/)** | Defines how requests are cryptographically signed and verified |
-| **[Web-Bot-Auth Draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)** | 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.
-
-&nbsp;
-
-## Demo
-
-[![vestauth:ping](https://vestauth.com/demo.png)](https://ping.vestauth.com)
-> [https://ping.vestauth.com](https://ping.vestauth.com)
-
-&nbsp;
-
 ## FAQ
 
 <details><summary>What problem does Vestauth solve?</summary><br>
@@ -530,7 +649,15 @@ Vestauth follows these specifications to ensure interoperability between agents
 &nbsp;
 
 </details>
+<details><summary>Is there a demo video?</summary><br>
 
+> Yes
+>
+> [Watch the demo](https://www.youtube.com/watch?v=cHARyULr_qk)
+
+&nbsp;
+
+</details>
 <details><summary>Why not just use API keys?</summary><br>
 
 > API keys are shared secrets. Anyone who obtains the key can impersonate the client, and keys are difficult to rotate safely.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vestauth",
-  "version": "0.21.0",
-  "description": "auth for agents–from the creator of dotenvx",
+  "version": "0.22.0",
+  "description": "web-bot-auth for agents–from the creator of dotenvx",
   "keywords": [
     "vestauth",
     "web-bot-auth",

package/src/cli/actions/agent/curl.js

@@ -5,6 +5,53 @@ const Errors = require('./../../../lib/helpers/errors')
 const findUrl = require('./../../../lib/helpers/findUrl')
 const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
+function requestMethodFromArgs (args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '-X' || arg === '--request') {
+      const method = args[i + 1]
+      if (method) return method.toUpperCase()
+      continue
+    }
+
+    if (arg.startsWith('--request=')) {
+      return arg.slice('--request='.length).toUpperCase()
+    }
+
+    if (arg.startsWith('-X') && arg.length > 2) {
+      return arg.slice(2).toUpperCase()
+    }
+  }
+
+  return null
+}
+
+function hasContentTypeHeader (args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '-H' || arg === '--header') {
+      const header = args[i + 1] || ''
+      if (header.toLowerCase().startsWith('content-type:')) return true
+      continue
+    }
+
+    if (arg.startsWith('--header=')) {
+      const header = arg.slice('--header='.length)
+      if (header.toLowerCase().startsWith('content-type:')) return true
+      continue
+    }
+
+    if (arg.startsWith('-H') && arg.length > 2) {
+      const header = arg.slice(2)
+      if (header.toLowerCase().startsWith('content-type:')) return true
+    }
+  }
+
+  return false
+}
+
 async function curl () {
   try {
     const commandArgs = this.args
@@ -13,14 +60,18 @@ async function curl () {
     const options = this.opts()
     logger.debug(`options: ${JSON.stringify(options)}`)
 
-    const httpMethod = 'GET'
+    const httpMethod = requestMethodFromArgs(commandArgs) || 'POST'
     const url = findUrl(commandArgs)
     const headers = await agent.headers(httpMethod, url)
+    const includeRequestMethod = requestMethodFromArgs(commandArgs) === null
+    const includeContentType = !hasContentTypeHeader(commandArgs)
     const injected = [
       'curl',
       '-H', `Signature: ${headers.Signature}`,
       '-H', `Signature-Input: ${headers['Signature-Input']}`,
       '-H', `Signature-Agent: ${headers['Signature-Agent']}`,
+      ...(includeRequestMethod ? ['-X', 'POST'] : []),
+      ...(includeContentType ? ['-H', 'Content-Type: application/json'] : []),
       ...commandArgs
     ]
 

package/src/lib/helpers/touch.js

@@ -1,6 +1,6 @@
 const fs = require('fs')
 
-const DEFAULT_HEADER_COMMENT = '# [vestauth] auth for agents–from the creator of `dotenv` and `dotenvx`'
+const DEFAULT_HEADER_COMMENT = '# [vestauth] web-bot-auth for agents–from the creator of `dotenv` and `dotenvx`'
 
 function touch (filepath, headerComment = null) {
   if (!fs.existsSync(filepath)) {