vestauth 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -2,9 +2,16 @@
 
 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.11.1...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.12.0...main)
 
-## [0.11.1](https://github.com/vestauth/vestauth/compare/v0.11.0...v0.11.1) (2026-02-17)
+## [0.12.0](https://github.com/vestauth/vestauth/compare/v0.11.2...v0.12.0) (2026-02-17)
+
+### Added
+
+* Add `--hostname` flag for `agent init` ([#17](https://github.com/vestauth/vestauth/pull/17) & [#18](https://github.com/vestauth/vestauth/pull/18))
+* Add types file ([#16](https://github.com/vestauth/vestauth/pull/16))
+
+## [0.11.2](https://github.com/vestauth/vestauth/compare/v0.11.0...v0.11.2) (2026-02-17)
 
 ### Removed
 

package/README.md

@@ -208,6 +208,17 @@ $ vestauth agent init
 ⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]
 ```
 
+</details>
+<details><summary>`agent init --hostname`</summary><br>
+
+Use `--hostname` to override the agent API hostname (defaults to `AGENT_HOSTNAME`, then `api.vestauth.com`):
+
+```sh
+$ vestauth agent init --hostname https://vestauth.yoursite.com
+✔ agent created (.env/AGENT_UID=agent-609a4fd2ebf4e6347108c517)
+⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]
+```
+
 </details>
 <details><summary>`agent curl`</summary><br>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vestauth",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "auth for agents–from the creator of dotenvx",
   "keywords": [
     "vestauth",
@@ -23,8 +23,10 @@
   ],
   "license": "BSD-3-Clause",
   "main": "src/lib/main.js",
+  "types": "./src/lib/main.d.ts",
   "exports": {
     ".": {
+      "types": "./src/lib/main.d.ts",
       "require": "./src/lib/main.js",
       "default": "./src/lib/main.js"
     },

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

@@ -8,7 +8,7 @@ async function init () {
     const options = this.opts()
     logger.debug(`options: ${JSON.stringify(options)}`)
 
-    const output = await agent.init()
+    const output = await agent.init(options.hostname)
 
     if (output.isNew) {
       logger.success(`✔ agent created (${output.path}/AGENT_UID=${output.AGENT_UID})`)

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

@@ -10,7 +10,7 @@ async function rotate () {
     logger.debug(`options: ${JSON.stringify(options)}`)
 
     const uid = options.uid || options.id || env('AGENT_UID') || env('AGENT_ID')
-    const output = await agent.rotate(uid, options.privateJwk, options.tag, options.nonce)
+    const output = await agent.rotate(uid, options.privateJwk, options.tag, options.nonce, options.hostname)
 
     logger.success(`✔ agent keys rotated (${output.path}/AGENT_UID=${output.AGENT_UID})`)
     logger.help('⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]')

package/src/cli/commands/agent.js

@@ -11,6 +11,7 @@ agent
 const initAction = require('./../actions/agent/init')
 agent.command('init')
   .description('create agent')
+  .option('--hostname <hostname>', 'agent API hostname')
   .action(initAction)
 
 // vestauth agent curl
@@ -42,6 +43,7 @@ agent.command('rotate')
   .description('rotate keypair')
   .option('--uid, --id <uid>', 'uid (string)', env('AGENT_UID') || env('AGENT_ID'))
   .option('--private-jwk <privateJwk>', 'AGENT_PRIVATE_JWK (default)', env('AGENT_PRIVATE_JWK'))
+  .option('--hostname <hostname>', 'agent API hostname')
   .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/lib/helpers/agentInit.js

@@ -2,10 +2,13 @@ const dotenvx = require('@dotenvx/dotenvx')
 const identity = require('./identity')
 const keypair = require('./keypair')
 const touch = require('./touch')
+const normalizeAgentHostname = require('./normalizeAgentHostname')
 const PostRegister = require('../api/postRegister')
 
-async function agentInit () {
+async function agentInit (hostname = null) {
   const envPath = '.env'
+  const normalizedHostname = normalizeAgentHostname(hostname)
+  const shouldPersistHostname = Boolean(hostname && String(hostname).trim())
 
   // keypair
   const currentPrivateJwk = identity(false).privateJwk
@@ -16,9 +19,12 @@ async function agentInit () {
   // must come before registration so that registration can send headers
   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 })
+  if (shouldPersistHostname) {
+    dotenvx.set('AGENT_HOSTNAME', new URL(normalizedHostname).host, { path: envPath, plain: true, quiet: true })
+  }
 
   // register agent
-  const agent = await new PostRegister(null, kp.publicJwk).run()
+  const agent = await new PostRegister(normalizedHostname, kp.publicJwk).run()
   dotenvx.set('AGENT_UID', agent.uid, { path: envPath, plain: true, quiet: true })
 
   return {

package/src/lib/helpers/agentRotate.js

@@ -1,15 +1,17 @@
 const dotenvx = require('@dotenvx/dotenvx')
 const keypair = require('./keypair')
+const normalizeAgentHostname = require('./normalizeAgentHostname')
 const PostRotate = require('../api/postRotate')
 
-async function agentRotate (uid, privateJwk, tag = 'web-bot-auth', nonce = null) {
+async function agentRotate (uid, privateJwk, tag = 'web-bot-auth', nonce = null, hostname = null) {
   const envPath = '.env'
+  const rotateUrl = normalizeAgentHostname(hostname)
 
   // new keypair
   const newKp = keypair()
 
   // rotate jwk
-  const agent = await new PostRotate(null, newKp.publicJwk, uid, privateJwk).run()
+  const agent = await new PostRotate(rotateUrl, newKp.publicJwk, uid, privateJwk).run()
 
   dotenvx.set('AGENT_PUBLIC_JWK', JSON.stringify(newKp.publicJwk), { path: envPath, plain: true, quiet: true })
   dotenvx.set('AGENT_PRIVATE_JWK', JSON.stringify(newKp.privateJwk), { path: envPath, plain: true, quiet: true })

package/src/lib/helpers/normalizeAgentHostname.js

@@ -0,0 +1,13 @@
+function normalizeAgentHostname (hostname = null) {
+  const value = (hostname || process.env.AGENT_HOSTNAME || '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 = normalizeAgentHostname

package/src/lib/main.d.ts

@@ -0,0 +1,138 @@
+export type HttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'OPTIONS'
+  | 'HEAD'
+  | (string & {})
+
+export type HeaderValue = string | string[]
+export type HeaderBag = Record<string, HeaderValue | undefined>
+
+/** Minimal JWK shape used by Vestauth (Ed25519 OKP). */
+export interface OkpEd25519PublicJwk {
+  kty: 'OKP'
+  crv: 'Ed25519'
+  x: string
+  kid?: string
+  [prop: string]: unknown
+}
+
+/** Minimal private JWK shape used by Vestauth (Ed25519 OKP). */
+export interface OkpEd25519PrivateJwk extends OkpEd25519PublicJwk {
+  d: string
+}
+
+export type PublicJwk = OkpEd25519PublicJwk
+export type PrivateJwk = OkpEd25519PrivateJwk
+
+export interface Keypair {
+  publicJwk: PublicJwk
+  privateJwk: PrivateJwk
+}
+
+export interface SignatureHeaders {
+  Signature: string
+  'Signature-Input': string
+  'Signature-Agent': string
+}
+
+export interface VerifyResult {
+  uid?: string
+  kid?: string
+  public_jwk?: PublicJwk
+  well_known_url?: string
+}
+
+export interface AgentApi {
+  /**
+   * Creates (or reuses) an Ed25519 keypair, registers the agent, and writes to `.env`.
+   */
+  init(): Promise<{
+    AGENT_PUBLIC_JWK: PublicJwk
+    AGENT_UID: string
+    path: string
+    isNew: boolean
+  }>
+
+  /**
+   * Generates RFC 9421 request signature headers.
+   *
+   * When `uid` / `privateJwk` are omitted, Vestauth reads them from `.env`.
+   */
+  headers(
+    httpMethod: HttpMethod,
+    uri: string,
+    uid?: string | null,
+    privateJwk?: string | null,
+    tag?: string,
+    nonce?: string | null
+  ): Promise<SignatureHeaders>
+
+  /**
+   * Rotates the agent keypair and writes the new keys to `.env`.
+   */
+  rotate(
+    uid: string,
+    privateJwk: string,
+    tag?: string,
+    nonce?: string | null
+  ): Promise<{
+    AGENT_PUBLIC_JWK: PublicJwk
+    AGENT_UID: string
+    path: string
+  }>
+}
+
+export interface ProviderApi {
+  /**
+   * 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.
+   */
+  keypair(existingPrivateJwk?: string, prefix?: string): Keypair
+
+  /**
+   * Generates RFC 9421 request signature headers.
+   */
+  headers(
+    httpMethod: HttpMethod,
+    uri: string,
+    uid: string,
+    privateJwk: string,
+    tag?: string,
+    nonce?: string | null
+  ): Promise<SignatureHeaders>
+
+  /**
+   * Verifies a signed request.
+   *
+   * When `publicJwk` is not provided, Vestauth will attempt to resolve it via
+   * `Signature-Agent` discovery.
+   */
+  verify(
+    httpMethod: HttpMethod,
+    uri: string,
+    headers?: HeaderBag,
+    publicJwk?: PublicJwk
+  ): Promise<VerifyResult>
+}
+
+export const agent: AgentApi
+export const provider: ProviderApi
+export const primitives: PrimitivesApi
+
+declare const _default: {
+  agent: AgentApi
+  provider: ProviderApi
+  primitives: PrimitivesApi
+}
+
+export default _default