vestauth 0.6.0 → 0.7.1

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.5.3...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.7.1...main)
+
+## [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)
+
+### Changed
+
+* Change `key` terms to `jwk` for clarity ([#9](https://github.com/vestauth/vestauth/pull/9))
 
 ## [0.6.0](https://github.com/vestauth/vestauth/compare/v0.5.3...v0.6.0) (2026-02-03)
 

package/README.md

@@ -4,6 +4,7 @@
 
 * identity
 * authentication
+* verification
 
  
 

package/package.json

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

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

@@ -9,7 +9,7 @@ async function headers (httpMethod, uri) {
   const options = this.opts()
   logger.debug(`options: ${JSON.stringify(options)}`)
 
-  const output = await agent.headers(httpMethod, uri, options.id, options.privateKey, options.tag, options.nonce)
+  const output = await agent.headers(httpMethod, uri, options.id, options.privateJwk, options.tag, options.nonce)
 
   let space = 0
   if (options.prettyPrint) {

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

@@ -11,7 +11,7 @@ async function headers (httpMethod, uri) {
     const options = this.opts()
     logger.debug(`options: ${JSON.stringify(options)}`)
 
-    const output = await primitives.headers(httpMethod, uri, options.id, options.privateKey, options.tag, options.nonce)
+    const output = await primitives.headers(httpMethod, uri, options.id, options.privateJwk, options.tag, options.nonce)
 
     let space = 0
     if (options.prettyPrint) {

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

@@ -6,11 +6,11 @@ function keypair () {
   const options = this.opts()
   logger.debug(`options: ${JSON.stringify(options)}`)
 
-  const kp = primitives.keypair(options.privateKey, options.prefix)
+  const kp = primitives.keypair(options.privateJwk, options.prefix)
 
   const output = {
-    public_key: kp.publicKey,
-    private_key: kp.privateKey
+    public_jwk: kp.publicJwk,
+    private_jwk: kp.privateJwk
   }
 
   let space = 0

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

@@ -17,10 +17,10 @@ async function verify (httpMethod, uri) {
       'Signature-Agent': options.signatureAgent
     }
 
-    const publicJwk = JSON.parse(options.publicKey || {})
+    const publicJwk = JSON.parse(options.publicJwk || {})
 
     const output = await primitives.verify(httpMethod, uri, headers, publicJwk)
-    // const output = await primitive.verifyWebBotAuth(httpMethod, uri, signature, signatureInput, JSON.parse(publicKey))
+    // const output = await primitive.verifyWebBotAuth(httpMethod, uri, signature, signatureInput, JSON.parse(publicJwk))
 
     let space = 0
     if (options.prettyPrint) {

package/src/cli/commands/agent.js

@@ -32,7 +32,7 @@ agent.command('headers')
   .argument('<httpMethod>', 'GET (default)')
   .argument('<uri>', '')
   .option('--id <id>', 'id (string)', env('AGENT_ID'))
-  .option('--privateKey <privateKey>', 'AGENT_PUBLIC_KEY (default)', env('AGENT_PRIVATE_KEY'))
+  .option('--privateJwk <privateJwk>', 'AGENT_PRIVATE_JWK (default)', env('AGENT_PRIVATE_JWK'))
   .option('--tag <tag>', 'web-bot-auth (default) | web-bot-auth', 'web-bot-auth')
   .option('--nonce <nonce>', 'null (default)')
   .option('--pp, --pretty-print', 'pretty print output')

package/src/cli/commands/primitives.js

@@ -11,7 +11,7 @@ primitives
 const keypairAction = require('./../actions/primitives/keypair')
 primitives.command('keypair')
   .description('generate public/private keypair')
-  .option('--private-key <privateKey>', 'pre-existing private key')
+  .option('--private-jwk <privateJwk>', 'pre-existing private JWK')
   .option('--prefix <type>', 'agent (default) | provider | none', 'agent')
   .option('--pp, --pretty-print', 'pretty print output')
   .action(keypairAction)
@@ -23,7 +23,7 @@ primitives.command('headers')
   .argument('<httpMethod>', 'GET (default)')
   .argument('<uri>', '')
   .option('--id <id>', 'id (string)', env('AGENT_ID'))
-  .option('--private-key <privateKey>', 'private key (json string)', env('AGENT_PRIVATE_KEY'))
+  .option('--private-jwk <privateJwk>', 'private JWK (json string)', env('AGENT_PRIVATE_JWK'))
   .option('--tag <tag>', 'web-bot-auth (default) | web-bot-auth', 'web-bot-auth')
   .option('--nonce <nonce>', 'null (default)')
   .option('--pp, --pretty-print', 'pretty print output')
@@ -38,7 +38,7 @@ primitives.command('verify')
   .requiredOption('--signature <signature>', '')
   .requiredOption('--signature-input <signatureInput>', '')
   .option('--signature-agent <signatureAgent>', '')
-  .option('--public-key <publicKey>', 'public key (json string)', env('AGENT_PUBLIC_KEY'))
+  .option('--public-jwk <publicJwk>', 'public JWK (json string)', env('AGENT_PUBLIC_JWK'))
   .option('--pp, --pretty-print', 'pretty print output')
   .action(verifyAction)
 

package/src/lib/helpers/agentHeaders.js

@@ -1,16 +1,16 @@
 const headers = require('./headers')
 const identity = require('./identity')
 
-async function agentHeaders (httpMethod, uri, id = null, privateKey = null, tag = 'web-bot-auth', nonce = null) {
-  if (!privateKey) {
-    privateKey = identity().privateKey
+async function agentHeaders (httpMethod, uri, id = null, privateJwk = null, tag = 'web-bot-auth', nonce = null) {
+  if (!privateJwk) {
+    privateJwk = identity().privateJwk
   }
 
   if (!id) {
     id = identity().id
   }
 
-  return await headers(httpMethod, uri, id, privateKey, tag, nonce)
+  return await headers(httpMethod, uri, id, privateJwk, tag, nonce)
 }
 
 module.exports = agentHeaders

package/src/lib/helpers/agentInit.js

@@ -8,21 +8,21 @@ async function agentInit () {
   const envPath = '.env'
 
   // keypair
-  const currentPrivateKey = identity(false).privateKey
-  const kp = keypair(currentPrivateKey, 'agent')
+  const currentPrivateJwk = identity(false).privateJwk
+  const kp = keypair(currentPrivateJwk, 'agent')
 
   touch(envPath)
 
   // must come before registration so that registration can send headers
-  dotenvx.set('AGENT_PUBLIC_KEY', JSON.stringify(kp.publicKey), { path: envPath, plain: true, quiet: true })
-  dotenvx.set('AGENT_PRIVATE_KEY', JSON.stringify(kp.privateKey), { path: envPath, plain: true, quiet: true })
+  dotenvx.set('AGENT_PUBLIC_JWK', JSON.stringify(kp.publicJwk), { path: envPath, plain: true, quiet: true })
+  dotenvx.set('AGENT_PRIVATE_JWK', JSON.stringify(kp.privateJwk), { path: envPath, plain: true, quiet: true })
 
   // register agent
-  const agent = await new PostRegister(null, kp.publicKey).run()
+  const agent = await new PostRegister(null, kp.publicJwk).run()
   dotenvx.set('AGENT_ID', agent.uid, { path: envPath, plain: true, quiet: true })
 
   return {
-    AGENT_PUBLIC_KEY: kp.publicKey,
+    AGENT_PUBLIC_JWK: kp.publicJwk,
     AGENT_ID: agent.uid,
     path: envPath,
     isNew: agent.is_new

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

@@ -14,9 +14,9 @@ class Errors {
     return e
   }
 
-  missingPrivateKey () {
-    const code = 'MISSING_PRIVATE_KEY'
-    const message = `[${code}] missing --private-key (AGENT_PRIVATE_KEY)`
+  missingPrivateJwk () {
+    const code = 'MISSING_PRIVATE_JWK'
+    const message = `[${code}] missing --private-jwk (AGENT_PRIVATE_JWK)`
     const help = `[${code}] https://github.com/vestauth/vestauth/issues/5`
 
     const e = new Error(message)
@@ -25,9 +25,9 @@ class Errors {
     return e
   }
 
-  invalidPrivateKey () {
-    const code = 'INVALID_PRIVATE_KEY'
-    const message = `[${code}] invalid --private-key (AGENT_PRIVATE_KEY)`
+  invalidPrivateJwk () {
+    const code = 'INVALID_PRIVATE_JWK'
+    const message = `[${code}] invalid --private-jwk (AGENT_PRIVATE_JWK)`
     const help = `[${code}] https://github.com/vestauth/vestauth/issues/7`
 
     const e = new Error(message)
@@ -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

@@ -3,18 +3,17 @@ const thumbprint = require('./thumbprint')
 const signatureParams = require('./signatureParams')
 const webBotAuthSignature = require('./webBotAuthSignature')
 
-async function headers (httpMethod, uri, id, privateKey, tag = 'web-bot-auth', nonce = null) {
+async function headers (httpMethod, uri, id, privateJwk, tag = 'web-bot-auth', nonce = null) {
   if (!id) throw new Errors().missingId()
-  if (!privateKey) throw new Errors().missingPrivateKey()
+  if (!privateJwk) throw new Errors().missingPrivateJwk()
 
-  let privateJwk
   try {
-    privateJwk = JSON.parse(privateKey)
+    privateJwk = JSON.parse(privateJwk)
   } catch {
-    throw new Errors().invalidPrivateKey()
+    throw new Errors().invalidPrivateJwk()
   }
   if (!privateJwk || typeof privateJwk !== 'object') {
-    throw new Errors().invalidPrivateKey()
+    throw new Errors().invalidPrivateJwk()
   }
 
   const kid = thumbprint(privateJwk)
@@ -25,7 +24,7 @@ async function headers (httpMethod, uri, id, privateKey, tag = 'web-bot-auth', n
   // const now = new Date()
   // return await signatureHeaders(
   //   request,
-  //   await signerFromJWK(JSON.parse(privateKey)),
+  //   await signerFromJWK(JSON.parse(privateJwk)),
   //   {
   //     created: now,
   //     expires: new Date(now.getTime() + 300_000), // now + 5 min
@@ -34,7 +33,7 @@ async function headers (httpMethod, uri, id, privateKey, 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/identity.js

@@ -1,16 +1,16 @@
 const env = require('./env')
 
 function identity (raiseError = true) {
-  const publicKey = env('AGENT_PUBLIC_KEY')
-  const privateKey = env('AGENT_PRIVATE_KEY')
+  const publicJwk = env('AGENT_PUBLIC_JWK')
+  const privateJwk = env('AGENT_PRIVATE_JWK')
   const id = env('AGENT_ID')
 
-  if (raiseError && id && !(publicKey || !privateKey)) throw new Error('missing AGENT_PUBLIC_KEY,  AGENT_PRIVATE_KEY, or AGENT_ID. Run [vestauth agent init]')
+  if (raiseError && id && !(publicJwk || !privateJwk)) throw new Error('missing AGENT_PUBLIC_JWK, AGENT_PRIVATE_JWK, or AGENT_ID. Run [vestauth agent init]')
 
   return {
     id,
-    publicKey,
-    privateKey
+    publicJwk,
+    privateJwk
   }
 }
 

package/src/lib/helpers/keypair.js

@@ -2,11 +2,11 @@ const crypto = require('crypto')
 
 const thumbprint = require('./thumbprint')
 
-function keypair (existingPrivateKey, prefix = 'agent') {
+function keypair (existingPrivateJwk, prefix = 'agent') {
   let publicJwk
   let privateJwk
 
-  if (existingPrivateKey) {
+  if (existingPrivateJwk) {
     // example
     // {
     //   "crv": "Ed25519",
@@ -15,9 +15,9 @@ function keypair (existingPrivateKey, prefix = 'agent') {
     //   "kty": "OKP",
     //   "kid": "rBE7_zLOVYk4oYEdI-01qpXHWNMyZYD-4LEf6HiyZ9Q"
     // }
-    // (publicKey just remove 'd')
+    // (publicJwk just remove 'd')
 
-    privateJwk = JSON.parse(existingPrivateKey)
+    privateJwk = JSON.parse(existingPrivateJwk)
     publicJwk = {
       crv: privateJwk.crv,
       x: privateJwk.x,
@@ -42,8 +42,8 @@ function keypair (existingPrivateKey, prefix = 'agent') {
   }
 
   return {
-    publicKey: publicJwk,
-    privateKey: privateJwk
+    publicJwk,
+    privateJwk
   }
 }
 

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/privateJwkObject.js

@@ -0,0 +1,7 @@
+const crypto = require('crypto')
+
+function privateJwkObject (privateJwk) {
+  return crypto.createPrivateKey({ key: privateJwk, format: 'jwk' })
+}
+
+module.exports = privateJwkObject

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 = {}) {
+async function providerVerify (httpMethod, uri, headers = {}) {
   const signatureAgent = headers['Signature-Agent']
-  const { value } = parseSignatureAgentHeader(signatureAgent) // sig1=https://agent-9aa52a556ca85ee195866c0b.agents.vestauth.com
+  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/{publicKeyObject.js → publicJwkObject.js}

@@ -1,7 +1,7 @@
 const crypto = require('crypto')
 
-function publicKeyObject (publicJwk) {
+function publicJwkObject (publicJwk) {
   return crypto.createPublicKey({ key: publicJwk, format: 'jwk' })
 }
 
-module.exports = publicKeyObject
+module.exports = publicJwkObject

package/src/lib/helpers/verify.js

@@ -3,7 +3,7 @@ const crypto = require('crypto')
 const parseSignatureInputHeader = require('./parseSignatureInputHeader')
 const stripDictionaryKey = require('./stripDictionaryKey')
 const authorityMessage = require('./authorityMessage')
-const publicKeyObject = require('./publicKeyObject')
+const publicJwkObject = require('./publicJwkObject')
 
 function verify (httpMethod, uri, headers = {}, publicJwk) {
   const signature = headers.Signature
@@ -26,7 +26,7 @@ function verify (httpMethod, uri, headers = {}, publicJwk) {
   const success = crypto.verify(
     null,
     Buffer.from(message, 'utf8'),
-    publicKeyObject(publicJwk),
+    publicJwkObject(publicJwk),
     Buffer.from(sig, 'base64')
   )
 

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/verifyWebBotAuth.js

@@ -1,10 +1,10 @@
 const { verify } = require('web-bot-auth')
 const { verifierFromJWK } = require('web-bot-auth/crypto')
 
-async function verifyWebBotAuth (httpMethod, uri, signatureHeader, signatureInputHeader, publicKey) {
+async function verifyWebBotAuth (httpMethod, uri, signatureHeader, signatureInputHeader, publicJwk) {
   let success = false
 
-  const verifier = await verifierFromJWK(publicKey)
+  const verifier = await verifierFromJWK(publicJwk)
   const signedRequest = new Request(uri, {
     headers: {
       Signature: signatureHeader,

package/src/lib/helpers/webBotAuthSignature.js

@@ -1,22 +1,14 @@
 const crypto = require('crypto')
-const edPrivateKeyObject = require('./edPrivateKeyObject')
+const privateJwkObject = require('./privateJwkObject')
 const authorityMessage = require('./authorityMessage')
 
-function webBotAuthSignature (method = 'GET', uri = '', signatureParams, privateKey) {
+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')
-
-  const privateKeyObject = edPrivateKeyObject(privateKey)
-
   return crypto.sign(
     null,
     Buffer.from(message, 'utf8'),
-    privateKeyObject
+    privateJwkObject(privateJwk)
   ).toString('base64')
 }
 

package/src/lib/helpers/edPrivateKeyObject.js

@@ -1,7 +0,0 @@
-const crypto = require('crypto')
-
-function edPrivateKeyObject (keyJson) {
-  return crypto.createPrivateKey({ key: keyJson, format: 'jwk' })
-}
-
-module.exports = edPrivateKeyObject