feat(api): pending-changes + audit routes

Owner-only routes wired with an applyPendingChange dispatch helper
covering page/project/task/ref/resource/source_doc create/update/delete.
Approve and reject emit their own audit_log entries (actions already in
the CHECK vocab) so the audit trail is self-contained.

Documents a latent bug in security-followups.md: pending_changes.action
CHECK constraint blocks 'upsert' / 'add_dependency' / 'remove_dependency'
divertToPending paths in refs/resources routes when an agent at suggest
tier hits them.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lib/api/index.js

@@ -17,6 +17,8 @@ import { router as conversationsRouter } from './routes/conversations.js';
 import { conversationsScopedRouter as messagesByConvRouter } from './routes/messages.js';
 import { router as tagsRouter, entityScopedRouter as tagsByEntityRouter } from './routes/tags.js';
 import { router as linksRouter } from './routes/links.js';
+import { router as pendingChangesRouter } from './routes/pending_changes.js';
+import { router as auditRouter } from './routes/audit.js';
 
 export function mountApi(app) {
   const api = Router();
@@ -41,6 +43,8 @@ export function mountApi(app) {
   api.use('/conversations/:conversation_id/messages', messagesByConvRouter);
   api.use('/tags', tagsRouter);
   api.use('/links', linksRouter);
+  api.use('/pending-changes', pendingChangesRouter);
+  api.use('/audit', auditRouter);
   api.use('/:entity_type/:entity_id/tags', tagsByEntityRouter);
 
   api.use((_req, _res, next) => next(new NotFoundError('route not found')));

lib/api/routes/audit.js

@@ -0,0 +1,45 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as repo from '../../db/repos/audit.js';
+import { parsePagination } from '../pagination.js';
+import { validate } from '../validate.js';
+import { requireOwner } from '../cap.js';
+import { asyncWrap } from '../errors.js';
+
+const ENTITY_TYPES = ['space','project','task','page','ref','resource','source_doc','conversation'];
+const ACTOR_KINDS = ['user','agent','cron','worker','system'];
+
+const entityParams = z.object({
+  type: z.enum(ENTITY_TYPES),
+  id: z.string().uuid()
+});
+
+const actorQuery = z.object({
+  actor_kind: z.enum(ACTOR_KINDS).optional(),
+  actor_id: z.string().uuid().optional(),
+  limit: z.string().optional(),
+  offset: z.string().optional()
+});
+
+export const router = Router();
+router.use(requireOwner);
+
+router.get('/entity/:type/:id',
+  validate({ params: entityParams }),
+  asyncWrap(async (req, res) => {
+    const { limit } = parsePagination(req);
+    res.json(await repo.listForEntity(req.params.type, req.params.id, { limit }));
+  })
+);
+
+router.get('/actor',
+  validate({ query: actorQuery }),
+  asyncWrap(async (req, res) => {
+    const { limit } = parsePagination(req);
+    res.json(await repo.listByActor({
+      actor_kind: req.validatedQuery.actor_kind,
+      actor_id: req.validatedQuery.actor_id,
+      limit
+    }));
+  })
+);

lib/api/routes/pending_changes.js

@@ -0,0 +1,95 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as pendingRepo from '../../db/repos/pending_changes.js';
+import * as pagesRepo from '../../db/repos/pages.js';
+import * as projectsRepo from '../../db/repos/projects.js';
+import * as tasksRepo from '../../db/repos/tasks.js';
+import * as refsRepo from '../../db/repos/refs.js';
+import * as resourcesRepo from '../../db/repos/resources.js';
+import * as sourceDocsRepo from '../../db/repos/source_docs.js';
+import * as audit from '../../db/repos/audit.js';
+import { parsePagination } from '../pagination.js';
+import { validate } from '../validate.js';
+import { requireOwner } from '../cap.js';
+import { NotFoundError, ConflictError, ValidationError, asyncWrap } from '../errors.js';
+
+const REPOS = {
+  page: pagesRepo,
+  project: projectsRepo,
+  task: tasksRepo,
+  ref: refsRepo,
+  resource: resourcesRepo,
+  source_doc: sourceDocsRepo
+};
+
+// Action dispatch only supports the three CHECK-allowed actions on
+// pending_changes. Extended actions like 'upsert' / 'add_dependency' /
+// 'remove_dependency' are surfaced from a few routes but are blocked at
+// the DB level today — see docs/security-followups.md.
+export async function applyPendingChange(row, actor) {
+  const repo = REPOS[row.entity_type];
+  if (!repo) throw new ValidationError(`unsupported entity_type for approval: ${row.entity_type}`);
+  switch (row.action) {
+    case 'create': {
+      const created = await repo.create(row.payload, actor);
+      return created.id;
+    }
+    case 'update': {
+      await repo.update(row.entity_id, row.payload, actor);
+      return row.entity_id;
+    }
+    case 'delete': {
+      await repo.del(row.entity_id, actor);
+      return row.entity_id;
+    }
+    default:
+      throw new ValidationError(`unsupported action for approval: ${row.action}`);
+  }
+}
+
+const idParams = z.object({ id: z.string().uuid() });
+
+export const router = Router();
+router.use(requireOwner);
+
+router.get('/',
+  asyncWrap(async (req, res) => {
+    const { limit } = parsePagination(req);
+    res.json(await pendingRepo.listPending({ limit }));
+  })
+);
+
+router.post('/:id/approve',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const row = await pendingRepo.getById(req.params.id);
+    if (!row) throw new NotFoundError('pending change not found');
+    if (row.status !== 'pending') {
+      throw new ConflictError(`pending change is already ${row.status}`);
+    }
+    const entity_id = await applyPendingChange(row, req.actor);
+    const resolved = await pendingRepo.resolve(req.params.id, 'approved', req.actor?.id ?? 'owner');
+    await audit.recordAudit(
+      req.actor, 'approve', row.entity_type, entity_id,
+      null, { pending_id: row.id, original_agent_id: row.agent_id, action: row.action }
+    );
+    res.json({ ...resolved, entity_id });
+  })
+);
+
+router.post('/:id/reject',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const row = await pendingRepo.getById(req.params.id);
+    if (!row) throw new NotFoundError('pending change not found');
+    if (row.status !== 'pending') {
+      throw new ConflictError(`pending change is already ${row.status}`);
+    }
+    const resolved = await pendingRepo.resolve(req.params.id, 'rejected', req.actor?.id ?? 'owner');
+    await audit.recordAudit(
+      req.actor, 'reject', row.entity_type, row.entity_id,
+      null, { pending_id: row.id, original_agent_id: row.agent_id, action: row.action }
+    );
+    res.json(resolved);
+  })
+);