feat(provenant): API key auth + webhook decision endpoint

StackMemory Bot (CLI) · StackMemory Bot (CLI) · commit 7be1970f1f8f · 2026-06-15T11:21:36.000-04:00
Add authentication and a real-time webhook endpoint to Provenant's
REST API so external systems (e.g. a coding harness) can push
decisions directly into the knowledge graph.

- API key auth via PROVENANT_API_KEY env var
- Auth required for POST /api/decisions and POST /api/webhook/decision
- POST /api/webhook/decision accepts decision payloads with optional
  source attribution for provenance
- startServer() now returns the http.Server instance
- Add REST API tests (4 tests, all passing)
diff --git a/packages/provenant/src/__tests__/api.test.ts b/packages/provenant/src/__tests__/api.test.ts
@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { startServer } from '../api/server.js';
+import type { Server } from 'node:http';
+
+function request(
+  port: number,
+  path: string,
+  opts: { method?: string; body?: unknown; token?: string } = {}
+): Promise<{ status: number; body: unknown }> {
+  return new Promise((resolve, reject) => {
+    const method = opts.method ?? 'GET';
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    };
+    if (opts.token) {
+      headers['Authorization'] = `Bearer ${opts.token}`;
+    }
+
+    const req = require('node:http').request(
+      {
+        hostname: '127.0.0.1',
+        port,
+        path,
+        method,
+        headers,
+      },
+      (res: any) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString();
+          try {
+            resolve({ status: res.statusCode ?? 0, body: JSON.parse(text) });
+          } catch {
+            resolve({ status: res.statusCode ?? 0, body: text });
+          }
+        });
+      }
+    );
+
+    req.on('error', reject);
+    if (opts.body) {
+      req.write(JSON.stringify(opts.body));
+    }
+    req.end();
+  });
+}
+
+describe('REST API', () => {
+  let tmpDir: string;
+  let server: Server;
+  let port: number;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'provenant-api-test-'));
+    port = 10_000 + Math.floor(Math.random() * 10_000);
+    server = startServer({
+      port,
+      dbPath: join(tmpDir, 'api.db'),
+      apiKey: 'test-api-key',
+    });
+    await new Promise<void>((resolve) => server.on('listening', resolve));
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('GET /api/status returns status without auth', async () => {
+    const res = await request(port, '/api/status');
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ nodeCount: 0 });
+  });
+
+  it('POST /api/decisions rejects without auth', async () => {
+    const res = await request(port, '/api/decisions', {
+      method: 'POST',
+      body: { content: 'Use PostgreSQL' },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('POST /api/decisions creates a node with valid auth', async () => {
+    const res = await request(port, '/api/decisions', {
+      method: 'POST',
+      body: { content: 'Use PostgreSQL', actor: 'qa' },
+      token: 'test-api-key',
+    });
+    expect(res.status).toBe(201);
+    expect(res.body).toMatchObject({ content: 'Use PostgreSQL', actor: 'qa' });
+  });
+
+  it('POST /api/webhook/decision stores decision with source provenance', async () => {
+    const res = await request(port, '/api/webhook/decision', {
+      method: 'POST',
+      body: {
+        content: 'SOP-101 satisfied: frame stack consistent',
+        actor: 'harness',
+        source: 'harness-pi',
+        source_id: 'run-123',
+        confidence: 0.9,
+      },
+      token: 'test-api-key',
+    });
+    expect(res.status).toBe(201);
+    expect(res.body).toMatchObject({
+      content: 'SOP-101 satisfied: frame stack consistent',
+      sourceLinked: true,
+    });
+
+    // Node should be searchable
+    const search = await request(
+      port,
+      '/api/nodes?keywords=SOP-101,frame'
+    );
+    expect(search.status).toBe(200);
+    expect(Array.isArray(search.body)).toBe(true);
+    expect((search.body as any[]).length).toBe(1);
+  });
+});
diff --git a/packages/provenant/src/api/server.ts b/packages/provenant/src/api/server.ts
@@ -1,5 +1,6 @@
 import {
   createServer,
+  type Server,
   type IncomingMessage,
   type ServerResponse,
 } from 'node:http';
@@ -8,6 +9,7 @@ import { Database } from '../schema/database.js';
 interface ServerConfig {
   port: number;
   dbPath: string;
+  apiKey?: string; // if set, required for mutation endpoints and webhooks
 }
 
 function parseJson(req: IncomingMessage): Promise<unknown> {
@@ -40,8 +42,32 @@ function parsePath(url: string): string {
   return idx >= 0 ? url.slice(0, idx) : url;
 }
 
-export function startServer(config: ServerConfig): void {
+function getAuthHeader(req: IncomingMessage): string | undefined {
+  const auth = req.headers['authorization'] ?? '';
+  if (typeof auth !== 'string') return undefined;
+  if (auth.toLowerCase().startsWith('bearer ')) {
+    return auth.slice(7).trim();
+  }
+  return auth.trim() || undefined;
+}
+
+function requireAuth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  apiKey: string | undefined
+): boolean {
+  if (!apiKey) return true; // auth disabled
+  const provided = getAuthHeader(req);
+  if (!provided || provided !== apiKey) {
+    json(res, 401, { error: 'Unauthorized' });
+    return false;
+  }
+  return true;
+}
+
+export function startServer(config: ServerConfig): Server {
   const db = new Database(config.dbPath);
+  const authEnabled = !!config.apiKey;
 
   const server = createServer(async (req, res) => {
     const method = req.method ?? 'GET';
@@ -95,6 +121,8 @@ export function startServer(config: ServerConfig): void {
 
       // POST /api/decisions
       if (method === 'POST' && path === '/api/decisions') {
+        if (!requireAuth(req, res, config.apiKey)) return;
+
         const body = (await parseJson(req)) as {
           content?: string;
           actor?: string;
@@ -115,6 +143,56 @@ export function startServer(config: ServerConfig): void {
         return;
       }
 
+      // POST /api/webhook/decision
+      // External systems (e.g. a coding harness) can push decisions in real time.
+      if (method === 'POST' && path === '/api/webhook/decision') {
+        if (!requireAuth(req, res, config.apiKey)) return;
+
+        const body = (await parseJson(req)) as {
+          content?: string;
+          actor?: string;
+          source?: string;
+          source_id?: string;
+          confidence?: number;
+          metadata?: Record<string, unknown>;
+        };
+        if (!body.content) {
+          json(res, 400, { error: 'content is required' });
+          return;
+        }
+
+        const node = db.insertNode({
+          type: 'decision',
+          content: body.content,
+          embedding: null,
+          actor: body.actor ?? null,
+          confidence: body.confidence ?? 0.75,
+        });
+
+        // Optionally link to an external source for provenance.
+        if (body.source && body.source_id) {
+          const source = db.insertSource({
+            system: body.source,
+            external_id: body.source_id,
+            raw_payload: JSON.stringify(body.metadata ?? {}),
+            hash: body.source_id,
+          });
+          db.linkNodeToSource(
+            node.id,
+            source.id,
+            body.source,
+            body.source_id
+          );
+        }
+
+        json(res, 201, {
+          ...node,
+          embedding: undefined,
+          sourceLinked: !!(body.source && body.source_id),
+        });
+        return;
+      }
+
       // GET /api/contradictions
       if (method === 'GET' && path === '/api/contradictions') {
         const contradictions = db.getPendingContradictions();
@@ -132,11 +210,13 @@ export function startServer(config: ServerConfig): void {
   server.listen(config.port, () => {
     console.log(`Provenant API server listening on port ${config.port}`);
     console.log(`  Database: ${config.dbPath}`);
+    console.log(`  Auth: ${authEnabled ? 'enabled (PROVENANT_API_KEY set)' : 'disabled'}`);
     console.log(`  Endpoints:`);
     console.log(`    GET  /api/status`);
     console.log(`    GET  /api/nodes?keywords=...&limit=...&actor=...`);
     console.log(`    GET  /api/nodes/:id`);
-    console.log(`    POST /api/decisions`);
+    console.log(`    POST /api/decisions          ${authEnabled ? '(auth required)' : ''}`);
+    console.log(`    POST /api/webhook/decision   ${authEnabled ? '(auth required)' : ''}`);
     console.log(`    GET  /api/contradictions`);
   });
 
@@ -151,4 +231,6 @@ export function startServer(config: ServerConfig): void {
     server.close();
     process.exit(0);
   });
+
+  return server;
 }
diff --git a/packages/provenant/src/cli/commands/serve.ts b/packages/provenant/src/cli/commands/serve.ts
@@ -14,5 +14,5 @@ export function serve(opts: ServeOpts): void {
     console.error(`Invalid port: ${opts.port}`);
     process.exit(1);
   }
-  startServer({ port, dbPath: opts.db });
+  startServer({ port, dbPath: opts.db, apiKey: process.env['PROVENANT_API_KEY'] });
 }

Original file line number	Diff line number	Diff line change
`@@ -14,5 +14,5 @@ export function serve(opts: ServeOpts): void {`
`14`	`14`	console.error(`Invalid port: ${opts.port}`);
`15`	`15`	`process.exit(1);`
`16`	`16`	`}`
`17`		`- startServer({ port, dbPath: opts.db });`
	`17`	`+ startServer({ port, dbPath: opts.db, apiKey: process.env['PROVENANT_API_KEY'] });`
`18`	`18`	`}`