vestauth 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 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.1...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)
 

package/README.md

@@ -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>
@@ -128,15 +131,29 @@ vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'
 &nbsp;
 
 </details>
-<details><summary>`GEO` geo.vestauth.com</summary><br/>
+<details><summary>`SAM` Simple Agent Mail</summary><br/>
+
+> SAM is a simple way to send email for vestauth agents.
+>
+> [sam.vestauth.com](https://sam.vestauth.com)
+
+```sh
+# 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/>
 
-> GEO returns the current geo-coordinates of a vestauth agent.
+> GEO returns the current latitude and longitude of a vestauth agent.
 >
 > [geo.vestauth.com](https://geo.vestauth.com)
 
 ```sh
-# make a ping
-vestauth agent curl https://ping.vestauth.com/ping
+# return latitude and longitude
+vestauth agent curl https://geo.vestauth.com/geo
 ```
 
 &nbsp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vestauth",
-  "version": "0.22.1",
+  "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/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)
   }
 }