vestauth 0.17.0 → 0.18.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.17.0...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.18.0...main)
+
+## [0.18.0](https://github.com/vestauth/vestauth/compare/v0.17.0...v0.18.0) (2026-02-24)
+
+### Added
+
+* Add `vestauth server start` for running your own vestauth server ([#33](https://github.com/vestauth/vestauth/pull/33))
 
 ## [0.17.0](https://github.com/vestauth/vestauth/compare/v0.16.0...v0.17.0) (2026-02-23)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vestauth",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "auth for agents–from the creator of dotenvx",
   "keywords": [
     "vestauth",
@@ -52,8 +52,10 @@
     "express": "^4.21.2",
     "knex": "^3.1.0",
     "pg": "^8.18.0",
+    "sails-postgresql": "^5.0.1",
     "structured-headers": "^2.0.2",
-    "undici": "7.11.0"
+    "undici": "7.11.0",
+    "waterline": "^0.15.2"
   },
   "devDependencies": {
     "@yao-pkg/pkg": "^5.14.2",

package/src/cli/commands/server.js

@@ -1,6 +1,8 @@
 const { Command } = require('commander')
 const env = require('./../../lib/helpers/env')
 const databaseUrl = require('./../../lib/helpers/databaseUrl')
+const protocol = require('./../../lib/helpers/protocol')
+const hostname = require('./../../lib/helpers/hostname')
 
 const server = new Command('server')
 
@@ -13,6 +15,8 @@ const startAction = require('./../actions/server/start')
 server.command('start')
   .description('start vestauth server')
   .option('--port <port>', 'port', env('PORT'))
+  .option('--protocol <protocol>', 'https or http', protocol())
+  .option('--hostname <hostname>', 'localhost:3000', hostname())
   .option('--database-url <databaseUrl>', 'DATABASE_URL', databaseUrl())
   .action(startAction)
 

package/src/lib/helpers/dbCreate.js

@@ -1,4 +1,5 @@
 const knex = require('knex')
+const { logger } = require('../../shared/logger')
 
 function quoteIdentifier (value) {
   return `"${String(value).replace(/"/g, '""')}"`
@@ -41,10 +42,12 @@ async function dbCreate ({ databaseUrl } = {}) {
     const exists = Array.isArray(result.rows) && result.rows.length > 0
 
     if (exists) {
+      logger.info(`Database '${database}' already exists`)
       return { created: false, database }
     }
 
     await db.raw(`create database ${quoteIdentifier(database)}`)
+    logger.info(`Created database '${database}'`)
     return { created: true, database }
   } finally {
     await db.destroy()

package/src/lib/helpers/dbDrop.js

@@ -1,4 +1,5 @@
 const knex = require('knex')
+const { logger } = require('../../shared/logger')
 
 function quoteIdentifier (value) {
   return `"${String(value).replace(/"/g, '""')}"`
@@ -41,6 +42,7 @@ async function dbDrop ({ databaseUrl } = {}) {
     const exists = Array.isArray(result.rows) && result.rows.length > 0
 
     if (!exists) {
+      logger.info(`Database '${database}' does not exist`)
       return { dropped: false, database }
     }
 
@@ -51,6 +53,7 @@ async function dbDrop ({ databaseUrl } = {}) {
     )
 
     await db.raw(`drop database ${quoteIdentifier(database)}`)
+    logger.info(`Dropped database '${database}'`)
     return { dropped: true, database }
   } finally {
     await db.destroy()

package/src/lib/helpers/dbMigrate.js

@@ -1,6 +1,26 @@
 const path = require('path')
 const knex = require('knex')
 const Errors = require('./errors')
+const { logger } = require('../../shared/logger')
+
+function migrationLabel (filename) {
+  const base = String(filename).replace(/\.js$/, '')
+  const match = base.match(/^(\d+)_(.+)$/)
+
+  if (!match) return base
+
+  const version = match[1]
+  const name = match[2]
+    .split('_')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+
+  return `${version} ${name}`
+}
+
+function formatRailsTiming (ms) {
+  return `(${(ms / 1000).toFixed(4)}s)`
+}
 
 async function dbMigrate ({ databaseUrl } = {}) {
   const connection = databaseUrl
@@ -16,7 +36,50 @@ async function dbMigrate ({ databaseUrl } = {}) {
   })
 
   try {
-    const [batchNo, migrations] = await db.migrate.latest()
+    if (!db.migrate || typeof db.migrate.list !== 'function' || typeof db.migrate.up !== 'function') {
+      const startedAt = Date.now()
+      const [batchNo, migrations] = await db.migrate.latest()
+      const elapsedMs = Date.now() - startedAt
+
+      for (const migration of migrations) {
+        const label = migrationLabel(migration)
+        logger.info(`== ${label}: migrating ================================================`)
+        logger.info(`== ${label}: migrated ${formatRailsTiming(elapsedMs)} ===========================`)
+      }
+
+      return {
+        batchNo,
+        migrations
+      }
+    }
+
+    const [, pending] = await db.migrate.list()
+    const migrations = []
+    let batchNo = null
+
+    for (const pendingMigration of pending) {
+      const name = typeof pendingMigration === 'string'
+        ? pendingMigration
+        : pendingMigration.file || pendingMigration.name
+
+      const label = migrationLabel(name)
+      logger.info(`== ${label}: migrating ================================================`)
+
+      const startedAt = Date.now()
+      const [nextBatchNo, ran] = await db.migrate.up({ name })
+      batchNo = nextBatchNo
+      const elapsedMs = Date.now() - startedAt
+
+      logger.info(`== ${label}: migrated ${formatRailsTiming(elapsedMs)} ===========================`)
+
+      if (Array.isArray(ran)) {
+        migrations.push(...ran)
+      } else if (ran) {
+        migrations.push(ran)
+      } else {
+        migrations.push(name)
+      }
+    }
 
     return {
       batchNo,

package/src/lib/helpers/hostname.js

@@ -0,0 +1,7 @@
+const env = require('./env')
+
+function hostname () {
+  return env('HOSTNAME') || 'localhost:3000' // for server
+}
+
+module.exports = hostname

package/src/lib/helpers/protocol.js

@@ -0,0 +1,7 @@
+const env = require('./env')
+
+function protocol () {
+  return env('PROTOCOL') || 'http'
+}
+
+module.exports = protocol

package/src/lib/helpers/serverStart.js

@@ -1,4 +1,4 @@
-const serverIndex = require('./../server/index')
+const serverIndex = require('./../../server/index')
 
 function serverStart ({ port, databaseUrl }) {
   return serverIndex.start({ port, databaseUrl })

package/src/lib/server.js

@@ -2,9 +2,11 @@ const serverStart = require('./helpers/serverStart')
 const dbCreate = require('./helpers/dbCreate')
 const dbMigrate = require('./helpers/dbMigrate')
 const dbDrop = require('./helpers/dbDrop')
+const serverIndex = require('./../server/index')
 
 module.exports = {
   start: serverStart,
+  close: serverIndex.close,
   db: {
     create: dbCreate,
     migrate: dbMigrate,

package/src/server/index.js

@@ -0,0 +1,203 @@
+const { logger } = require('./../shared/logger')
+const tool = require('./../lib/tool')
+const primitives = require('./../lib/primitives')
+const { connectOrm } = require('./models/index')
+
+const express = require('express')
+
+const app = express()
+let ORM = null
+let HTTP_SERVER = null
+let CLOSE_PROMISE = null
+let SIGNAL_HANDLERS_INSTALLED = false
+let SIGNAL_HANDLERS = null
+app.use(express.json())
+
+app.use((req, res, next) => {
+  const hostNoPort = (req.headers.host || '').split(':')[0].toLowerCase()
+
+  // agent-c235... .localhost
+  if (hostNoPort.endsWith('.localhost')) {
+    let sub = hostNoPort.slice(0, -'.localhost'.length) // "agent-c235..."
+
+    // remove "agent-" prefix if present
+    if (sub.startsWith('agent-')) {
+      sub = sub.slice('agent-'.length)
+    }
+
+    req.agentUid = sub
+
+    return next()
+  }
+
+  next()
+})
+
+app.get('/', (req, res) => {
+  if (req.agentUid) {
+    res.json({ uid: req.agentUid })
+  } else {
+    res.json({ hello: 'vestauth' })
+  }
+})
+
+app.post('/register', async (req, res) => {
+  try {
+    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
+    const verified = await primitives.verify(req.method, url, req.headers, req.body.public_jwk)
+
+    const agent = await app.models.agent.create().fetch()
+
+    const attrs = {
+      agent: agent.id,
+      kid: verified.kid,
+      value: verified.public_jwk
+    }
+    const publicJwk = await app.models.public_jwk.create(attrs).fetch()
+    const agentFormatted = agent.toJSON()
+
+    res.json({
+      uid: agentFormatted.uidFormatted,
+      kid: publicJwk.kid,
+      public_jwk: verified.public_jwk,
+      is_new: true
+    })
+  } catch (err) {
+    logger.error(err)
+    res.status(401).json({ error: { status: 401, code: 401, message: err.message } })
+  }
+})
+
+app.get('/.well-known/http-message-signatures-directory', async (req, res) => {
+  const agent = await app.models.agent.findOne({ uid: req.agentUid })
+  if (!agent) {
+    return res.status(404).json({ error: { status: 404, code: 404, message: 'not found' } })
+  }
+
+  const jwks = await app.models.public_jwk.find({ agent: agent.id, state: 'active' })
+  const keys = jwks.map(j => j.value)
+
+  return res.json({ keys })
+})
+
+app.get('/whoami', async (req, res) => {
+  try {
+    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
+    const verified = await tool.verify(req.method, url, req.headers)
+
+    res.json(verified)
+  } catch (err) {
+    logger.error(err)
+    res.status(401).json({ error: { status: 401, code: 401, message: err.message } })
+  }
+})
+
+async function start ({ port, databaseUrl } = {}) {
+  const PORT = port || '3000'
+
+  if (HTTP_SERVER) return HTTP_SERVER
+
+  try {
+    const { orm, config } = connectOrm({ databaseUrl })
+
+    // promisify initialize
+    const db = await new Promise((resolve, reject) => {
+      orm.initialize(config, (err, ontology) => {
+        if (err) return reject(err)
+        resolve(ontology)
+      })
+    })
+
+    ORM = orm
+    app.models = db.collections
+
+    HTTP_SERVER = await new Promise((resolve, reject) => {
+      const server = app.listen(PORT, () => {
+        logger.success(`vestauth server listening on http://localhost:${PORT}`)
+        resolve(server)
+      })
+
+      server.once('error', reject)
+    })
+
+    installSignalHandlers()
+
+    return HTTP_SERVER
+  } catch (error) {
+    await close().catch(() => {})
+    throw error
+  }
+}
+
+async function close () {
+  if (CLOSE_PROMISE) return CLOSE_PROMISE
+
+  CLOSE_PROMISE = (async () => {
+    removeSignalHandlers()
+
+    if (HTTP_SERVER) {
+      await new Promise((resolve, reject) => {
+        HTTP_SERVER.close((err) => {
+          if (err) return reject(err)
+          resolve()
+        })
+      })
+      HTTP_SERVER = null
+    }
+
+    if (ORM) {
+      await new Promise((resolve, reject) => {
+        ORM.teardown((err) => {
+          if (err) return reject(err)
+          resolve()
+        })
+      })
+      ORM = null
+    }
+
+    delete app.models
+  })()
+
+  try {
+    await CLOSE_PROMISE
+  } finally {
+    CLOSE_PROMISE = null
+  }
+}
+
+function installSignalHandlers () {
+  if (SIGNAL_HANDLERS_INSTALLED) return
+
+  const shutdown = () => {
+    close()
+      .then(() => process.exit(0))
+      .catch((err) => {
+        logger.error(err)
+        process.exit(1)
+      })
+  }
+
+  SIGNAL_HANDLERS = {
+    SIGINT: () => shutdown('SIGINT'),
+    SIGTERM: () => shutdown('SIGTERM')
+  }
+
+  process.once('SIGINT', SIGNAL_HANDLERS.SIGINT)
+  process.once('SIGTERM', SIGNAL_HANDLERS.SIGTERM)
+  SIGNAL_HANDLERS_INSTALLED = true
+}
+
+function removeSignalHandlers () {
+  if (!SIGNAL_HANDLERS_INSTALLED || !SIGNAL_HANDLERS) return
+
+  process.removeListener('SIGINT', SIGNAL_HANDLERS.SIGINT)
+  process.removeListener('SIGTERM', SIGNAL_HANDLERS.SIGTERM)
+  SIGNAL_HANDLERS = null
+  SIGNAL_HANDLERS_INSTALLED = false
+}
+
+module.exports = {
+  app,
+  start,
+  close
+}

package/src/server/models/agent.js

@@ -0,0 +1,47 @@
+const crypto = require('crypto')
+const Waterline = require('waterline')
+
+const protocol = require('./../../lib/helpers/protocol')
+const hostname = require('./../../lib/helpers/hostname')
+
+const Agent = Waterline.Collection.extend({
+  identity: 'agent',
+  tableName: 'agents',
+  datastore: 'default',
+  primaryKey: 'id',
+  schema: true,
+
+  attributes: {
+    id: { type: 'number', autoMigrations: { autoIncrement: true } },
+    uid: { type: 'string', required: false },
+    createdAt: { columnName: 'created_at', type: 'ref', autoCreatedAt: true },
+    updatedAt: { columnName: 'updated_at', type: 'ref', autoUpdatedAt: true },
+
+    // relationships
+    publicJwks: {
+      collection: 'public_jwk',
+      via: 'agent'
+    }
+  },
+
+  beforeCreate (self, next) {
+    if (!self.uid) {
+      const uid = crypto.randomBytes(12).toString('hex')
+      self.uid = uid
+    }
+    next()
+  },
+
+  customToJSON () {
+    const self = this
+
+    self.uidFormatted = `agent-${self.uid}`
+    self.wellKnownUrl = `${protocol()}://${self.uidFormatted}.${hostname()}/.well-known/http-message-signatures-directory`
+    // remove fields if needed
+    // delete self.privateKey
+
+    return self
+  }
+})
+
+module.exports = Agent

package/src/server/models/index.js

@@ -0,0 +1,31 @@
+const Waterline = require('waterline')
+const sailsPostgresAdapter = require('sails-postgresql')
+
+const Agent = require('./agent')
+const PublicJwk = require('./publicJwk')
+
+function connectOrm ({ databaseUrl }) {
+  const orm = new Waterline()
+
+  // register any models
+  orm.registerModel(Agent)
+  orm.registerModel(PublicJwk)
+
+  // setup config
+  const config = {
+    adapters: {
+      postgres: sailsPostgresAdapter
+    },
+    datastores: {
+      default: {
+        adapter: 'postgres',
+        url: databaseUrl,
+        migrate: 'safe' // IMPORTANT. instead managed by knex
+      }
+    }
+  }
+
+  return { orm, config }
+}
+
+module.exports = { connectOrm }

package/src/server/models/publicJwk.js

@@ -0,0 +1,39 @@
+const Waterline = require('waterline')
+
+const PublicJwk = Waterline.Collection.extend({
+  identity: 'public_jwk',
+  tableName: 'public_jwks',
+  datastore: 'default',
+  primaryKey: 'id',
+  schema: true,
+
+  attributes: {
+    id: { type: 'number', autoMigrations: { autoIncrement: true } },
+    agent: { model: 'agent', columnName: 'agent_id', required: true },
+    kid: { type: 'string', required: true },
+    value: { type: 'json', required: true },
+    state: { type: 'string', required: false },
+    createdAt: { columnName: 'created_at', type: 'ref', autoCreatedAt: true },
+    updatedAt: { columnName: 'updated_at', type: 'ref', autoUpdatedAt: true }
+  },
+
+  beforeCreate (self, next) {
+    if (!self.state) {
+      self.state = 'active' // default state
+    }
+    next()
+  }
+
+  // customToJSON () {
+  //   const self = this
+
+  //   self.uidFormatted = `agent-${self.uid}`
+  //   self.wellKnownUrl = `${protocol()}://${self.uidFormatted}.${hostname()}/.well-known/http-message-signatures-directory`
+  //   // remove fields if needed
+  //   // delete self.privateKey
+
+  //   return self
+  // }
+})
+
+module.exports = PublicJwk

package/src/server/services/register.js

@@ -0,0 +1,13 @@
+class Register {
+  constructor ({ httpMethod, uri, headers, publicJwk }) {
+    this.httpMethod = httpMethod
+    this.uri = uri
+    this.headers = headers
+    this.publicJwk = publicJwk
+  }
+
+  async run () {
+  }
+}
+
+module.exports = Register

package/src/lib/server/index.js

@@ -1,99 +0,0 @@
-const { logger } = require('./../../shared/logger')
-const tool = require('./../tool')
-const primitives = require('./../primitives')
-
-const express = require('express')
-const crypto = require('crypto')
-
-const AGENTS = []
-const PUBLIC_JWKS = []
-
-const app = express()
-app.use(express.json())
-
-app.use((req, res, next) => {
-  const hostNoPort = (req.headers.host || '').split(':')[0].toLowerCase()
-
-  // agent-c235... .localhost
-  if (hostNoPort.endsWith('.localhost')) {
-    const sub = hostNoPort.slice(0, -'.localhost'.length) // "agent-c235..."
-    req.agentUid = sub
-    return next()
-  }
-
-  next()
-})
-
-app.get('/', (req, res) => {
-  if (req.agentUid) {
-    res.json({ uid: req.agentUid })
-  } else {
-    res.json({ hello: 'vestauth' })
-  }
-})
-
-app.post('/register', async (req, res) => {
-  try {
-    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
-    const verified = await primitives.verify(req.method, url, req.headers, req.body.public_jwk)
-
-    // insert agent
-    const uid = `agent-${crypto.randomBytes(12).toString('hex')}`
-    const agent = { uid }
-    AGENTS.push(agent)
-
-    // insert public_jwk
-    const publicJwk = {
-      agent_uid: agent.uid,
-      kid: verified.kid,
-      value: verified.public_jwk
-    }
-    PUBLIC_JWKS.push(publicJwk)
-
-    // response must be this format
-    const json = {
-      uid: agent.uid,
-      kid: publicJwk.kid,
-      public_jwk: verified.public_jwk,
-      is_new: true
-    }
-
-    res.json(json)
-  } catch (err) {
-    logger.error(err)
-    res.status(401).json({ error: { status: 401, code: 401, message: err.message } })
-  }
-})
-
-app.get('/.well-known/http-message-signatures-directory', (req, res) => {
-  const keys = PUBLIC_JWKS
-    .filter(jwk => jwk.agent_uid === req.agentUid)
-    .map(jwk => jwk.value)
-
-  res.json({ keys })
-})
-
-app.get('/whoami', async (req, res) => {
-  try {
-    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
-    const verified = await tool.verify(req.method, url, req.headers)
-
-    res.json(verified)
-  } catch (err) {
-    logger.error(err)
-    res.status(401).json({ error: { status: 401, code: 401, message: err.message } })
-  }
-})
-
-function start ({ port, databaseUrl: _databaseUrl } = {}) {
-  const PORT = port || '3000'
-
-  return app.listen(PORT, () => {
-    logger.success(`vestauth server listening on http://localhost:${PORT}`)
-  })
-}
-
-module.exports = {
-  app,
-  start
-}