vestauth 0.16.0 → 0.17.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.16.0...main)
+[Unreleased](https://github.com/vestauth/vestauth/compare/v0.17.0...main)
+
+## [0.17.0](https://github.com/vestauth/vestauth/compare/v0.16.0...v0.17.0) (2026-02-23)
+
+### Added
+
+* Add `db:*` scripts ([#32](https://github.com/vestauth/vestauth/pull/32))
 
 ## [0.16.0](https://github.com/vestauth/vestauth/compare/v0.15.1...v0.16.0) (2026-02-23)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vestauth",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "auth for agents–from the creator of dotenvx",
   "keywords": [
     "vestauth",
@@ -48,8 +48,10 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.52.0",
     "commander": "^11.1.0",
-    "express": "^4.21.2",
     "execa": "^5.1.1",
+    "express": "^4.21.2",
+    "knex": "^3.1.0",
+    "pg": "^8.18.0",
     "structured-headers": "^2.0.2",
     "undici": "7.11.0"
   },

package/src/cli/actions/server/dbCreate.js

@@ -0,0 +1,18 @@
+const { logger } = require('./../../../shared/logger')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
+
+const server = require('./../../../lib/server')
+
+async function dbCreate () {
+  try {
+    const options = this.opts()
+    logger.debug(`options: ${JSON.stringify(options)}`)
+
+    await server.db.create({ databaseUrl: options.databaseUrl })
+  } catch (error) {
+    catchAndLog(error)
+    process.exit(1)
+  }
+}
+
+module.exports = dbCreate

package/src/cli/actions/server/dbDrop.js

@@ -0,0 +1,18 @@
+const { logger } = require('./../../../shared/logger')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
+
+const server = require('./../../../lib/server')
+
+async function dbDrop () {
+  try {
+    const options = this.opts()
+    logger.debug(`options: ${JSON.stringify(options)}`)
+
+    await server.db.drop({ databaseUrl: options.databaseUrl })
+  } catch (error) {
+    catchAndLog(error)
+    process.exit(1)
+  }
+}
+
+module.exports = dbDrop

package/src/cli/actions/server/dbMigrate.js

@@ -0,0 +1,18 @@
+const { logger } = require('./../../../shared/logger')
+const catchAndLog = require('./../../../lib/helpers/catchAndLog')
+
+const server = require('./../../../lib/server')
+
+async function dbMigrate () {
+  try {
+    const options = this.opts()
+    logger.debug(`options: ${JSON.stringify(options)}`)
+
+    await server.db.migrate({ databaseUrl: options.databaseUrl })
+  } catch (error) {
+    catchAndLog(error)
+    process.exit(1)
+  }
+}
+
+module.exports = dbMigrate

package/src/cli/actions/server/start.js

@@ -8,7 +8,10 @@ async function start () {
     const options = this.opts()
     logger.debug(`options: ${JSON.stringify(options)}`)
 
-    await server.start({ port: options.port })
+    await server.start({
+      port: options.port,
+      databaseUrl: options.databaseUrl
+    })
   } catch (error) {
     catchAndLog(error)
     process.exit(1)

package/src/cli/commands/server.js

@@ -1,5 +1,6 @@
 const { Command } = require('commander')
 const env = require('./../../lib/helpers/env')
+const databaseUrl = require('./../../lib/helpers/databaseUrl')
 
 const server = new Command('server')
 
@@ -12,6 +13,28 @@ const startAction = require('./../actions/server/start')
 server.command('start')
   .description('start vestauth server')
   .option('--port <port>', 'port', env('PORT'))
+  .option('--database-url <databaseUrl>', 'DATABASE_URL', databaseUrl())
   .action(startAction)
 
+// vestauth server db:create
+const dbCreateAction = require('./../actions/server/dbCreate')
+server.command('db:create')
+  .description('create vestauth database')
+  .option('--database-url <databaseUrl>', 'DATABASE_URL', databaseUrl())
+  .action(dbCreateAction)
+
+// vestauth server db:migrate
+const dbMigrateAction = require('./../actions/server/dbMigrate')
+server.command('db:migrate')
+  .description('run db migrations')
+  .option('--database-url <databaseUrl>', 'DATABASE_URL', databaseUrl())
+  .action(dbMigrateAction)
+
+// vestauth server db:drop
+const dbDropAction = require('./../actions/server/dbDrop')
+server.command('db:drop')
+  .description('delete vestauth database')
+  .option('--database-url <databaseUrl>', 'DATABASE_URL', databaseUrl())
+  .action(dbDropAction)
+
 module.exports = server

package/src/db/migrations/20260223204000_create_agents_table.js

@@ -0,0 +1,19 @@
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.up = async function (knex) {
+  await knex.schema.createTable('agents', function (table) {
+    table.bigIncrements('id').primary()
+    table.string('uid')
+    table.datetime('created_at').notNullable()
+    table.datetime('updated_at').notNullable()
+    table.unique(['uid'], { indexName: 'index_agents_on_uid' })
+  })
+}
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.down = async function (knex) {
+  await knex.schema.dropTableIfExists('agents')
+}

package/src/db/migrations/20260223205500_create_public_jwks_table.js

@@ -0,0 +1,25 @@
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.up = async function (knex) {
+  await knex.schema.createTable('public_jwks', function (table) {
+    table.bigIncrements('id').primary()
+    table.bigInteger('agent_id').notNullable()
+    table.string('kid').notNullable()
+    table.jsonb('value').notNullable().defaultTo({})
+    table.string('state').notNullable().defaultTo('active')
+    table.datetime('created_at').notNullable()
+    table.datetime('updated_at').notNullable()
+
+    table.index(['agent_id'], 'index_public_jwks_on_agent_id')
+    table.unique(['kid'], { indexName: 'index_public_jwks_on_kid' })
+    table.foreign('agent_id').references('agents.id')
+  })
+}
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.down = async function (knex) {
+  await knex.schema.dropTableIfExists('public_jwks')
+}

package/src/lib/helpers/databaseUrl.js

@@ -0,0 +1,7 @@
+const env = require('./env')
+
+function databaseUrl () {
+  return env('DATABASE_URL') || 'postgres://localhost/vestauth_production'
+}
+
+module.exports = databaseUrl

package/src/lib/helpers/dbCreate.js

@@ -0,0 +1,54 @@
+const knex = require('knex')
+
+function quoteIdentifier (value) {
+  return `"${String(value).replace(/"/g, '""')}"`
+}
+
+function parseConnectionUrl (value) {
+  if (!value) throw new Error('missing DATABASE_URL')
+
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error('invalid DATABASE_URL')
+  }
+
+  const database = decodeURIComponent((url.pathname || '').replace(/^\//, ''))
+  if (!database) throw new Error('missing database name in DATABASE_URL')
+
+  return { url, database }
+}
+
+async function dbCreate ({ databaseUrl } = {}) {
+  const targetUrl = databaseUrl
+  const { url, database } = parseConnectionUrl(targetUrl)
+
+  // Connect to the maintenance DB (`postgres`) to create the target DB.
+  const maintenanceUrl = (() => {
+    const copy = new URL(url.toString())
+    copy.pathname = '/postgres'
+    return copy.toString()
+  })()
+
+  const db = knex({
+    client: 'pg',
+    connection: maintenanceUrl
+  })
+
+  try {
+    const result = await db.raw('select 1 from pg_database where datname = ?', [database])
+    const exists = Array.isArray(result.rows) && result.rows.length > 0
+
+    if (exists) {
+      return { created: false, database }
+    }
+
+    await db.raw(`create database ${quoteIdentifier(database)}`)
+    return { created: true, database }
+  } finally {
+    await db.destroy()
+  }
+}
+
+module.exports = dbCreate

package/src/lib/helpers/dbDrop.js

@@ -0,0 +1,60 @@
+const knex = require('knex')
+
+function quoteIdentifier (value) {
+  return `"${String(value).replace(/"/g, '""')}"`
+}
+
+function parseConnectionUrl (value) {
+  if (!value) throw new Error('missing DATABASE_URL')
+
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error('invalid DATABASE_URL')
+  }
+
+  const database = decodeURIComponent((url.pathname || '').replace(/^\//, ''))
+  if (!database) throw new Error('missing database name in DATABASE_URL')
+
+  return { url, database }
+}
+
+async function dbDrop ({ databaseUrl } = {}) {
+  const targetUrl = databaseUrl
+  const { url, database } = parseConnectionUrl(targetUrl)
+
+  // Connect to the maintenance DB (`postgres`) to drop the target DB.
+  const maintenanceUrl = (() => {
+    const copy = new URL(url.toString())
+    copy.pathname = '/postgres'
+    return copy.toString()
+  })()
+
+  const db = knex({
+    client: 'pg',
+    connection: maintenanceUrl
+  })
+
+  try {
+    const result = await db.raw('select 1 from pg_database where datname = ?', [database])
+    const exists = Array.isArray(result.rows) && result.rows.length > 0
+
+    if (!exists) {
+      return { dropped: false, database }
+    }
+
+    // Terminate active connections so DROP DATABASE succeeds in local workflows.
+    await db.raw(
+      'select pg_terminate_backend(pid) from pg_stat_activity where datname = ? and pid <> pg_backend_pid()',
+      [database]
+    )
+
+    await db.raw(`drop database ${quoteIdentifier(database)}`)
+    return { dropped: true, database }
+  } finally {
+    await db.destroy()
+  }
+}
+
+module.exports = dbDrop

package/src/lib/helpers/dbMigrate.js

@@ -0,0 +1,30 @@
+const path = require('path')
+const knex = require('knex')
+const Errors = require('./errors')
+
+async function dbMigrate ({ databaseUrl } = {}) {
+  const connection = databaseUrl
+  if (!connection) throw new Errors().missingDatabaseUrl()
+
+  const db = knex({
+    client: 'pg',
+    connection,
+    ssl: { rejectUnauthorized: false },
+    migrations: {
+      directory: path.resolve(__dirname, '../../db/migrations')
+    }
+  })
+
+  try {
+    const [batchNo, migrations] = await db.migrate.latest()
+
+    return {
+      batchNo,
+      migrations
+    }
+  } finally {
+    await db.destroy()
+  }
+}
+
+module.exports = dbMigrate

package/src/lib/helpers/errors.js

@@ -121,6 +121,17 @@ class Errors {
     return e
   }
 
+  missingDatabaseUrl () {
+    const code = 'MISSING_DATABASE_URL'
+    const message = `[${code}] missing DATABASE_URL`
+    const help = `[${code}] pass --database-url or set DATABASE_URL`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    return e
+  }
+
   commandFailed () {
     const code = 'COMMAND_FAILED'
     const message = `[${code}] command failed with exit code ${this.exitCode}`

package/src/lib/helpers/serverStart.js

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

package/src/lib/server/index.js

@@ -85,7 +85,7 @@ app.get('/whoami', async (req, res) => {
   }
 })
 
-function start ({ port } = {}) {
+function start ({ port, databaseUrl: _databaseUrl } = {}) {
   const PORT = port || '3000'
 
   return app.listen(PORT, () => {

package/src/lib/server.js

@@ -1,5 +1,13 @@
 const serverStart = require('./helpers/serverStart')
+const dbCreate = require('./helpers/dbCreate')
+const dbMigrate = require('./helpers/dbMigrate')
+const dbDrop = require('./helpers/dbDrop')
 
 module.exports = {
-  start: serverStart
+  start: serverStart,
+  db: {
+    create: dbCreate,
+    migrate: dbMigrate,
+    drop: dbDrop
+  }
 }