feat(api): karakeep webhook (HMAC-verified)

POST /api/ingest/karakeep accepts Karakeep webhook payloads. HMAC
signature on the raw body captured by express.json's verify hook.
Mounted on app before mountApi so it bypasses agentOrOwner — the
shared secret IS the auth.

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

lib/api/routes/ingest.js

@@ -0,0 +1,34 @@
+import { Router } from 'express';
+import crypto from 'node:crypto';
+import * as queue from '../../jobs/queue.js';
+import { asyncWrap } from '../errors.js';
+
+function verify(rawBody, headerSig) {
+  const secret = process.env.KARAKEEP_WEBHOOK_SECRET || '';
+  if (!headerSig || !secret || !rawBody) return false;
+  const expected = 'sha256=' +
+    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  try { return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headerSig)); }
+  catch { return false; }
+}
+
+export const router = Router();
+
+router.post('/karakeep', asyncWrap(async (req, res) => {
+  const sig = req.headers['x-karakeep-signature'];
+  if (!verify(req.rawBody, sig)) {
+    return res.status(401).json({ error: { code: 'unauthorized', message: 'bad signature' } });
+  }
+  const payload = req.body;
+  if (payload.event !== 'bookmark.created') return res.status(202).json({ skipped: true });
+  const space_id = process.env.KARAKEEP_DEFAULT_SPACE_ID;
+  if (!space_id) {
+    return res.status(503).json({
+      error: { code: 'unconfigured', message: 'KARAKEEP_DEFAULT_SPACE_ID not set' }
+    });
+  }
+  const job_id = await queue.enqueue('ingest.karakeep', {
+    bookmark_id: payload.bookmark_id, space_id
+  });
+  res.status(202).json({ job_id });
+}));

server.js

@@ -5,14 +5,22 @@ import { log } from './lib/log.js';
 import { mountApi } from './lib/api/index.js';
 import * as queue from './lib/jobs/queue.js';
 import { registerWorkers } from './lib/jobs/index.js';
+import { router as ingestRouter } from './lib/api/routes/ingest.js';
 
 const VERSION = '2.0.0-alpha.2';
 
 export function createApp() {
   const app = express();
-  app.use(express.json({ limit: '10mb' }));
+  app.use(express.json({
+    limit: '10mb',
+    verify: (req, _res, buf) => { req.rawBody = buf; }
+  }));
   app.use(express.static('public'));
 
+  // /api/ingest/* bypasses agentOrOwner — webhooks authenticate via HMAC
+  // and need access to req.rawBody captured above.
+  app.use('/api/ingest', ingestRouter);
+
   app.get('/health', async (_req, res) => {
     let db_ok = false;
     try {

tests/api/ingest.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import crypto from 'node:crypto';
+import request from 'supertest';
+import { setup } from './helpers.js';
+import { stopBoss } from '../helpers/boss.js';
+import * as queue from '../../lib/jobs/queue.js';
+import { registerWorkers } from '../../lib/jobs/index.js';
+import * as spaces from '../../lib/db/repos/spaces.js';
+
+let app, sp;
+const SECRET = 'test-karakeep-secret';
+
+function sign(body) {
+  return 'sha256=' + crypto.createHmac('sha256', SECRET).update(body).digest('hex');
+}
+
+beforeEach(async () => {
+  ({ app } = await setup());
+  process.env.KARAKEEP_WEBHOOK_SECRET = SECRET;
+  sp = await spaces.create({ slug: 'kw', name: 'KW' }, { kind: 'user', id: null });
+  process.env.KARAKEEP_DEFAULT_SPACE_ID = sp.id;
+  await queue.start(); await registerWorkers();
+});
+afterEach(async () => { await stopBoss(); });
+
+describe('karakeep webhook', () => {
+  it('enqueues on valid signature', async () => {
+    const body = JSON.stringify({ event: 'bookmark.created', bookmark_id: 'b-1' });
+    const res = await request(app).post('/api/ingest/karakeep')
+      .set('X-Karakeep-Signature', sign(body))
+      .set('Content-Type', 'application/json')
+      .send(body);
+    expect(res.status).toBe(202);
+    expect(res.body.job_id).toBeTruthy();
+  });
+
+  it('401 on bad signature', async () => {
+    const res = await request(app).post('/api/ingest/karakeep')
+      .set('X-Karakeep-Signature', 'sha256=wrong')
+      .set('Content-Type', 'application/json')
+      .send('{"event":"bookmark.created","bookmark_id":"b-1"}');
+    expect(res.status).toBe(401);
+  });
+
+  it('401 on missing signature', async () => {
+    const res = await request(app).post('/api/ingest/karakeep')
+      .set('Content-Type', 'application/json')
+      .send('{"event":"bookmark.created","bookmark_id":"b-1"}');
+    expect(res.status).toBe(401);
+  });
+
+  it('non-bookmark.created → 202 skipped', async () => {
+    const body = JSON.stringify({ event: 'bookmark.deleted', bookmark_id: 'b-1' });
+    const res = await request(app).post('/api/ingest/karakeep')
+      .set('X-Karakeep-Signature', sign(body))
+      .set('Content-Type', 'application/json')
+      .send(body);
+    expect(res.status).toBe(202);
+    expect(res.body.skipped).toBe(true);
+  });
+
+  it('503 when KARAKEEP_DEFAULT_SPACE_ID not set', async () => {
+    delete process.env.KARAKEEP_DEFAULT_SPACE_ID;
+    const body = JSON.stringify({ event: 'bookmark.created', bookmark_id: 'b-2' });
+    const res = await request(app).post('/api/ingest/karakeep')
+      .set('X-Karakeep-Signature', sign(body))
+      .set('Content-Type', 'application/json')
+      .send(body);
+    expect(res.status).toBe(503);
+  });
+});