@vobase/core 0.10.0 → 0.11.0

package/src/infra/webhooks.test.ts

@@ -0,0 +1,364 @@
+import { Database } from 'bun:sqlite';
+import { createHmac } from 'node:crypto';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { drizzle } from 'drizzle-orm/bun-sqlite';
+import type { VobaseDb } from '../db/client';
+import type { Scheduler } from './queue';
+import {
+  checkAndRecordWebhook,
+  createWebhookRoutes,
+  verifyHmacSignature,
+  type WebhookConfig,
+} from './webhooks';
+
+/** Helper: compute a valid HMAC-SHA256 hex signature for a given payload + secret */
+function computeSignature(payload: string, secret: string): string {
+  return createHmac('sha256', secret).update(payload).digest('hex');
+}
+
+/** Create a Drizzle db with the webhook dedup table */
+function createTestDb(): VobaseDb {
+  const sqlite = new Database(':memory:');
+  sqlite.run(`CREATE TABLE _webhook_dedup (
+    id TEXT NOT NULL,
+    source TEXT NOT NULL,
+    received_at INTEGER NOT NULL,
+    PRIMARY KEY (id, source)
+  )`);
+  return drizzle({ client: sqlite }) as VobaseDb;
+}
+
+describe('WebhookConfig', () => {
+  test('type is correctly shaped with required and optional fields', () => {
+    const config: WebhookConfig = {
+      path: '/webhooks/stripe',
+      secret: 'whsec_test123',
+      handler: 'system:processWebhook',
+    };
+    expect(config.path).toBe('/webhooks/stripe');
+    expect(config.secret).toBe('whsec_test123');
+    expect(config.handler).toBe('system:processWebhook');
+    expect(config.signatureHeader).toBeUndefined();
+    expect(config.dedup).toBeUndefined();
+    expect(config.idHeader).toBeUndefined();
+
+    const fullConfig: WebhookConfig = {
+      path: '/webhooks/github',
+      secret: 'ghsec_abc',
+      handler: 'system:processGithub',
+      signatureHeader: 'x-hub-signature-256',
+      dedup: false,
+      idHeader: 'x-github-delivery',
+    };
+    expect(fullConfig.signatureHeader).toBe('x-hub-signature-256');
+    expect(fullConfig.dedup).toBe(false);
+    expect(fullConfig.idHeader).toBe('x-github-delivery');
+  });
+});
+
+describe('verifyHmacSignature', () => {
+  const secret = 'test-webhook-secret';
+  const payload = '{"event":"payment.completed","id":"evt_123"}';
+
+  test('verifies valid HMAC-SHA256 signature', () => {
+    const signature = computeSignature(payload, secret);
+    expect(verifyHmacSignature(payload, signature, secret)).toBe(true);
+  });
+
+  test('rejects invalid signature', () => {
+    const signature = computeSignature(payload, secret);
+    // Flip last character
+    const tampered = signature.slice(0, -1) + (signature.endsWith('0') ? '1' : '0');
+    expect(verifyHmacSignature(payload, tampered, secret)).toBe(false);
+  });
+
+  test('rejects empty signature', () => {
+    expect(verifyHmacSignature(payload, '', secret)).toBe(false);
+  });
+
+  test('rejects signature with wrong length', () => {
+    expect(verifyHmacSignature(payload, 'abcdef', secret)).toBe(false);
+    expect(verifyHmacSignature(payload, 'a'.repeat(128), secret)).toBe(false);
+  });
+
+  test('uses timing-safe comparison (not ===)', () => {
+    const valid = computeSignature(payload, secret);
+    expect(verifyHmacSignature(payload, valid, secret)).toBe(true);
+
+    // Same length but different content — must still reject
+    const sameLength = 'f'.repeat(valid.length);
+    expect(verifyHmacSignature(payload, sameLength, secret)).toBe(false);
+  });
+
+  test('handles different payloads correctly', () => {
+    const payload2 = '{"different":"data"}';
+    const sig1 = computeSignature(payload, secret);
+    const sig2 = computeSignature(payload2, secret);
+
+    expect(verifyHmacSignature(payload, sig1, secret)).toBe(true);
+    expect(verifyHmacSignature(payload2, sig2, secret)).toBe(true);
+    // Cross-check: sig for payload1 should not verify payload2
+    expect(verifyHmacSignature(payload2, sig1, secret)).toBe(false);
+  });
+
+  test('never throws on malformed input', () => {
+    expect(verifyHmacSignature(payload, 'not-hex-at-all!!!', secret)).toBe(false);
+    expect(verifyHmacSignature(payload, 'zzzz'.repeat(16), secret)).toBe(false);
+  });
+});
+
+describe('webhook deduplication', () => {
+  let db: VobaseDb;
+
+  beforeEach(() => {
+    db = createTestDb();
+  });
+
+  test('first webhook ID is not a duplicate', () => {
+    const isDuplicate = checkAndRecordWebhook(db, 'wh_001', 'stripe');
+    expect(isDuplicate).toBe(false);
+  });
+
+  test('same webhook ID is a duplicate', () => {
+    checkAndRecordWebhook(db, 'wh_002', 'stripe');
+    const isDuplicate = checkAndRecordWebhook(db, 'wh_002', 'stripe');
+    expect(isDuplicate).toBe(true);
+  });
+
+  test('different webhook IDs are not duplicates', () => {
+    expect(checkAndRecordWebhook(db, 'wh_aaa', 'stripe')).toBe(false);
+    expect(checkAndRecordWebhook(db, 'wh_bbb', 'stripe')).toBe(false);
+    expect(checkAndRecordWebhook(db, 'wh_ccc', 'stripe')).toBe(false);
+  });
+
+  test('same ID with different source is not a duplicate (composite key)', () => {
+    expect(checkAndRecordWebhook(db, 'wh_shared', 'stripe')).toBe(false);
+    expect(checkAndRecordWebhook(db, 'wh_shared', 'github')).toBe(false);
+  });
+});
+
+// --- Route handler tests ---
+
+function createMockScheduler(): Scheduler & { calls: Array<{ jobName: string; data: unknown }> } {
+  const calls: Array<{ jobName: string; data: unknown }> = [];
+  return {
+    calls,
+    async add(jobName: string, data: unknown) {
+      calls.push({ jobName, data });
+    },
+  };
+}
+
+function createWebhookTestApp(
+  configs: Record<string, WebhookConfig>,
+  mockScheduler: Scheduler,
+) {
+  const db = createTestDb();
+  const router = createWebhookRoutes(configs, { db, scheduler: mockScheduler });
+  return { app: router, db };
+}
+
+function computeHmac(payload: string, secret: string): string {
+  return createHmac('sha256', secret).update(payload).digest('hex');
+}
+
+describe('createWebhookRoutes', () => {
+  const secret = 'test-secret';
+  const payload = JSON.stringify({ event: 'test', id: 'evt_1' });
+
+  test('receives webhook with valid signature and enqueues job', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook' } },
+      scheduler,
+    );
+
+    const sig = computeHmac(payload, secret);
+    const res = await app.request('/webhooks/stripe', {
+      method: 'POST',
+      body: payload,
+      headers: {
+        'x-webhook-signature': sig,
+        'x-webhook-id': 'wh_001',
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ received: true });
+    expect(scheduler.calls).toHaveLength(1);
+    expect(scheduler.calls[0].jobName).toBe('billing:processWebhook');
+    expect(scheduler.calls[0].data).toEqual({
+      source: 'stripe',
+      webhookId: 'wh_001',
+      payload: JSON.parse(payload),
+    });
+  });
+
+  test('rejects invalid signature with 401', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook' } },
+      scheduler,
+    );
+
+    const res = await app.request('/webhooks/stripe', {
+      method: 'POST',
+      body: payload,
+      headers: {
+        'x-webhook-signature': 'invalidsignature',
+        'x-webhook-id': 'wh_002',
+      },
+    });
+
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Invalid signature' });
+    expect(scheduler.calls).toHaveLength(0);
+  });
+
+  test('deduplicates same webhook ID', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook' } },
+      scheduler,
+    );
+
+    const sig = computeHmac(payload, secret);
+    const headers = {
+      'x-webhook-signature': sig,
+      'x-webhook-id': 'wh_dup',
+    };
+
+    const res1 = await app.request('/webhooks/stripe', { method: 'POST', body: payload, headers });
+    expect(res1.status).toBe(200);
+    expect(await res1.json()).toEqual({ received: true });
+
+    const res2 = await app.request('/webhooks/stripe', { method: 'POST', body: payload, headers });
+    expect(res2.status).toBe(200);
+    expect(await res2.json()).toEqual({ received: true, deduplicated: true });
+
+    expect(scheduler.calls).toHaveLength(1);
+  });
+
+  test('skips dedup when dedup: false in config', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook', dedup: false } },
+      scheduler,
+    );
+
+    const sig = computeHmac(payload, secret);
+    const headers = {
+      'x-webhook-signature': sig,
+      'x-webhook-id': 'wh_nodup',
+    };
+
+    await app.request('/webhooks/stripe', { method: 'POST', body: payload, headers });
+    await app.request('/webhooks/stripe', { method: 'POST', body: payload, headers });
+
+    expect(scheduler.calls).toHaveLength(2);
+  });
+
+  test('uses custom signatureHeader when configured', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      {
+        github: {
+          path: '/webhooks/github',
+          secret,
+          handler: 'gh:process',
+          signatureHeader: 'x-hub-signature-256',
+        },
+      },
+      scheduler,
+    );
+
+    const sig = computeHmac(payload, secret);
+    const res = await app.request('/webhooks/github', {
+      method: 'POST',
+      body: payload,
+      headers: {
+        'x-hub-signature-256': sig,
+        'x-webhook-id': 'gh_001',
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(scheduler.calls).toHaveLength(1);
+  });
+
+  test('uses custom idHeader when configured', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      {
+        github: {
+          path: '/webhooks/github',
+          secret,
+          handler: 'gh:process',
+          idHeader: 'x-github-delivery',
+        },
+      },
+      scheduler,
+    );
+
+    const sig = computeHmac(payload, secret);
+    const headers = {
+      'x-webhook-signature': sig,
+      'x-github-delivery': 'gh_dup',
+    };
+
+    await app.request('/webhooks/github', { method: 'POST', body: payload, headers });
+    const res2 = await app.request('/webhooks/github', { method: 'POST', body: payload, headers });
+
+    expect(res2.status).toBe(200);
+    expect(await res2.json()).toEqual({ received: true, deduplicated: true });
+    expect(scheduler.calls).toHaveLength(1);
+  });
+
+  test('enqueues raw string payload when body is not valid JSON', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook' } },
+      scheduler,
+    );
+
+    const rawBody = 'plain text payload';
+    const sig = computeHmac(rawBody, secret);
+    const res = await app.request('/webhooks/stripe', {
+      method: 'POST',
+      body: rawBody,
+      headers: {
+        'x-webhook-signature': sig,
+        'x-webhook-id': 'wh_raw',
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ received: true });
+    expect(scheduler.calls).toHaveLength(1);
+    expect(scheduler.calls[0].data).toEqual({
+      source: 'stripe',
+      webhookId: 'wh_raw',
+      payload: 'plain text payload',
+    });
+  });
+
+  test('returns 401 when signature header is missing', async () => {
+    const scheduler = createMockScheduler();
+    const { app } = createWebhookTestApp(
+      { stripe: { path: '/webhooks/stripe', secret, handler: 'billing:processWebhook' } },
+      scheduler,
+    );
+
+    const res = await app.request('/webhooks/stripe', {
+      method: 'POST',
+      body: payload,
+      headers: {
+        'x-webhook-id': 'wh_nosig',
+      },
+    });
+
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Invalid signature' });
+    expect(scheduler.calls).toHaveLength(0);
+  });
+});

package/src/infra/webhooks.ts

@@ -0,0 +1,146 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import { Hono } from 'hono';
+import type { VobaseDb } from '../db/client';
+import type { Scheduler } from './queue';
+import { webhookDedup } from './webhooks-schema';
+
+export { webhookDedup } from './webhooks-schema';
+
+export interface WebhookConfig {
+  /** Route path, e.g. '/webhooks/stripe' */
+  path: string;
+  /** HMAC secret for signature verification */
+  secret: string;
+  /** Job name to enqueue, e.g. 'system:processWebhook' */
+  handler: string;
+  /** Header containing the signature (default: 'x-webhook-signature') */
+  signatureHeader?: string;
+  /** Whether to deduplicate webhooks (default: true) */
+  dedup?: boolean;
+  /** Header containing the webhook delivery ID (default: 'x-webhook-id') */
+  idHeader?: string;
+}
+
+/**
+ * Verify an HMAC-SHA256 signature against a payload and secret.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Returns false for any malformed or invalid signature (never throws).
+ */
+export function verifyHmacSignature(
+  payload: string,
+  signature: string,
+  secret: string,
+): boolean {
+  try {
+    const expected = createHmac('sha256', secret).update(payload).digest('hex');
+
+    if (signature.length !== expected.length) {
+      return false;
+    }
+
+    const sigBuffer = Buffer.from(signature, 'hex');
+    const expectedBuffer = Buffer.from(expected, 'hex');
+
+    // If the hex decode produced different lengths (malformed hex), reject
+    if (sigBuffer.length !== expectedBuffer.length) {
+      return false;
+    }
+
+    return timingSafeEqual(sigBuffer, expectedBuffer);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether a webhook has already been processed and record it if not.
+ *
+ * Checks for existing record first, then inserts if not found.
+ *
+ * @returns `true` if the webhook is a duplicate, `false` if it's new.
+ */
+export function checkAndRecordWebhook(
+  db: VobaseDb,
+  webhookId: string,
+  source: string,
+): boolean {
+  const existing = db
+    .select({ id: webhookDedup.id })
+    .from(webhookDedup)
+    .where(and(eq(webhookDedup.id, webhookId), eq(webhookDedup.source, source)))
+    .get();
+
+  if (existing) {
+    return true;
+  }
+
+  db.insert(webhookDedup)
+    .values({
+      id: webhookId,
+      source,
+      receivedAt: new Date(),
+    })
+    .run();
+
+  return false;
+}
+
+/**
+ * Create a Hono router that handles incoming webhook POST requests.
+ *
+ * For each webhook config, registers a POST handler that:
+ * 1. Verifies HMAC signature
+ * 2. Optionally deduplicates by webhook ID
+ * 3. Enqueues the payload to the configured job
+ */
+export function createWebhookRoutes(
+  configs: Record<string, WebhookConfig>,
+  deps: { db: VobaseDb; scheduler: Scheduler },
+): Hono {
+  const { db, scheduler } = deps;
+
+  const router = new Hono();
+
+  for (const [source, config] of Object.entries(configs)) {
+    router.post(config.path, async (c) => {
+      const body = await c.req.text();
+
+      const sigHeader = config.signatureHeader ?? 'x-webhook-signature';
+      const signature = c.req.header(sigHeader) ?? '';
+
+      if (!verifyHmacSignature(body, signature, config.secret)) {
+        return c.json({ error: 'Invalid signature' }, 401);
+      }
+
+      const dedupEnabled = config.dedup !== false;
+
+      if (dedupEnabled) {
+        const idHeader = config.idHeader ?? 'x-webhook-id';
+        const webhookId = c.req.header(idHeader) ?? '';
+
+        if (webhookId && checkAndRecordWebhook(db, webhookId, source)) {
+          return c.json({ received: true, deduplicated: true }, 200);
+        }
+      }
+
+      let payload: unknown;
+      try {
+        payload = JSON.parse(body);
+      } catch {
+        payload = body;
+      }
+
+      await scheduler.add(config.handler, {
+        source,
+        webhookId: c.req.header(config.idHeader ?? 'x-webhook-id') ?? '',
+        payload,
+      });
+
+      return c.json({ received: true }, 200);
+    });
+  }
+
+  return router;
+}

package/src/mcp/auth.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+
+import { createDatabase } from '../db/client';
+import { createMcpHandler } from './server';
+import { auditLog } from '../modules/audit/schema';
+import type { VobaseModule } from '../module';
+
+const MODULES_WITH_SCHEMA: VobaseModule[] = [
+  {
+    name: 'audit',
+    schema: { auditLog },
+    routes: new Hono(),
+  },
+];
+
+function createTestDb() {
+  const db = createDatabase(':memory:');
+  db.$client.run(`
+    CREATE TABLE IF NOT EXISTS _audit_log (
+      id TEXT PRIMARY KEY NOT NULL,
+      event TEXT NOT NULL,
+      actor_id TEXT,
+      actor_email TEXT,
+      ip TEXT,
+      details TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  return db;
+}
+
+async function postMcp(
+  handler: (req: Request) => Promise<Response>,
+  payload: Record<string, unknown>,
+  headers?: Record<string, string>,
+): Promise<{ response: Response; body: Record<string, unknown> }> {
+  const request = new Request('http://localhost/mcp', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      ...headers,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  const response = await handler(request);
+  const body = (await response.json()) as Record<string, unknown>;
+  return { response, body };
+}
+
+describe('MCP API key auth', () => {
+  it('allows unauthenticated access to discovery tools', async () => {
+    const handler = createMcpHandler({
+      db: createTestDb(),
+      modules: MODULES_WITH_SCHEMA,
+      verifyApiKey: async () => null,
+    });
+
+    const { response, body } = await postMcp(handler, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/list',
+    });
+
+    const tools = (
+      (body.result as { tools?: Array<{ name: string }> }).tools ?? []
+    ).map((t) => t.name);
+
+    expect(response.status).toBe(200);
+    expect(tools).toContain('list_modules');
+    expect(tools).toContain('view_logs');
+    // CRUD tools should NOT be present without auth
+    expect(tools).not.toContain('list_audit_log');
+    expect(tools).not.toContain('create_audit_log');
+  });
+
+  it('exposes CRUD tools when valid API key is provided', async () => {
+    const handler = createMcpHandler({
+      db: createTestDb(),
+      modules: MODULES_WITH_SCHEMA,
+      verifyApiKey: async (key) =>
+        key === 'valid-key' ? { userId: 'u1' } : null,
+    });
+
+    const { response, body } = await postMcp(
+      handler,
+      { jsonrpc: '2.0', id: 1, method: 'tools/list' },
+      { authorization: 'Bearer valid-key' },
+    );
+
+    const tools = (
+      (body.result as { tools?: Array<{ name: string }> }).tools ?? []
+    ).map((t) => t.name);
+
+    expect(response.status).toBe(200);
+    // Discovery tools present
+    expect(tools).toContain('list_modules');
+    // CRUD tools present when authenticated
+    expect(tools).toContain('list_audit_log');
+    expect(tools).toContain('get_audit_log');
+    expect(tools).toContain('create_audit_log');
+    expect(tools).toContain('update_audit_log');
+    expect(tools).toContain('delete_audit_log');
+  });
+
+  it('does not expose CRUD tools with invalid API key', async () => {
+    const handler = createMcpHandler({
+      db: createTestDb(),
+      modules: MODULES_WITH_SCHEMA,
+      verifyApiKey: async () => null,
+    });
+
+    const { response, body } = await postMcp(
+      handler,
+      { jsonrpc: '2.0', id: 1, method: 'tools/list' },
+      { authorization: 'Bearer bad-key' },
+    );
+
+    const tools = (
+      (body.result as { tools?: Array<{ name: string }> }).tools ?? []
+    ).map((t) => t.name);
+
+    expect(response.status).toBe(200);
+    expect(tools).toContain('list_modules');
+    expect(tools).not.toContain('list_audit_log');
+  });
+});