vestauth 0.22.0 → 0.23.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.22.0...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.23.0...main)
+
+## [0.23.0](https://github.com/vestauth/vestauth/compare/v0.22.1...v0.23.0) (2026-03-03)
+
+### Added
+
+* `vestauth tool init` preparing the way for 402 payments ([#46](https://github.com/vestauth/vestauth/pull/46))
+
+## [0.22.1](https://github.com/vestauth/vestauth/compare/v0.22.0...v0.22.1) (2026-03-02)
+
+### Changed
+
+* `vestauth server start` should use `POST /whoami`
 
 ## [0.22.0](https://github.com/vestauth/vestauth/compare/v0.21.1...v0.22.0) (2026-03-02)
 

package/README.md

@@ -3,8 +3,8 @@
 *web-bot-auth for agents*–from the creator of [`dotenv`](https://github.com/motdotla/dotenv) and [`dotenvx`](https://github.com/dotenvx/dotenvx).
 
 * identity ([web-bot-auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture))
-* authentication
 * tools!
+* authentication
 
 <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> 
 
@@ -21,6 +21,9 @@ npm i -g vestauth
 ```sh
 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":"you@email.com", "text":"hello from agent"}'
 ```
 
 <details><summary>with curl 🌐 </summary><br>
@@ -94,66 +97,21 @@ AGENT_PRIVATE_JWK="{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72y
 
 &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>
-
-`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
-{
-  "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"
-}
-```
-
-</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
+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
+#### First Party
 
 <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
@@ -173,25 +131,41 @@ vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'
 &nbsp;
 
 </details>
-<details><summary>`Ping` ping.vestauth.com</summary><br/>
+<details><summary>`SAM` Simple Agent Mail</summary><br/>
 
-> Ping is a demonstration of vestauth.
-> [ping.vestauth.com](https://ping.vestauth.com)
+> SAM is a simple way to send email for vestauth agents.
+>
+> [sam.vestauth.com](https://sam.vestauth.com)
 
 ```sh
-# make a ping
-vestauth agent curl https://ping.vestauth.com/ping
+# send an email
+vestauth agent curl https://sam.vestauth.com/send -d '{"to":"you@email.com", "text":"i am agent"}'
 ```
 
 &nbsp;
 
 </details>
+<details><summary>`GEO` Latitude and Longitude</summary><br/>
 
-#### Third Party Tools
+> GEO returns the current latitude and longitude of a vestauth agent.
+>
+> [geo.vestauth.com](https://geo.vestauth.com)
+
+```sh
+# return latitude and longitude
+vestauth agent curl https://geo.vestauth.com/geo
+```
+
+&nbsp;
+
+</details>
+
+#### Third Party
 
 <details><summary>`AS2` Agentic Secret Storage</summary><br/>
 
 > AS2 is a simple, agent-friendly secret storage.
+>
 > [as2.dotenvx.com](https://as2.dotenvx.com)
 
 ```sh
@@ -214,15 +188,15 @@ vestauth agent curl "https://as2.dotenvx.com/get?key=KEY,TWILIO"
 <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) 
+>
+> [github.com/treadiehq/docle](https://github.com/treadiehq/docle) 
 
 ```sh
 # 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
+vestauth agent curl https://docle.co/api/agent/usage
 ```
 
 &nbsp;
@@ -238,10 +212,58 @@ vestauth agent curl https://docle.co/api/agent/usage -X GET
 * Human-in-the-loop - coming
 * Rotate NPM Tokens - coming
 * Rotate GitHub Tokens - coming
-* Working on a tool? Tell us and wel'll list it.
+* Working on a tool? Tell us and we'll list it.
+
+</details>
+
+&nbsp;
+
+## Authentication
+
+> Build your own tools. Authenticate them with a single line of code – `vestauth.tool.verify`…
+
+```js
+...
+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.
+
+```sh
+> SIGNED - 200
+$ vestauth agent curl https://api.vestauth.com/whoami
+{"uid":"agent-4b94ccd425e939fac5016b6b",...}
+```
+
+<details><summary>learn more</summary><br>
+
+`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
+{
+  "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"
+}
+```
 
 </details>
 
+Vestauth handles usage, payments, and spam protection for your tool!
+
 &nbsp;
 
 ## Self-hosting

package/package.json

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

package/src/cli/actions/primitives/verify.js

@@ -25,9 +25,13 @@ async function verify (httpMethod, uri) {
       'Signature-Agent': options.signatureAgent
     }
 
+    const meter = {
+      cost: options.meterCost
+    }
+
     const publicJwk = options.publicJwk ? JSON.parse(options.publicJwk) : undefined
 
-    const output = await primitives.verify(httpMethod, uri, headers, publicJwk)
+    const output = await primitives.verify(httpMethod, uri, headers, meter, publicJwk)
 
     let space = 0
     if (options.prettyPrint) {

package/src/cli/actions/tool/init.js

@@ -0,0 +1,26 @@
+const { logger } = require('./../../../shared/logger')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
+
+const tool = require('./../../../lib/tool')
+
+async function init () {
+  try {
+    const options = this.opts()
+    logger.debug(`options: ${JSON.stringify(options)}`)
+
+    const output = await tool.init(options.hostname)
+
+    if (output.isNew) {
+      logger.success(`✔ tool created (${output.path}/TOOL_UID=${output.TOOL_UID})`)
+    } else {
+      logger.info(`• tool exists (${output.path}/TOOL_UID=${output.TOOL_UID})`)
+    }
+
+    logger.help(`⮕ next run: [vestauth agent curl ${output.TOOL_HOSTNAME}/whoami]`)
+  } catch (error) {
+    catchAndLog(error)
+    process.exit(1)
+  }
+}
+
+module.exports = init

package/src/cli/actions/tool/verify.js

@@ -17,7 +17,11 @@ async function verify (httpMethod, uri) {
       'Signature-Agent': options.signatureAgent
     }
 
-    const output = await tool.verify(httpMethod, uri, headers)
+    const meter = {
+      cost: options.meterCost
+    }
+
+    const output = await tool.verify(httpMethod, uri, headers, meter)
 
     let space = 0
     if (options.prettyPrint) {

package/src/cli/commands/primitives.js

@@ -39,6 +39,7 @@ primitives.command('verify')
   .requiredOption('--signature-input <signatureInput>', '')
   .option('--signature-agent <signatureAgent>', '')
   .option('--public-jwk <publicJwk>', 'public JWK (json string)', env('AGENT_PUBLIC_JWK'))
+  .option('--meter-cost <meterCost>', 'vesties per invocation', '0')
   .option('--pp, --pretty-print', 'pretty print output')
   .action(verifyAction)
 

package/src/cli/commands/tool.js

@@ -1,4 +1,5 @@
 const { Command } = require('commander')
+const env = require('./../../lib/helpers/env')
 
 const tool = new Command('tool')
 
@@ -6,6 +7,13 @@ tool
   .description('🔨 tool')
   .allowUnknownOption()
 
+// vestauth tool init
+const initAction = require('./../actions/tool/init')
+tool.command('init')
+  .description('create tool')
+  .option('--hostname <hostname>', 'tool API hostname', env('TOOL_HOSTNAME'))
+  .action(initAction)
+
 // vestauth tool verify
 const verifyAction = require('./../actions/tool/verify')
 tool.command('verify')
@@ -15,6 +23,7 @@ tool.command('verify')
   .requiredOption('--signature <signature>', '')
   .requiredOption('--signature-input <signatureInput>', '')
   .requiredOption('--signature-agent <signatureAgent>', '')
+  .option('--meter-cost <meterCost>', 'vesties per invocation', '0')
   .option('--pp, --pretty-print', 'pretty print output')
   .action(verifyAction)
 

package/src/lib/api/postToolRegister.js

@@ -0,0 +1,42 @@
+const { http } = require('../helpers/http')
+const buildApiError = require('../helpers/buildApiError')
+const agentHeaders = require('../helpers/agentHeaders')
+
+class PostToolRegister {
+  constructor (hostname, publicJwk, privateJwk) {
+    this.hostname = hostname || 'https://api.vestauth.com'
+    this.publicJwk = publicJwk
+    this.privateJwk = privateJwk
+  }
+
+  async run () {
+    const hostname = this.hostname
+    const url = `${hostname}/tool/register`
+    const publicJwk = this.publicJwk
+    const privateJwk = this.privateJwk
+
+    const httpMethod = 'POST'
+    const headers = await agentHeaders(httpMethod, url, 'REGISTERING', JSON.stringify(privateJwk), null, null, hostname)
+    headers['Content-Type'] = 'application/json'
+    delete headers['Signature-Agent'] // don't send Signature-Agent on registration. nothing to discover yet.
+    delete headers['signature-agent']
+
+    const resp = await http(url, {
+      method: httpMethod,
+      headers,
+      body: JSON.stringify({
+        public_jwk: publicJwk
+      })
+    })
+
+    if (resp.statusCode >= 400) {
+      const json = await resp.body.json()
+      throw buildApiError(resp.statusCode, json)
+    }
+
+    const json = await resp.body.json()
+    return json
+  }
+}
+
+module.exports = PostToolRegister

package/src/lib/helpers/normalizeToolHostname.js

@@ -0,0 +1,16 @@
+const env = require('./env')
+
+function normalizeToolHostname (hostname = null) {
+  const envHostname = env('TOOL_HOSTNAME')
+  const value = (hostname || envHostname || 'api.vestauth.com').trim()
+  const candidate = /^https?:\/\//i.test(value) ? value : `https://${value}`
+  const url = new URL(candidate)
+
+  if (url.pathname !== '/' || url.search || url.hash) {
+    throw new Error('invalid --hostname. path/query/hash are not allowed')
+  }
+
+  return url.origin
+}
+
+module.exports = normalizeToolHostname

package/src/lib/helpers/toolInit.js

@@ -0,0 +1,33 @@
+const dotenvx = require('@dotenvx/dotenvx')
+const keypair = require('./keypair')
+const touch = require('./touch')
+const normalizeToolHostname = require('./normalizeToolHostname')
+const PostToolRegister = require('../api/postToolRegister')
+
+async function toolInit (hostname = null) {
+  const envPath = '.env'
+  const normalizedHostname = normalizeToolHostname(hostname)
+  const shouldPersistHostname = normalizedHostname !== 'https://api.vestauth.com'
+
+  const kp = keypair(null, 'tool')
+
+  touch(envPath)
+
+  const tool = await new PostToolRegister(normalizedHostname, kp.publicJwk, kp.privateJwk).run()
+  dotenvx.set('TOOL_UID', tool.uid, { path: envPath, plain: true, quiet: true })
+  dotenvx.set('TOOL_PUBLIC_JWK', JSON.stringify(kp.publicJwk), { path: envPath, plain: true, quiet: true })
+  dotenvx.set('TOOL_PRIVATE_JWK', JSON.stringify(kp.privateJwk), { path: envPath, plain: true, quiet: true })
+  if (shouldPersistHostname) {
+    dotenvx.set('TOOL_HOSTNAME', normalizedHostname, { path: envPath, plain: true, quiet: true })
+  }
+
+  return {
+    TOOL_UID: tool.uid,
+    TOOL_PUBLIC_JWK: kp.publicJwk,
+    TOOL_HOSTNAME: normalizedHostname,
+    path: envPath,
+    isNew: tool.is_new
+  }
+}
+
+module.exports = toolInit

package/src/lib/helpers/toolVerify.js

@@ -4,7 +4,7 @@ const extractHostAndHostname = require('./extractHostAndHostname')
 const trustedFqdn = require('./trustedFqdn')
 const Errors = require('./errors')
 
-async function toolVerify (httpMethod, uri, headers = {}, serverHostname = null) {
+async function toolVerify (httpMethod, uri, headers = {}, meter = {}, serverHostname = null) {
   if (!httpMethod) {
     throw new Errors().missingHttpMethod()
   }
@@ -33,7 +33,7 @@ async function toolVerify (httpMethod, uri, headers = {}, serverHostname = null)
     throw new Errors().untrustedSignatureAgent()
   }
 
-  return verify(httpMethod, uri, headers)
+  return verify(httpMethod, uri, headers, meter)
 }
 
 module.exports = toolVerify

package/src/lib/helpers/verify.js

@@ -77,7 +77,7 @@ async function resolvePublicJwk ({ signatureInput, signatureAgent, publicJwk })
   }
 }
 
-async function verify (httpMethod, uri, headers = {}, publicJwk) {
+async function verify (httpMethod, uri, headers = {}, meter = {}, publicJwk) {
   const signature = headers.Signature || headers.signature
   const signatureInput = headers['Signature-Input'] || headers['signature-input']
   const signatureAgent = headers['Signature-Agent'] || headers['signature-agent']

package/src/lib/main.d.ts

@@ -46,6 +46,11 @@ export interface VerifyResult {
   well_known_url?: string
 }
 
+export interface Meter {
+  cost?: string | number
+  [prop: string]: unknown
+}
+
 export interface AgentApi {
   /**
    * Creates (or reuses) an Ed25519 keypair, registers the agent, and writes to `.env`.
@@ -93,6 +98,23 @@ export interface ProviderApi {
   verify(httpMethod: HttpMethod, uri: string, headers?: HeaderBag): Promise<VerifyResult>
 }
 
+export interface ToolApi {
+  /**
+   * Creates (or reuses) an Ed25519 keypair, registers the tool, and writes to `.env`.
+   */
+  init(): Promise<{
+    TOOL_PUBLIC_JWK: PublicJwk
+    TOOL_UID: string
+    path: string
+    isNew: boolean
+  }>
+
+  /**
+   * Verifies a signed request (fetching the agent's discovery keys when needed).
+   */
+  verify(httpMethod: HttpMethod, uri: string, headers?: HeaderBag): Promise<VerifyResult>
+}
+
 export interface PrimitivesApi {
   /**
    * Creates an Ed25519 keypair. If `existingPrivateJwk` is provided, it is reused.
@@ -121,16 +143,19 @@ export interface PrimitivesApi {
     httpMethod: HttpMethod,
     uri: string,
     headers?: HeaderBag,
+    meter?: Meter,
     publicJwk?: PublicJwk
   ): Promise<VerifyResult>
 }
 
 export const agent: AgentApi
+export const tool: ToolApi
 export const provider: ProviderApi
 export const primitives: PrimitivesApi
 
 declare const _default: {
   agent: AgentApi
+  tool: ToolApi
   provider: ProviderApi
   primitives: PrimitivesApi
 }

package/src/lib/tool.js

@@ -1,5 +1,7 @@
+const toolInit = require('./helpers/toolInit')
 const toolVerify = require('./helpers/toolVerify')
 
 module.exports = {
+  init: toolInit,
   verify: toolVerify
 }

package/src/server/index.js

@@ -105,7 +105,7 @@ app.get('/.well-known/http-message-signatures-directory', async (req, res) => {
   return res.json({ keys })
 })
 
-app.get('/whoami', async (req, res) => {
+app.post('/whoami', async (req, res) => {
   try {
     const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
     const attrs = {

package/src/server/services/registerService.js

@@ -1,11 +1,12 @@
 const primitives = require('./../../lib/primitives')
 
 class RegisterService {
-  constructor ({ models, httpMethod, uri, headers, publicJwk }) {
+  constructor ({ models, httpMethod, uri, headers, meter, publicJwk }) {
     this.models = models
     this.httpMethod = httpMethod
     this.uri = uri
     this.headers = headers
+    this.meter = meter
     this.publicJwk = publicJwk
   }
 
@@ -14,6 +15,7 @@ class RegisterService {
       this.httpMethod,
       this.uri,
       this.headers,
+      this.meter,
       this.publicJwk
     )
 

package/src/server/services/rotateService.js

@@ -11,7 +11,7 @@ class RotateService {
   }
 
   async run () {
-    const remoteAgent = await tool.verify(this.httpMethod, this.uri, this.headers, this.serverHostname)
+    const remoteAgent = await tool.verify(this.httpMethod, this.uri, this.headers, {}, this.serverHostname)
     // uid: 'agent-6d2140af72bcefcedd4b44ab',
     // kid: 'Tx3W50MU5wMQ5I77z5DUGtbcs3ZPLlxfWx14pzpo5Fo',
     // public_jwk: {

package/src/server/services/whoamiService.js

@@ -9,7 +9,7 @@ class WhoamiService {
   }
 
   async run () {
-    return tool.verify(this.httpMethod, this.uri, this.headers, this.serverHostname)
+    return tool.verify(this.httpMethod, this.uri, this.headers, {}, this.serverHostname)
   }
 }