meyi-vault-server 1.0.0

package/src/routes/entries.mjs

@@ -0,0 +1,170 @@
+import { Router } from 'express'
+import { eq, and, isNull } from 'drizzle-orm'
+import { vaultVaults, vaultGroups, vaultEntries } from '../database/schema.mjs'
+import { encrypt, decrypt } from '../utils/crypto.mjs'
+import { checkVaultAccess } from '../utils/auth.mjs'
+import { writeAudit, actorFromReq } from '../utils/audit.mjs'
+
+async function getVaultForGroup(db, groupId) {
+  const [group] = await db.select().from(vaultGroups).where(eq(vaultGroups.id, groupId))
+  if (!group) throw Object.assign(new Error('Group not found'), { status: 404 })
+  const [vault] = await db.select().from(vaultVaults).where(eq(vaultVaults.id, group.vault_id))
+  if (!vault) throw Object.assign(new Error('Vault not found'), { status: 404 })
+  return vault
+}
+
+export function createEntriesRouter(db) {
+  const router = Router({ mergeParams: true })
+
+  // GET /groups/:groupId/entries — decrypt all entries
+  router.get('/', async (req, res) => {
+    try {
+      const vault = await getVaultForGroup(db, req.params.groupId)
+      const { access } = await checkVaultAccess(db, vault.id, req.user)
+      if (!access) return res.status(403).json({ error: 'Forbidden' })
+
+      const keyHex = vault.key_material
+      const rows = await db.select().from(vaultEntries).where(
+        and(eq(vaultEntries.group_id, req.params.groupId), isNull(vaultEntries.deleted_at))
+      )
+      const entries = rows.map(e => {
+        const { password, notes = '' } = JSON.parse(
+          decrypt(e.encrypted_data, e.iv, e.auth_tag, keyHex)
+        )
+        return {
+          id: e.id, group_id: e.group_id, title: e.title,
+          username: e.username, password, notes,
+          created_at: e.created_at, updated_at: e.updated_at,
+        }
+      })
+
+      // Log sensitive access
+      if (entries.length > 0) {
+        await writeAudit(db, {
+          ...actorFromReq(req),
+          action: 'ENTRIES_VIEWED',
+          module: 'entry',
+          item_label: `Viewed ${entries.length} entries in group ${req.params.groupId}`,
+          meta: { group_id: req.params.groupId, vault_id: vault.id }
+        })
+      }
+
+      res.json({ entries })
+    } catch (err) {
+      res.status(err.status || 500).json({ error: err.message || 'Failed to fetch entries' })
+    }
+  })
+
+  // POST /groups/:groupId/entries — encrypt and store
+  router.post('/', async (req, res) => {
+    try {
+      const vault = await getVaultForGroup(db, req.params.groupId)
+      const { access, isOwner } = await checkVaultAccess(db, vault.id, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const { title, username, password, notes = '' } = req.body
+      if (!title || !username || !password) {
+        return res.status(400).json({ error: 'title, username and password required' })
+      }
+      const keyHex = vault.key_material
+      const enc = encrypt(JSON.stringify({ password, notes }), keyHex)
+      const [entry] = await db.insert(vaultEntries).values({
+        group_id: req.params.groupId,
+        title: title.trim(),
+        username: username.trim(),
+        ...enc,
+      }).returning()
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'ENTRY_CREATED',
+        module: 'entry',
+        item_id: entry.id,
+        item_label: entry.title,
+        meta: { group_id: req.params.groupId, vault_id: vault.id }
+      })
+
+      res.status(201).json({ entry: { ...entry, password, notes } })
+    } catch (err) {
+      res.status(err.status || 500).json({ error: err.message || 'Failed to create entry' })
+    }
+  })
+
+  // PUT /groups/:groupId/entries/:id — re-encrypt on update
+  router.put('/:id', async (req, res) => {
+    try {
+      const vault = await getVaultForGroup(db, req.params.groupId)
+      const { access, isOwner } = await checkVaultAccess(db, vault.id, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const [existing] = await db.select().from(vaultEntries).where(
+        and(
+          eq(vaultEntries.id, req.params.id),
+          eq(vaultEntries.group_id, req.params.groupId),
+          isNull(vaultEntries.deleted_at)
+        )
+      )
+      if (!existing) return res.status(404).json({ error: 'Entry not found' })
+
+      const keyHex = vault.key_material
+      const old = JSON.parse(decrypt(existing.encrypted_data, existing.iv, existing.auth_tag, keyHex))
+
+      const merged = {
+        password: req.body.password ?? old.password,
+        notes: req.body.notes ?? old.notes ?? '',
+      }
+      const enc = encrypt(JSON.stringify(merged), keyHex)
+
+      const [entry] = await db.update(vaultEntries).set({
+        title: req.body.title ?? existing.title,
+        username: req.body.username ?? existing.username,
+        ...enc,
+        updated_at: new Date(),
+      }).where(eq(vaultEntries.id, req.params.id)).returning()
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'ENTRY_UPDATED',
+        module: 'entry',
+        item_id: entry.id,
+        item_label: entry.title,
+        meta: { group_id: req.params.groupId, vault_id: vault.id }
+      })
+
+      res.json({ entry: { ...entry, ...merged } })
+    } catch (err) {
+      res.status(err.status || 500).json({ error: err.message || 'Failed to update entry' })
+    }
+  })
+
+  // DELETE /groups/:groupId/entries/:id — soft delete only
+  router.delete('/:id', async (req, res) => {
+    try {
+      const vault = await getVaultForGroup(db, req.params.groupId)
+      const { access, isOwner } = await checkVaultAccess(db, vault.id, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const [entry] = await db.select().from(vaultEntries).where(eq(vaultEntries.id, req.params.id))
+      if (!entry) return res.status(404).json({ error: 'Entry not found' })
+
+      await db.update(vaultEntries).set({ deleted_at: new Date() }).where(
+        and(eq(vaultEntries.id, req.params.id), eq(vaultEntries.group_id, req.params.groupId))
+      )
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'ENTRY_DELETED',
+        module: 'entry',
+        item_id: req.params.id,
+        item_label: entry.title,
+        meta: { group_id: req.params.groupId, vault_id: vault.id }
+      })
+
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to delete entry' })
+    }
+  })
+
+  return router
+}

package/src/routes/grants.mjs

@@ -0,0 +1,141 @@
+import { Router } from 'express'
+import { eq, and, isNull } from 'drizzle-orm'
+import { vaultGrants } from '../database/schema.mjs'
+import { expiresInToDate } from '../utils/crypto.mjs'
+import { checkVaultAccess, getVaultIdForScope } from '../utils/auth.mjs'
+import { writeAudit, actorFromReq } from '../utils/audit.mjs'
+
+export function createGrantsRouter(db) {
+  const router = Router()
+
+  // POST /grants — create or renew a grant
+  router.post('/', async (req, res) => {
+    try {
+      const { scope, scope_id, grantee_id, expires_in } = req.body
+      if (!scope || !scope_id || !grantee_id) {
+        return res.status(400).json({ error: 'scope, scope_id and grantee_id required' })
+      }
+      if (!['vault', 'group', 'entry'].includes(scope)) {
+        return res.status(400).json({ error: 'scope must be vault, group, or entry' })
+      }
+
+      // Check if grantor is the owner of the vault containing this scope
+      const vaultId = await getVaultIdForScope(db, scope, scope_id)
+      if (!vaultId) return res.status(404).json({ error: 'Resource not found' })
+
+      const { access, isOwner } = await checkVaultAccess(db, vaultId, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const expires_at = expiresInToDate(expires_in)
+
+      // Upsert — if grant already exists (even revoked), renew it
+      const [grant] = await db
+        .insert(vaultGrants)
+        .values({
+          scope,
+          scope_id,
+          grantee_id,
+          granted_by_id: req.user.id,
+          expires_at,
+          revoked_at: null,
+        })
+        .onConflictDoUpdate({
+          target: [vaultGrants.scope, vaultGrants.scope_id, vaultGrants.grantee_id],
+          set: {
+            granted_by_id: req.user.id,
+            expires_at,
+            revoked_at: null,
+            created_at: new Date(),
+          },
+        })
+        .returning()
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'GRANT_CREATED',
+        module: 'grant',
+        item_id: grant.id,
+        item_label: `Access to ${scope} granted to ${grantee_id}`,
+        meta: { scope, scope_id, grantee_id, vault_id: vaultId }
+      })
+
+      res.status(201).json({ grant })
+    } catch (err) {
+      console.error('[vault] POST /grants', err.message)
+      res.status(500).json({ error: 'Failed to create grant' })
+    }
+  })
+
+  // GET /grants — list grants issued by current user
+  router.get('/', async (req, res) => {
+    try {
+      const grants = await db
+        .select()
+        .from(vaultGrants)
+        .where(
+          and(
+            eq(vaultGrants.granted_by_id, req.user.id),
+            isNull(vaultGrants.revoked_at)
+          )
+        )
+      res.json({ grants })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to fetch grants' })
+    }
+  })
+
+  // GET /grants/received — grants received by current user
+  router.get('/received', async (req, res) => {
+    try {
+      const grants = await db
+        .select()
+        .from(vaultGrants)
+        .where(
+          and(
+            eq(vaultGrants.grantee_id, req.user.id),
+            isNull(vaultGrants.revoked_at)
+          )
+        )
+      res.json({ grants })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to fetch received grants' })
+    }
+  })
+
+  // DELETE /grants/:id — revoke
+  router.delete('/:id', async (req, res) => {
+    try {
+      const [grant] = await db
+        .select()
+        .from(vaultGrants)
+        .where(eq(vaultGrants.id, req.params.id))
+
+      if (!grant) return res.status(404).json({ error: 'Grant not found' })
+
+      // Only the grantor or an admin can revoke
+      if (grant.granted_by_id !== req.user.id && req.user.role !== 'admin') {
+        return res.status(403).json({ error: 'Forbidden' })
+      }
+
+      await db
+        .update(vaultGrants)
+        .set({ revoked_at: new Date() })
+        .where(eq(vaultGrants.id, req.params.id))
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'GRANT_REVOKED',
+        module: 'grant',
+        item_id: grant.id,
+        item_label: `Access to ${grant.scope} revoked from ${grant.grantee_id}`,
+        meta: { scope: grant.scope, scope_id: grant.scope_id, grantee_id: grant.grantee_id }
+      })
+
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to revoke grant' })
+    }
+  })
+
+  return router
+}

package/src/routes/groups.mjs

@@ -0,0 +1,127 @@
+import { Router } from 'express'
+import { eq, and, isNull, sql } from 'drizzle-orm'
+import { vaultGroups, vaultEntries } from '../database/schema.mjs'
+import { checkVaultAccess } from '../utils/auth.mjs'
+import { writeAudit, actorFromReq } from '../utils/audit.mjs'
+
+export function createGroupsRouter(db) {
+  const router = Router({ mergeParams: true })
+
+  // GET /vaults/:vaultId/groups
+  router.get('/', async (req, res) => {
+    try {
+      const { access } = await checkVaultAccess(db, req.params.vaultId, req.user)
+      if (!access) return res.status(403).json({ error: 'Forbidden' })
+
+      const groups = await db.select().from(vaultGroups)
+        .where(eq(vaultGroups.vault_id, req.params.vaultId))
+
+      // Entry counts per group
+      const withCounts = await Promise.all(groups.map(async (g) => {
+        const [{ count }] = await db
+          .select({ count: sql`count(*)::int` })
+          .from(vaultEntries)
+          .where(and(eq(vaultEntries.group_id, g.id), isNull(vaultEntries.deleted_at)))
+        return { ...g, entry_count: count ?? 0 }
+      }))
+
+      res.json({ groups: withCounts })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to fetch groups' })
+    }
+  })
+
+  // POST /vaults/:vaultId/groups
+  router.post('/', async (req, res) => {
+    try {
+      const { access, isOwner } = await checkVaultAccess(db, req.params.vaultId, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const { name, domain } = req.body
+      if (!name || !domain) return res.status(400).json({ error: 'name and domain required' })
+      const [group] = await db.insert(vaultGroups).values({
+        vault_id: req.params.vaultId,
+        name: name.trim(),
+        domain: domain.trim().toLowerCase(),
+      }).returning()
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'GROUP_CREATED',
+        module: 'group',
+        item_id: group.id,
+        item_label: group.name,
+        meta: { vault_id: req.params.vaultId }
+      })
+
+      res.status(201).json({ group: { ...group, entry_count: 0 } })
+    } catch (err) {
+      if (err.code === '23505') {
+        return res.status(409).json({ error: 'This domain already exists in the vault' })
+      }
+      res.status(500).json({ error: 'Failed to create group' })
+    }
+  })
+
+  // PUT /vaults/:vaultId/groups/:id
+  router.put('/:id', async (req, res) => {
+    try {
+      const { access, isOwner } = await checkVaultAccess(db, req.params.vaultId, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const updates = {}
+      if (req.body.name) updates.name = req.body.name.trim()
+      if (req.body.domain) updates.domain = req.body.domain.trim().toLowerCase()
+      if (!Object.keys(updates).length) return res.status(400).json({ error: 'Nothing to update' })
+
+      const [group] = await db.update(vaultGroups).set(updates)
+        .where(and(eq(vaultGroups.id, req.params.id), eq(vaultGroups.vault_id, req.params.vaultId)))
+        .returning()
+
+      if (!group) return res.status(404).json({ error: 'Group not found' })
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'GROUP_UPDATED',
+        module: 'group',
+        item_id: group.id,
+        item_label: group.name,
+        meta: { vault_id: req.params.vaultId }
+      })
+
+      res.json({ group })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to update group' })
+    }
+  })
+
+  // DELETE /vaults/:vaultId/groups/:id
+  router.delete('/:id', async (req, res) => {
+    try {
+      const { access, isOwner } = await checkVaultAccess(db, req.params.vaultId, req.user, true)
+      if (!access || !isOwner) return res.status(403).json({ error: 'Forbidden' })
+
+      const [group] = await db.select().from(vaultGroups).where(eq(vaultGroups.id, req.params.id))
+      if (!group) return res.status(404).json({ error: 'Group not found' })
+
+      await db.delete(vaultGroups).where(
+        and(eq(vaultGroups.id, req.params.id), eq(vaultGroups.vault_id, req.params.vaultId))
+      )
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'GROUP_DELETED',
+        module: 'group',
+        item_id: req.params.id,
+        item_label: group.name,
+        meta: { vault_id: req.params.vaultId }
+      })
+
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to delete group' })
+    }
+  })
+
+  return router
+}

package/src/routes/stats.mjs

@@ -0,0 +1,50 @@
+import { Router } from 'express'
+import { eq, and, isNull, sql } from 'drizzle-orm'
+import { vaultVaults, vaultGrants, vaultEntries } from '../database/schema.mjs'
+
+export function createStatsRouter(db) {
+  const router = Router()
+
+  // GET /stats — dashboard widget data for current user
+  router.get('/', async (req, res) => {
+    try {
+      const userId = req.user.id
+
+      const [{ vault_count }] = await db
+        .select({ vault_count: sql`count(*)::int` })
+        .from(vaultVaults)
+        .where(eq(vaultVaults.owner_id, userId))
+
+      const [{ active_grants }] = await db
+        .select({ active_grants: sql`count(*)::int` })
+        .from(vaultGrants)
+        .where(
+          and(
+            eq(vaultGrants.granted_by_id, userId),
+            isNull(vaultGrants.revoked_at)
+          )
+        )
+
+      const [{ entry_count }] = await db
+        .select({ entry_count: sql`count(*)::int` })
+        .from(vaultEntries)
+        .where(isNull(vaultEntries.deleted_at))
+
+      res.json({
+        vault_count: vault_count ?? 0,
+        active_grants: active_grants ?? 0,
+        entry_count: entry_count ?? 0,
+      })
+    } catch (err) {
+      console.error('[vault] GET /stats', err.message)
+      res.status(500).json({ error: 'Failed to fetch stats' })
+    }
+  })
+
+  // GET /me — current user info
+  router.get('/me', (req, res) => {
+    res.json({ user: req.user })
+  })
+
+  return router
+}

package/src/routes/vaults.mjs

@@ -0,0 +1,156 @@
+import { Router } from 'express'
+import { eq, and, isNull, or, sql, gt } from 'drizzle-orm'
+import { vaultVaults, vaultGrants } from '../database/schema.mjs'
+import { generateVaultKey } from '../utils/crypto.mjs'
+import { checkVaultAccess, getVaultIdForScope } from '../utils/auth.mjs'
+import { writeAudit, actorFromReq } from '../utils/audit.mjs'
+
+export function createVaultsRouter(db) {
+  const router = Router()
+
+  // GET /vaults — list owned + shared vaults
+  router.get('/', async (req, res) => {
+    try {
+      const userId = req.user.id
+      const owned = await db.select().from(vaultVaults).where(eq(vaultVaults.owner_id, userId))
+
+      // Find all active grants for the user
+      const activeGrants = await db.select().from(vaultGrants).where(
+        and(
+          eq(vaultGrants.grantee_id, userId),
+          isNull(vaultGrants.revoked_at),
+          or(
+            isNull(vaultGrants.expires_at),
+            gt(vaultGrants.expires_at, sql`now()`)
+          )
+        )
+      )
+
+      // Resolve vault IDs for all grants
+      const vaultIds = new Set()
+      for (const grant of activeGrants) {
+        if (grant.scope === 'vault') {
+          vaultIds.add(grant.scope_id)
+        } else {
+          const vId = await getVaultIdForScope(db, grant.scope, grant.scope_id)
+          if (vId) vaultIds.add(vId)
+        }
+      }
+
+      let shared = []
+      const activeGrantIds = Array.from(vaultIds)
+      if (activeGrantIds.length > 0) {
+        shared = await db.select().from(vaultVaults).where(
+          sql`${vaultVaults.id} = ANY(ARRAY[${sql.raw(activeGrantIds.map(id => `'${id}'`).join(','))}]::uuid[])`
+        )
+      }
+
+      const ownedIds = new Set(owned.map(v => v.id))
+      const all = [
+        ...owned.map(v => ({ ...v, is_owner: true })),
+        ...shared.filter(v => !ownedIds.has(v.id)).map(v => ({ ...v, is_owner: false })),
+      ].map(({ key_material, ...safe }) => safe) // never send key to client
+
+      res.json({ vaults: all })
+    } catch (err) {
+      console.error('[vault] GET /vaults', err.message)
+      res.status(500).json({ error: 'Failed to fetch vaults' })
+    }
+  })
+
+  // POST /vaults — create vault with fresh AES key
+  router.post('/', async (req, res) => {
+    try {
+      const { name } = req.body
+      if (!name?.trim()) return res.status(400).json({ error: 'name required' })
+      const [vault] = await db.insert(vaultVaults).values({
+        name: name.trim(),
+        owner_id: req.user.id,
+        key_material: generateVaultKey(),
+      }).returning()
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'VAULT_CREATED',
+        module: 'vault',
+        item_id: vault.id,
+        item_label: vault.name,
+      })
+
+      const { key_material, ...safe } = vault
+      res.status(201).json({ vault: { ...safe, is_owner: true } })
+    } catch (err) {
+      console.error('[vault] POST /vaults', err.message)
+      res.status(500).json({ error: 'Failed to create vault' })
+    }
+  })
+
+  // GET /vaults/:id
+  router.get('/:id', async (req, res) => {
+    try {
+      const { access, isOwner, vault } = await checkVaultAccess(db, req.params.id, req.user)
+      if (!vault) return res.status(404).json({ error: 'Vault not found' })
+      if (!access) return res.status(403).json({ error: 'Forbidden' })
+
+      const { key_material, ...safe } = vault
+      res.json({ vault: { ...safe, is_owner: isOwner } })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to fetch vault' })
+    }
+  })
+
+  // PUT /vaults/:id
+  router.put('/:id', async (req, res) => {
+    try {
+      const { name } = req.body
+      if (!name?.trim()) return res.status(400).json({ error: 'name required' })
+      
+      const { access, isOwner, vault } = await checkVaultAccess(db, req.params.id, req.user, true)
+      if (!vault) return res.status(404).json({ error: 'Vault not found' })
+      if (!access) return res.status(403).json({ error: 'Forbidden' })
+
+      const [updated] = await db.update(vaultVaults)
+        .set({ name: name.trim() })
+        .where(eq(vaultVaults.id, req.params.id))
+        .returning()
+      
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'VAULT_UPDATED',
+        module: 'vault',
+        item_id: updated.id,
+        item_label: updated.name,
+      })
+      
+      const { key_material, ...safe } = updated
+      res.json({ vault: { ...safe, is_owner: isOwner } })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to update vault' })
+    }
+  })
+
+  // DELETE /vaults/:id
+  router.delete('/:id', async (req, res) => {
+    try {
+      const { access, vault } = await checkVaultAccess(db, req.params.id, req.user, true)
+      if (!vault) return res.status(404).json({ error: 'Vault not found' })
+      if (!access) return res.status(403).json({ error: 'Forbidden' })
+
+      await db.delete(vaultVaults).where(eq(vaultVaults.id, req.params.id))
+
+      await writeAudit(db, {
+        ...actorFromReq(req),
+        action: 'VAULT_DELETED',
+        module: 'vault',
+        item_id: req.params.id,
+        item_label: vault.name,
+      })
+
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to delete vault' })
+    }
+  })
+
+  return router
+}

package/src/utils/audit.mjs

@@ -0,0 +1,57 @@
+import { vaultAuditLogs } from '../database/schema.mjs'
+
+/**
+ * Audit logging utility.
+ * Every mutating action in vault-server calls writeAudit().
+ * Errors are swallowed so an audit failure never breaks the main request.
+ */
+
+/**
+ * @param {object} db      — Drizzle DB instance
+ * @param {object} params
+ * @param {string} params.actor_id
+ * @param {string} params.actor_name
+ * @param {string} params.actor_email
+ * @param {string} params.action       — e.g. 'VAULT_CREATED'
+ * @param {string} params.module       — 'vault' | 'group' | 'entry' | 'grant'
+ * @param {string} params.item_id      — UUID of the resource
+ * @param {string} params.item_label   — human name e.g. vault name, entry title
+ * @param {object} [params.meta]       — extra context
+ */
+export async function writeAudit(db, {
+  actor_id,
+  actor_name = '',
+  actor_email = '',
+  action,
+  module,
+  item_id = '',
+  item_label = '',
+  meta = null,
+}) {
+  try {
+    await db.insert(vaultAuditLogs).values({
+      actor_id,
+      actor_name,
+      actor_email,
+      action,
+      module,
+      item_id: String(item_id),
+      item_label,
+      meta: meta ? JSON.stringify(meta) : null,
+    })
+  } catch (err) {
+    // Audit failures must never break the main request path
+    console.error('[vault-audit] write failed:', err.message)
+  }
+}
+
+/**
+ * Convenience: extract actor fields from req.user
+ */
+export function actorFromReq(req) {
+  return {
+    actor_id:    req.user?.id    ?? 'unknown',
+    actor_name:  req.user?.full_name ?? req.user?.name ?? '',
+    actor_email: req.user?.email ?? '',
+  }
+}