vestauth 0.7.0 → 0.7.2

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.7.0...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.7.2...main)
+
+## [0.7.2](https://github.com/vestauth/vestauth/compare/v0.7.1...v0.7.2) (2026-02-04)
+
+### Changed
+
+* Handle headers in a more flexible way
+
+## [0.7.1](https://github.com/vestauth/vestauth/compare/v0.7.0...v0.7.1) (2026-02-04)
+
+### Changed
+
+* Raise an error if a bad `Signature-Agent` header ([#11](https://github.com/vestauth/vestauth/pull/11))
 
 ## [0.7.0](https://github.com/vestauth/vestauth/compare/v0.6.0...v0.7.0) (2026-02-03)
 

package/README.md

@@ -2,67 +2,137 @@
 
 *auth for agents*–from the creator of [`dotenvx`](https://github.com/dotenvx/dotenvx).
 
-* identity
+* identity (cryptographic)
 * authentication
+* verification
 
  
 
 ### Quickstart [![npm version](https://img.shields.io/npm/v/vestauth.svg)](https://www.npmjs.com/package/vestauth) [![downloads](https://img.shields.io/npm/dw/vestauth)](https://www.npmjs.com/package/vestauth)
 
 ```sh
-curl -sfS https://vestauth.sh | sh
+npm i -g vestauth
 ```
 
 ```sh
 vestauth agent init
-vestauth agent curl https://api.vestauth.com/whoami
 ```
 
  
 
-or install as npm - *unlocks vestauth inside code!*
+or install globally - *unlocks vestauth for any agent, agent tool, or agent framework!*
 
-<details><summary>with npm 📦</summary><br>
+<details><summary>with curl 🌐 </summary><br>
 
 ```sh
-npm install vestauth --save
+curl -sfS https://vestauth.sh | sh
+vestauth help
 ```
 
+[![curl installs](https://img.shields.io/endpoint?url=https://vestauth.sh/stats/curl&label=curl%20installs)](https://github.com/vestauth/vestauth.sh/blob/main/install.sh)
+
 &nbsp;
 
 </details>
 
-## Agent
+<details><summary>with github releases 🐙</summary><br>
+
+```sh
+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 help
+```
+
+[![github releases](https://img.shields.io/github/downloads/vestauth/vestauth/total)](https://github.com/vestauth/vestauth/releases)
+
+&nbsp;
+
+</details>
 
-> Initialize your agent and make authenticated curl calls to vestauth providers.
+<details><summary>or windows 🪟</summary><br>
+
+Download [the windows executable](https://github.com/vestauth/vestauth/releases) directly from the [releases page](https://github.com/vestauth/vestauth/releases).
+
+> * [vestauth-windows-amd64.zip
+](https://github.com/vestauth/releases/raw/main/latest/vestauth-windows-amd64.zip)
+> * [vestauth-windows-x86_64.zip
+](https://github.com/vestauth/releases/raw/main/latest/vestauth-windows-x86_64.zip)
+
+(unzip to extract `vestauth.exe`)
+
+</details>
+
+&nbsp;
+
+## Identity
+
+> Give your agent its cryptographic identity. 
 
 ```sh
+$ mkdir your-agent
+$ cd your-agent
+
 $ vestauth agent init
-$ vestauth agent curl https://ping.vestauth.com/ping
+✔ agent created (.env/AGENT_ID=agent-4b94ccd425e939fac5016b6b)
 ```
 
-More examples
+<details><summary>learn more</summary><br>
 
-*coming soon*
+This populates a `.env` file with an `AGENT_PUBLIC_JWK`, `AGENT_PRIVATE_JWK`, and `AGENT_ID`.
 
-## Provider
+```ini
+# example
+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_ID="agent-4b94ccd425e939fac5016b6b"
+```
 
-> As a provider of agentic tools, authenticate agents through cryptographic verification.
+* The `AGENT_PUBLIC_KEY` is auto-hosted to its own [`/.well-known/http-message-signatures-directory`](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-04#appendix-A) for discovery purposes.
+* The `AGENT_PRIVATE_KEY` must NOT be shared and is used to sign requests according to [RFC 9421](https://datatracker.ietf.org/doc/rfc9421/).
+* The `AGENT_ID` contributes to building the [FQDN for the `Signature-Agent` header](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-01#name-request-with-http-signature).
+
+</details>
+
+&nbsp;
+
+## Authentication
+
+> Turn any curl request into a signed, authenticated request.
 
 ```sh
-$ vestauth provider verify GET https://ping.vestauth.com/ping
+> without vestauth
+$ curl https://api.vestauth.com/whoami
+{"error":{"status":400,"code":null,"message":"bad_request","help":null,"meta":null}}
+
+> with vestauth
+$ vestauth agent curl https://api.vestauth.com/whoami
+{"uid":"agent-4b94ccd425e939fac5016b6b",...}
 ```
 
-More examples
+<details><summary>learn more</summary><br>
 
-* Express.js
-* Next.js
-* Rails
-* ...
+Vestauth autosigns each curl request – injecting valid signed headers according to the [web-bot-auth draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture). View these with the built-in `headers` primitive.
 
-### List of current providers
+```
+$ 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.agents.vestauth.com"
+}
+```
 
-* `dotenvx as2` – agentic secret storage
+</details>
+
+&nbsp;
+
+## Verification 
+
+> As a provider of agentic tools, authenticate agents through cryptographic verification.
+
+```sh
+
+```
 
 ## Advanced
 

package/package.json

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

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

@@ -2,37 +2,44 @@ const { logger } = require('./../../../shared/logger')
 const agent = require('./../../../lib/agent')
 const execute = require('./../../../lib/helpers/execute')
 const findUrl = require('./../../../lib/helpers/findUrl')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
 
 async function curl () {
-  const commandArgs = this.args
-  logger.debug(`process command [${commandArgs.join(' ')}]`)
-
-  const options = this.opts()
-  logger.debug(`options: ${JSON.stringify(options)}`)
-
-  const httpMethod = 'GET'
-  const url = findUrl(commandArgs)
-  const headers = await agent.headers(httpMethod, url)
-  const injected = [
-    'curl',
-    '-H', `Signature: ${headers.Signature}`,
-    '-H', `Signature-Input: ${headers['Signature-Input']}`,
-    ...commandArgs
-  ]
-
-  const { stdout, exitCode } = await execute.execa(injected[0], injected.slice(1), {})
-
-  if (exitCode !== 0) {
-    logger.debug(`received exitCode ${exitCode}`)
-    throw new Error(`Command exited with exit code ${exitCode}`)
+  try {
+    const commandArgs = this.args
+    logger.debug(`process command [${commandArgs.join(' ')}]`)
+
+    const options = this.opts()
+    logger.debug(`options: ${JSON.stringify(options)}`)
+
+    const httpMethod = 'GET'
+    const url = findUrl(commandArgs)
+    const headers = await agent.headers(httpMethod, url)
+    const injected = [
+      'curl',
+      '-H', `Signature: ${headers.Signature}`,
+      '-H', `Signature-Input: ${headers['Signature-Input']}`,
+      '-H', `Signature-Agent: ${headers['Signature-Agent']}`,
+      ...commandArgs
+    ]
+
+    const { stdout, exitCode } = await execute.execa(injected[0], injected.slice(1), {})
+
+    if (exitCode !== 0) {
+      logger.debug(`received exitCode ${exitCode}`)
+      throw new Error(`Command exited with exit code ${exitCode}`)
+    }
+
+    let space = 0
+    if (options.prettyPrint) {
+      space = 2
+    }
+
+    console.log(JSON.stringify(JSON.parse(stdout), null, space))
+  } catch (error) {
+    catchAndLog(error)
+    process.exit(1)
   }
-
-  let space = 0
-  if (options.prettyPrint) {
-    space = 2
-  }
-
-  console.log(JSON.stringify(JSON.parse(stdout), null, space))
 }
 
 module.exports = curl

package/src/lib/helpers/authorityMessage.js

@@ -2,6 +2,13 @@ function authorityMessage (uri, signatureParams) {
   const u = new URL(uri)
   const authority = u.host // includes port if present
 
+  // other possible message (target-uri, and signature-params)
+  // const message = [
+  //   `"@method": ${method.toUpperCase()}`,
+  //   `"@target-uri": ${uri}`,
+  //   `"@signature-params": ${signatureParams}`
+  // ].join('\n')
+
   return [
     `"@authority": ${authority}`,
     `"@signature-params": ${signatureParams}`

package/src/lib/helpers/errors.js

@@ -36,6 +36,17 @@ class Errors {
     return e
   }
 
+  invalidSignatureAgent () {
+    const code = 'INVALID_SIGNATURE_AGENT'
+    const message = `[${code}] invalid --signature-agent`
+    const help = `[${code}] https://github.com/vestauth/vestauth/issues/11`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    return e
+  }
+
   econnrefused () {
     const code = 'ECONNREFUSED'
     const message = `[${code}] connection refused`

package/src/lib/helpers/headers.js

@@ -33,7 +33,7 @@ async function headers (httpMethod, uri, id, privateJwk, tag = 'web-bot-auth', n
 
   const signatureInput = signatureParams(privateJwk.kid, tag, nonce)
   const signature = webBotAuthSignature(httpMethod, uri, signatureInput, privateJwk)
-  const signatureAgent = `https://${id}.agents.vestauth.com` // https://agent-1234.agents.vestauth.com/.well-known/http-message-signatures-directory
+  const signatureAgent = `${id}.agents.vestauth.com` // agent-1234.agents.vestauth.com (no scheme) /.well-known/http-message-signatures-directory
 
   return {
     Signature: `sig1=:${signature}:`,

package/src/lib/helpers/parseSignatureAgentHeader.js

@@ -1,13 +1,14 @@
 const { parseDictionary } = require('structured-headers')
+const Errors = require('./errors')
 
 // example: sig1=https://agent-9aa52a556ca85ee195866c0b.agents.vestauth.com
 function parseSignatureAgentHeader (signatureAgentHeader) {
   const dictionary = parseDictionary(signatureAgentHeader)
   const entry = dictionary.entries().next()
-  if (entry.done) throw new Error('Invalid Signature-Agent header: empty dictionary')
+  if (entry.done) throw new Errors().invalidSignatureAgent()
   const [key, innerlist] = entry.value
   const value = innerlist[0].value
-  if (!value) throw new Error('Invalid Signature-Agent header: expected a URL string')
+  if (!value) throw new Errors().invalidSignatureAgent()
 
   return {
     key,

package/src/lib/helpers/providerVerify.js

@@ -1,13 +1,18 @@
 const { http } = require('./http')
 const buildApiError = require('./buildApiError')
 const parseSignatureAgentHeader = require('./parseSignatureAgentHeader')
+const verifyAgentFqdn = require('./verifyAgentFqdn')
 const verify = require('./verify')
 
-async function providerVerify (httpMethod = 'GET', uri = 'https://api.vestauth.com/whoami', headers = {}) {
-  const signatureAgent = headers['Signature-Agent']
-  const { value } = parseSignatureAgentHeader(signatureAgent) // sig1=https://agent-9aa52a556ca85ee195866c0b.agents.vestauth.com
+async function providerVerify (httpMethod, uri, headers = {}) {
+  const signatureAgent = headers['Signature-Agent'] || headers['signature-agent'] // support either case (expressjs lowers headers)
+  const { value } = parseSignatureAgentHeader(signatureAgent) // sig1=agent-1234.agents.vestauth.com
+  const fqdn = value
+  verifyAgentFqdn(fqdn)
+  const origin = `https://${fqdn}` // https://agent-1234.agents.vestauth.com
 
-  const url = `${value}/.well-known/http-message-signatures-directory`
+  // get jwks from .well-known
+  const url = `${origin}/.well-known/http-message-signatures-directory` // risk of SSRF ?
   const resp = await http(url, { method: 'GET', headers: { 'Content-Type': 'application/json' } })
   if (resp.statusCode >= 400) {
     const json = await resp.body.json()
@@ -26,6 +31,8 @@ async function providerVerify (httpMethod = 'GET', uri = 'https://api.vestauth.c
   //     }
   //   ]
   // }
+
+  // use publicJwk to verify
   const publicJwk = json.keys[0]
   const output = await verify(httpMethod, uri, headers, publicJwk)
 

package/src/lib/helpers/verify.js

@@ -6,8 +6,8 @@ const authorityMessage = require('./authorityMessage')
 const publicJwkObject = require('./publicJwkObject')
 
 function verify (httpMethod, uri, headers = {}, publicJwk) {
-  const signature = headers.Signature
-  const signatureInput = headers['Signature-Input']
+  const signature = headers.Signature || headers.signature
+  const signatureInput = headers['Signature-Input'] || headers['signature-input']
 
   const { values } = parseSignatureInputHeader(signatureInput)
   const { expires } = values

package/src/lib/helpers/verifyAgentFqdn.js

@@ -0,0 +1,28 @@
+const DEFAULT_PROVIDER_FQDN_REGEX = /^[A-Za-z0-9-]+\.agents\.vestauth\.com$/
+const Errors = require('./errors')
+
+function getProviderFqdnRegex () {
+  const override = process.env.PROVIDER_FQDN_REGEX
+  if (!override) return DEFAULT_PROVIDER_FQDN_REGEX
+
+  try {
+    return new RegExp(override)
+  } catch {
+    return DEFAULT_PROVIDER_FQDN_REGEX
+  }
+}
+
+function verifyAgentFqdn (fqdn) {
+  if (!fqdn || typeof fqdn !== 'string') {
+    throw new Errors().invalidSignatureAgent()
+  }
+
+  const pattern = getProviderFqdnRegex()
+  if (!pattern.test(fqdn)) {
+    throw new Errors().invalidSignatureAgent()
+  }
+
+  return true
+}
+
+module.exports = verifyAgentFqdn

package/src/lib/helpers/webBotAuthSignature.js

@@ -5,12 +5,6 @@ const authorityMessage = require('./authorityMessage')
 function webBotAuthSignature (method = 'GET', uri = '', signatureParams, privateJwk) {
   const message = authorityMessage(uri, signatureParams)
 
-  // const message = [
-  //   `"@method": ${method.toUpperCase()}`,
-  //   `"@target-uri": ${uri}`,
-  //   `"@signature-params": ${signatureParams}`
-  // ].join('\n')
-
   return crypto.sign(
     null,
     Buffer.from(message, 'utf8'),