harper-knowledge 0.1.0

package/dist/webhooks/middleware.js

@@ -0,0 +1,161 @@
+/**
+ * Webhook Middleware
+ *
+ * HTTP middleware for Harper's scope.server.http() that routes
+ * /webhooks/* requests to the appropriate webhook handler.
+ */
+import { readBody } from "../http-utils.js";
+import { submitTriage, findBySourceId } from "../core/triage.js";
+import { validateSignature as validateGitHubSignature, parsePayload as parseGitHubPayload, } from "./github.js";
+import { validateApiKey as validateDatadogKey, parsePayload as parseDatadogPayload, } from "./datadog.js";
+// In-memory delivery ID dedup to prevent webhook replay attacks.
+// Bounded to MAX_SEEN entries; cleared when full (per-worker, resets on restart).
+const SEEN_DELIVERIES = new Set();
+const MAX_SEEN = 10_000;
+function isDuplicateDelivery(deliveryId) {
+    if (SEEN_DELIVERIES.has(deliveryId))
+        return true;
+    if (SEEN_DELIVERIES.size >= MAX_SEEN)
+        SEEN_DELIVERIES.clear();
+    SEEN_DELIVERIES.add(deliveryId);
+    return false;
+}
+/**
+ * Create a webhook middleware function for Harper's scope.server.http().
+ *
+ * Reads webhook config from scope.options and watches for changes
+ * to support secret rotation without restart.
+ */
+export function createWebhookMiddleware(scope) {
+    const scopeLogger = scope.logger;
+    // Read initial config
+    let webhookConfig = scope.options.getAll()?.webhooks || {};
+    // Watch for config changes (supports secret rotation)
+    scope.options.on("change", (_key, _value, config) => {
+        webhookConfig = config?.webhooks || {};
+        scopeLogger?.debug?.("Webhook configuration updated");
+    });
+    return async (request, next) => {
+        const pathname = request.pathname || "";
+        // Only handle /webhooks/* routes
+        if (!pathname.startsWith("/webhooks/")) {
+            return next(request);
+        }
+        // Only accept POST
+        if (request.method !== "POST") {
+            return jsonResponse(405, { error: "Method not allowed" });
+        }
+        // Route to the appropriate handler
+        if (pathname === "/webhooks/github") {
+            return handleGitHub(request, webhookConfig, scopeLogger);
+        }
+        if (pathname === "/webhooks/datadog") {
+            return handleDatadog(request, webhookConfig, scopeLogger);
+        }
+        return jsonResponse(404, { error: "Unknown webhook endpoint" });
+    };
+}
+async function handleGitHub(request, config, scopeLogger) {
+    const secret = config.github?.secret;
+    if (!secret) {
+        return jsonResponse(503, { error: "GitHub webhook not configured" });
+    }
+    // Read raw body
+    const rawBody = await readBody(request);
+    // Validate signature
+    const signature = getHeader(request, "x-hub-signature-256");
+    if (!validateGitHubSignature(rawBody, signature, secret)) {
+        return jsonResponse(401, { error: "Invalid signature" });
+    }
+    // Replay protection — reject duplicate delivery IDs
+    const deliveryId = getHeader(request, "x-github-delivery");
+    if (deliveryId && isDuplicateDelivery(deliveryId)) {
+        return jsonResponse(200, { status: "duplicate", deliveryId });
+    }
+    // Parse payload
+    let payload;
+    try {
+        payload = JSON.parse(rawBody);
+    }
+    catch {
+        return jsonResponse(400, { error: "Invalid JSON" });
+    }
+    const event = getHeader(request, "x-github-event");
+    const result = parseGitHubPayload(event, payload);
+    if (!result) {
+        // Event type we don't handle — acknowledge without creating triage item
+        return jsonResponse(200, { status: "ignored" });
+    }
+    return submitResult(result, scopeLogger);
+}
+async function handleDatadog(request, config, scopeLogger) {
+    const configuredKey = config.datadog?.apiKey;
+    if (!configuredKey) {
+        return jsonResponse(503, { error: "Datadog webhook not configured" });
+    }
+    // Read raw body
+    const rawBody = await readBody(request);
+    // Validate API key from DD-API-KEY or X-API-Key header
+    const apiKey = getHeader(request, "dd-api-key") || getHeader(request, "x-api-key");
+    if (!validateDatadogKey(apiKey, configuredKey)) {
+        return jsonResponse(401, { error: "Invalid API key" });
+    }
+    // Parse payload
+    let payload;
+    try {
+        payload = JSON.parse(rawBody);
+    }
+    catch {
+        return jsonResponse(400, { error: "Invalid JSON" });
+    }
+    const result = parseDatadogPayload(payload);
+    return submitResult(result, scopeLogger);
+}
+/**
+ * Submit a webhook result to the triage queue, checking for duplicates first.
+ */
+async function submitResult(result, scopeLogger) {
+    // Idempotency check
+    const existing = await findBySourceId(result.sourceId);
+    if (existing) {
+        return jsonResponse(200, { status: "duplicate", triageId: existing.id });
+    }
+    const item = await submitTriage(result.source, result.summary, result.rawPayload, result.sourceId);
+    scopeLogger?.info?.(`Webhook triage item created: ${item.id} (${result.source})`);
+    return jsonResponse(200, { status: "accepted", triageId: item.id });
+}
+/**
+ * Get a header value from Harper's request, case-insensitive.
+ */
+function getHeader(request, name) {
+    const headers = request.headers;
+    if (!headers)
+        return "";
+    // Try direct access (case-sensitive)
+    const direct = headers[name] ?? headers[name.toLowerCase()];
+    if (direct !== undefined) {
+        return Array.isArray(direct) ? direct[0] : String(direct);
+    }
+    // Try .get() method (Harper's Headers class)
+    if (typeof headers.get === "function") {
+        const val = headers.get(name);
+        if (val !== undefined && val !== null)
+            return String(val);
+    }
+    // Fallback: iterate to find case-insensitive match
+    const lowerName = name.toLowerCase();
+    if (typeof headers === "object") {
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() === lowerName && value !== undefined) {
+                return Array.isArray(value) ? value[0] : String(value);
+            }
+        }
+    }
+    return "";
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}

package/dist/webhooks/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared types for webhook handlers.
+ */
+/**
+ * Result from parsing a webhook payload.
+ * Returned by GitHub/Datadog handlers for the middleware to submit to triage.
+ */
+export interface WebhookResult {
+    /** Source identifier (e.g., "github-webhook", "datadog-webhook") */
+    source: string;
+    /** Deduplication key for idempotency */
+    sourceId: string;
+    /** Human-readable summary for triage review */
+    summary: string;
+    /** Original raw payload */
+    rawPayload: unknown;
+}

package/dist/webhooks/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for webhook handlers.
+ */
+export {};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "harper-knowledge",
+  "version": "0.1.0",
+  "description": "Knowledge base plugin for Harper with MCP server integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./config": "./config.yaml"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test \"test/**/*.test.js\"",
+    "test:watch": "npm run build && node --test --watch \"test/**/*.test.js\"",
+    "test:coverage": "npm run build && node --enable-source-maps --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-coverage-exclude='**/harperdb/**' \"test/**/*.test.js\"",
+    "lint": "eslint . --ignore-pattern 'dist/**'",
+    "format": "prettier .",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write .",
+    "model:download": "node scripts/download-model.js",
+    "model:test": "node scripts/download-model.js --test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "harper",
+    "harperdb",
+    "plugin",
+    "knowledge-base",
+    "mcp",
+    "ai",
+    "embeddings",
+    "vector-search"
+  ],
+  "author": "Nathan Heskew <nathan@heskew.dev> (https://heskew.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heskew/harper-knowledge"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "jose": "^6.1.3",
+    "node-llama-cpp": "^3.6.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@harperdb/code-guidelines": "0.0.6",
+    "@types/node": "25.2.0",
+    "eslint": "9.39.2",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "harperdb": ">=4.7.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "web",
+    "config.yaml",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/schema/knowledge.graphql

@@ -0,0 +1,134 @@
+## Knowledge Base Plugin Schema
+## Defines all tables for the knowledge base in the "kb" database
+
+## Core knowledge entries with vector embeddings for semantic search
+type KnowledgeEntry @table(database: "kb") @export {
+  id: ID @primaryKey
+  title: String @indexed
+  content: String
+  tags: [String]
+  appliesTo: Any
+  source: String
+  sourceUrl: String
+  confidence: String @indexed
+  addedBy: String
+  reviewedBy: String
+  embedding: [Float] @indexed(type: "HNSW", distance: "cosine")
+  supersedesId: ID
+  supersedes: KnowledgeEntry @relationship(from: "supersedesId")
+  supersededById: ID
+  supersededBy: KnowledgeEntry @relationship(from: "supersededById")
+  siblingIds: [ID]
+  siblings: [KnowledgeEntry] @relationship(from: "siblingIds")
+  relatedIds: [ID]
+  relatedEntries: [KnowledgeEntry] @relationship(from: "relatedIds")
+  customerContext: Any
+  deprecated: Boolean @indexed
+  createdAt: Date @createdTime
+  updatedAt: Date @updatedTime
+}
+
+## Webhook intake queue for new knowledge submissions
+## 7-day TTL (604800 seconds)
+type TriageItem @table(database: "kb", expiration: 604800) {
+  id: ID @primaryKey
+  source: String @indexed
+  sourceId: String @indexed
+  rawPayload: Any
+  summary: String
+  status: String @indexed
+  matchedEntryId: ID
+  matchedEntry: KnowledgeEntry @relationship(from: "matchedEntryId")
+  draftEntryId: ID
+  draftEntry: KnowledgeEntry @relationship(from: "draftEntryId")
+  action: String
+  processedBy: String
+  createdAt: Date @createdTime
+  processedAt: Date
+}
+
+## Tag registry with descriptions and usage counts
+type KnowledgeTag @table(database: "kb") {
+  id: ID @primaryKey
+  description: String
+  entryCount: Int
+}
+
+## Search query analytics log
+## 30-day TTL (2592000 seconds)
+type QueryLog @table(database: "kb", expiration: 2592000) {
+  id: ID @primaryKey
+  query: String
+  context: Any
+  source: String
+  resultCount: Int
+  topResultId: ID
+  topResult: KnowledgeEntry @relationship(from: "topResultId")
+  createdAt: Date @createdTime
+}
+
+## API keys for webhooks and service accounts
+type ServiceKey @table(database: "kb") {
+  id: ID @primaryKey
+  name: String
+  keyHash: String
+  role: String
+  permissions: Any
+  createdBy: String
+  createdAt: Date @createdTime
+  lastUsedAt: Date
+}
+
+## OAuth 2.1 Dynamic Client Registration (RFC 7591)
+type OAuthClient @table(database: "kb") {
+  id: ID @primaryKey
+  clientSecret: String
+  clientName: String
+  redirectUris: [String]
+  grantTypes: [String]
+  responseTypes: [String]
+  scope: String
+  createdAt: Date @createdTime
+}
+
+## OAuth 2.1 Authorization Codes (5-minute TTL)
+type OAuthCode @table(database: "kb", expiration: 300) {
+  id: ID @primaryKey
+  clientId: String @indexed
+  userId: String
+  scope: String
+  codeChallenge: String
+  codeChallengeMethod: String
+  redirectUri: String
+  createdAt: Date @createdTime
+}
+
+## OAuth 2.1 Refresh Tokens (30-day TTL)
+type OAuthRefreshToken @table(database: "kb", expiration: 2592000) {
+  id: ID @primaryKey
+  clientId: String @indexed
+  userId: String
+  scope: String
+  createdAt: Date @createdTime
+}
+
+## RSA signing key pair for JWT access tokens
+type OAuthSigningKey @table(database: "kb") {
+  id: ID @primaryKey
+  publicKeyJwk: Any
+  privateKeyJwk: Any
+  algorithm: String
+  createdAt: Date @createdTime
+}
+
+## Edit history for knowledge entries — append-only audit log
+type KnowledgeEntryEdit @table(database: "kb") {
+  id: ID @primaryKey
+  entryId: ID @indexed
+  entry: KnowledgeEntry @relationship(from: "entryId")
+  editedBy: String @indexed
+  editSummary: String
+  previousSnapshot: Any
+  changedFields: [String]
+  createdAt: Date @createdTime
+}