@azizikri/hookpipe 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hookpipe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# hookpipe
+
+Self-hosted webhook relay with transform pipelines. Receive webhooks, authenticate, filter, transform, and deliver to one or more destinations. Built for self-hosted environments where you control the infrastructure.
+
+## Quick Start — Docker
+
+```bash
+docker build -t hookpipe -f docker/Dockerfile .
+docker run -p 3000:3000 -v ./pipelines:/app/pipelines -v ./data:/app/data hookpipe
+```
+
+## Quick Start — Bare Metal
+
+```bash
+npm install
+cp .env.example .env
+mkdir -p pipelines data
+node src/cli/index.js serve
+```
+
+Webhooks are received at `POST /hook/:pipeline-id`.
+
+## Pipeline YAML Schema
+
+Pipelines are YAML files in the `pipelines/` directory. Each file defines one pipeline.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique pipeline identifier (must match filename) |
+| `destinations` | array | One or more delivery targets |
+
+Each destination requires:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique destination identifier within the pipeline |
+| `type` | string | Destination type (`http`) |
+| `url` | string | Target URL |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Human-readable pipeline name |
+| `description` | string | Pipeline description |
+| `auth` | object | Authentication configuration |
+| `filter` | string | Filter plugin name |
+| `filter_config` | object | Config passed to the filter plugin |
+| `transform` | string | Transform plugin name |
+| `retry` | object | Retry policy override |
+
+### Auth Configuration
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | `hmac-sha256` or `hmac-sha1` |
+| `secret` | string | HMAC secret (supports `${ENV_VAR}` interpolation) |
+| `header` | string | Header containing the signature |
+
+### Destination Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `method` | string | HTTP method (default: `POST`) |
+| `headers` | object | Additional headers to send |
+| `body_template` | string | Handlebars template for the request body |
+| `timeout_ms` | number | Request timeout in milliseconds |
+| `on_failure` | string | Failure behavior (`retry` or `log`) |
+
+### Complete Example
+
+```yaml
+id: github-deploy
+name: GitHub Deploy Notifications
+description: Forward GitHub push events to deploy service
+
+auth:
+  type: hmac-sha256
+  secret: ${GITHUB_WEBHOOK_SECRET}
+  header: x-hub-signature-256
+
+filter: github-event-filter
+filter_config:
+  events:
+    - push
+    - release
+
+transform: extract-commit-info
+
+destinations:
+  - id: deploy-service
+    type: http
+    url: https://deploy.internal/api/trigger
+    method: POST
+    headers:
+      authorization: Bearer ${DEPLOY_TOKEN}
+    timeout_ms: 10000
+    on_failure: retry
+
+  - id: slack-notify
+    type: http
+    url: https://hooks.slack.com/services/T00/B00/xxx
+    body_template: |
+      {"text": "Deploy triggered by {{payload.pusher.name}} on {{payload.ref}}"}
+    on_failure: log
+
+retry:
+  maxAttempts: 5
+  backoff: exponential
+  initialDelayMs: 2000
+  maxDelayMs: 300000
+```
+
+## Plugin API
+
+Plugins are CommonJS modules loaded via `createRequire` (the project itself is ESM). Place them in the `plugins/` directory.
+
+### Transform Plugin
+
+```js
+// plugins/extract-commit-info.cjs
+module.exports.transform = function (payload, headers, config) {
+  // Return transformed payload object
+  // Return null to drop the webhook entirely
+  return {
+    ref: payload.ref,
+    commits: payload.commits.map(c => c.message),
+    pusher: payload.pusher.name,
+  };
+};
+```
+
+**Signature:** `transform(payload, headers, config) → object | null`
+
+- `payload` — parsed JSON body of the incoming webhook
+- `headers` — request headers (lowercased keys)
+- `config` — the pipeline's `filter_config` object (shared namespace)
+- Returns the transformed payload, or `null` to drop the webhook
+
+### Filter Plugin
+
+```js
+// plugins/github-event-filter.cjs
+module.exports.filter = function (payload, headers, config) {
+  const event = headers['x-github-event'];
+  if (config.events.includes(event)) {
+    return { pass: true };
+  }
+  return { pass: false, reason: `Event '${event}' not in allowed list` };
+};
+```
+
+**Signature:** `filter(payload, headers, config) → { pass: boolean, reason?: string }`
+
+- Return `{ pass: true }` to continue processing
+- Return `{ pass: false, reason: "..." }` to reject the webhook
+
+## CLI Reference
+
+```
+hookpipe <command> [options]
+```
+
+### `hookpipe serve`
+
+Start the webhook server.
+
+| Flag | Description |
+|------|-------------|
+| `-p, --port <number>` | Port to listen on |
+| `-H, --host <string>` | Host to bind to |
+| `-c, --config <path>` | Config file path |
+| `--pipelines <dir>` | Pipelines directory |
+| `--plugins <dir>` | Plugins directory |
+
+### `hookpipe test <pipeline-id>`
+
+Dry-run a webhook through a pipeline without delivering.
+
+| Flag | Description |
+|------|-------------|
+| `-f, --file <path>` | JSON file to use as payload |
+| `-d, --data <json>` | Inline JSON payload |
+| `--header <header>` | Custom header (repeatable, format: `Key: Value`) |
+| `--skip-auth` | Skip HMAC authentication check |
+| `-c, --config <path>` | Config file path |
+
+### `hookpipe logs`
+
+Query delivery logs.
+
+| Flag | Description |
+|------|-------------|
+| `--pipeline <id>` | Filter by pipeline ID |
+| `--status <status>` | Filter by status (success, failed, pending) |
+| `--since <duration>` | Show logs since duration (e.g. `1h`, `7d`) |
+| `--limit <n>` | Max number of entries (default: 50) |
+| `--json` | Output as JSON |
+
+### `hookpipe replay <delivery-id>`
+
+Re-enqueue a previous delivery for reprocessing.
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show what would be replayed without enqueuing |
+| `-c, --config <path>` | Config file path |
+
+## Configuration
+
+hookpipe loads configuration from a YAML file, environment variables, and CLI flags.
+
+**Precedence** (highest wins): CLI flags > environment variables > YAML file > defaults
+
+### Config File
+
+By default, hookpipe looks for `hookpipe.yaml` in the working directory. Override with `--config` or `HOOKPIPE_CONFIG`.
+
+```yaml
+host: 0.0.0.0
+port: 3000
+
+db:
+  path: ./data/hookpipe.db
+
+log:
+  level: info
+
+pipelines:
+  dir: ./pipelines
+
+plugins:
+  dir: ./plugins
+
+retry:
+  maxAttempts: 3
+  backoff: exponential
+  initialDelayMs: 1000
+  maxDelayMs: 300000
+
+queue:
+  pollIntervalMs: 1000
+  concurrency: 5
+```
+
+### Environment Variables
+
+| Variable | Maps to | Default |
+|----------|---------|---------|
+| `HOOKPIPE_PORT` | `port` | `3000` |
+| `HOOKPIPE_HOST` | `host` | `0.0.0.0` |
+| `HOOKPIPE_DB_PATH` | `db.path` | `./data/hookpipe.db` |
+| `HOOKPIPE_LOG_LEVEL` | `log.level` | `info` |
+| `HOOKPIPE_PIPELINES_DIR` | `pipelines.dir` | `./pipelines` |
+| `HOOKPIPE_PLUGINS_DIR` | `plugins.dir` | `./plugins` |
+| `HOOKPIPE_CONFIG` | config file path | `hookpipe.yaml` |
+
+Pipeline YAML values support `${ENV_VAR}` interpolation for secrets.
+
+## Trust Model
+
+hookpipe v1.0 has **no sandbox**. Plugins are loaded as plain Node.js modules with full access to the process, filesystem, and network.
+
+This is by design for self-hosted environments where you control what code runs on your infrastructure. The tradeoff is simplicity and zero overhead in exchange for requiring trust in your plugins.
+
+**Guidelines:**
+
+- Only load plugins you wrote or audited
+- Do not accept plugin uploads from untrusted sources
+- Run hookpipe with least-privilege OS permissions
+- Use Docker to limit blast radius if needed
+
+v1.1 will add optional isolation for plugins.
+
+## Tech Stack
+
+| Component | Role |
+|-----------|------|
+| Node.js 22+ | Runtime |
+| Fastify | HTTP server |
+| better-sqlite3 | Delivery queue and log storage |
+| Commander.js | CLI framework |
+| Pino | Structured logging |
+| Handlebars | Body templates |
+| chokidar | Pipeline hot-reload (file watching) |
+
+## Roadmap
+
+### v1.0 — Core (current)
+- Fastify HTTP server, YAML pipelines, env var interpolation
+- HMAC-SHA256/SHA1/Stripe authentication
+- JS transform + filter plugins (CJS, no sandbox)
+- HTTP destination adapter with Handlebars templates
+- SQLite delivery log, retry with exponential backoff, dead letter queue
+- Pipeline hot-reload via chokidar
+- CLI: serve, test, logs, replay
+- Docker image
+
+### v1.1 — Agent Layer
+- REST Admin API (CRUD pipelines, query logs, replay)
+- Agent registration + scoped API keys
+- Agent event queue (subscribe, poll, acknowledge)
+- SSE real-time event stream
+- Agent-writable transforms (runtime upload, sandboxed)
+- Plugin sandbox (isolated-vm)
+- Skills distribution via skills.sh
+
+### v1.2 — Polish
+- Destinations: Telegram, Discord, Slack, SMTP, File
+- Prometheus metrics endpoint
+- Rate limiting per pipeline
+- `hookpipe init` scaffolding
+- `hookpipe validate` pipeline linting
+
+### v1.3 — Scale
+- Redis/BullMQ queue backend
+- Horizontal scaling (multiple workers)
+- Pipeline chaining
+- TypeScript plugin support
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@azizikri/hookpipe",
+  "version": "1.0.0",
+  "description": "Self-hosted webhook relay with transform pipelines",
+  "keywords": [
+    "webhook",
+    "relay",
+    "pipeline",
+    "transform",
+    "fastify",
+    "sqlite"
+  ],
+  "homepage": "https://github.com/azizikri/hookpipe#readme",
+  "bugs": {
+    "url": "https://github.com/azizikri/hookpipe/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azizikri/hookpipe.git"
+  },
+  "license": "MIT",
+  "author": "azizikri",
+  "type": "module",
+  "main": "src/cli/index.js",
+  "bin": {
+    "hookpipe": "src/cli/index.js"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli/index.js serve",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run tests/integration",
+    "prepack": "npm test"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "chokidar": "^4.0.3",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "fastify": "^5.2.1",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "ulid": "^2.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/auth/hmac.js

@@ -0,0 +1,100 @@
+import { verifySignature, computeHmac, timingSafeCompare } from '../utils/crypto.js';
+
+const TYPE_MAP = {
+  'hmac-sha256': { algorithm: 'sha256', prefix: 'sha256=' },
+  'hmac-sha1': { algorithm: 'sha1', prefix: 'sha1=' },
+  'stripe': { algorithm: 'sha256', prefix: '' },
+};
+
+/**
+ * Parse Stripe-Signature header format: t=<timestamp>,v1=<sig1>,v1=<sig2>
+ */
+function parseStripeSignature(headerValue) {
+  const parts = headerValue.split(',');
+  let timestamp = null;
+  const signatures = [];
+  for (const part of parts) {
+    const [key, value] = part.split('=', 2);
+    if (key === 't') timestamp = value;
+    else if (key === 'v1') signatures.push(value);
+  }
+  return { timestamp, signatures };
+}
+
+/**
+ * Verify Stripe webhook signature.
+ * Stripe signs `${timestamp}.${rawBody}` with HMAC-SHA256.
+ */
+function verifyStripeAuth(rawBody, headers, authConfig) {
+  const { header, secret } = authConfig;
+  const headerLower = header.toLowerCase();
+  const sigHeader = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === headerLower
+  )?.[1];
+
+  if (!sigHeader) {
+    return { valid: false, error: 'Missing signature header' };
+  }
+
+  const { timestamp, signatures } = parseStripeSignature(sigHeader);
+
+  if (!timestamp || signatures.length === 0) {
+    return { valid: false, error: 'Invalid Stripe signature format' };
+  }
+
+  const signedPayload = `${timestamp}.${rawBody}`;
+  const expectedSig = computeHmac('sha256', secret, signedPayload);
+
+  const isValid = signatures.some((sig) => timingSafeCompare(sig, expectedSig));
+
+  if (!isValid) {
+    return { valid: false, error: 'Invalid signature' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Verify webhook authentication via HMAC signature.
+ *
+ * @param {string|Buffer} rawBody - The raw request body
+ * @param {object} headers - Request headers (keys may be any case)
+ * @param {object|null|undefined} authConfig - Auth configuration from pipeline YAML
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function verifyWebhookAuth(rawBody, headers, authConfig) {
+  if (!authConfig) {
+    return { valid: true };
+  }
+
+  const { type, header, secret } = authConfig;
+
+  if (!TYPE_MAP[type]) {
+    return { valid: false, error: `Unknown auth type: ${type}` };
+  }
+
+  // Stripe has its own verification flow
+  if (type === 'stripe') {
+    return verifyStripeAuth(rawBody, headers, authConfig);
+  }
+
+  const { algorithm, prefix } = TYPE_MAP[type];
+
+  // Case-insensitive header lookup
+  const headerLower = header.toLowerCase();
+  const signature = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === headerLower
+  )?.[1];
+
+  if (!signature) {
+    return { valid: false, error: 'Missing signature header' };
+  }
+
+  const isValid = verifySignature({ algorithm, secret, payload: rawBody, signature, prefix });
+
+  if (!isValid) {
+    return { valid: false, error: 'Invalid signature' };
+  }
+
+  return { valid: true };
+}

package/src/cli/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import dotenv from 'dotenv';
+import { serveCommand } from './serve.js';
+import { replayCommand } from './replay.js';
+import { testCommand } from './test.js';
+import { logsCommand } from './logs.js';
+dotenv.config();
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+const program = new Command();
+
+program
+  .name('hookpipe')
+  .description('Webhook ingestion and delivery pipeline')
+  .version(pkg.version);
+
+// Register commands
+serveCommand(program);
+
+testCommand(program);
+
+logsCommand(program);
+
+replayCommand(program);
+
+program.parse();

package/src/cli/logs.js

@@ -0,0 +1,86 @@
+import { loadConfig } from '../utils/config.js';
+import { initDatabase, closeDatabase } from '../db/index.js';
+import { listDeliveries } from '../db/queries.js';
+
+/**
+ * Parse a duration string (e.g., '1h', '24h', '7d', '30m') into an ISO date string.
+ */
+export function parseSince(duration) {
+  const match = duration.match(/^(\d+)([mhd])$/);
+  if (!match) {
+    throw new Error(`Invalid duration format: ${duration}. Use Nm, Nh, or Nd.`);
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  const multipliers = {
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+
+  const ms = value * multipliers[unit];
+  return new Date(Date.now() - ms).toISOString();
+}
+
+/**
+ * Format deliveries as a table string.
+ */
+function formatTable(deliveries) {
+  if (deliveries.length === 0) {
+    return 'No delivery logs found.';
+  }
+
+  const header = `${'ID'.padEnd(38)} ${'Pipeline'.padEnd(20)} ${'Status'.padEnd(12)} Received At`;
+  const separator = '-'.repeat(header.length);
+  const rows = deliveries.map((d) => {
+    const id = (d.id || '').padEnd(38);
+    const pipeline = (d.pipeline_id || '').padEnd(20);
+    const status = (d.status || '').padEnd(12);
+    const received = d.received_at || '';
+    return `${id} ${pipeline} ${status} ${received}`;
+  });
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Register the 'logs' command on the Commander program.
+ */
+export function logsCommand(program) {
+  program
+    .command('logs')
+    .description('Query delivery logs')
+    .option('-p, --pipeline <id>', 'Filter by pipeline ID')
+    .option('-s, --status <status>', 'Filter by status (pending/delivered/failed/dead_letter)')
+    .option('--since <duration>', "Show logs since duration (e.g., '1h', '24h', '7d', '30m')")
+    .option('-n, --limit <number>', 'Max results', '50')
+    .option('--offset <number>', 'Pagination offset', '0')
+    .option('-c, --config <path>', 'Config file path')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      const config = loadConfig(opts.config ? { configPath: opts.config } : {});
+      const db = initDatabase(config.db.path);
+
+      try {
+        const filters = {
+          pipelineId: opts.pipeline,
+          status: opts.status,
+          limit: parseInt(opts.limit, 10),
+          offset: parseInt(opts.offset, 10),
+          since: opts.since ? parseSince(opts.since) : undefined,
+        };
+
+        const deliveries = listDeliveries(db, filters);
+
+        if (opts.json) {
+          console.log(JSON.stringify(deliveries, null, 2));
+        } else {
+          console.log(formatTable(deliveries));
+        }
+      } finally {
+        closeDatabase(db);
+      }
+    });
+}

package/src/cli/replay.js

@@ -0,0 +1,64 @@
+import { loadConfig } from '../utils/config.js';
+import { initDatabase, closeDatabase } from '../db/index.js';
+import { getDelivery } from '../db/queries.js';
+import { SqliteQueue } from '../queue/sqlite-queue.js';
+import { PipelineLoader } from '../pipeline-loader.js';
+
+export function replayCommand(program) {
+  program
+    .command('replay')
+    .description('Replay a webhook delivery')
+    .argument('<delivery-id>', 'Delivery ID to replay')
+    .option('--dry-run', 'Show what would be replayed without enqueuing')
+    .option('-c, --config <path>', 'Config file path')
+    .action(async (deliveryId, opts) => {
+      const overrides = {};
+      if (opts.config) overrides.configPath = opts.config;
+
+      const config = loadConfig(overrides);
+      const db = initDatabase(config.db.path);
+
+      try {
+        const delivery = getDelivery(db, deliveryId);
+
+        if (!delivery) {
+          console.error(`Delivery not found: ${deliveryId}`);
+          process.exit(1);
+        }
+
+        const pipelineLoader = new PipelineLoader(config.pipelines.dir);
+        await pipelineLoader.loadAll();
+
+        const pipeline = pipelineLoader.get(delivery.pipeline_id);
+        const destinations = pipeline?.destinations || [];
+
+        if (opts.dryRun) {
+          console.log(`Delivery: ${deliveryId}`);
+          console.log(`Pipeline: ${delivery.pipeline_id}`);
+          console.log(`Status: ${delivery.status}`);
+          console.log(`Payload: ${JSON.stringify(delivery.payload).slice(0, 200)}`);
+          console.log(`Would re-enqueue to destinations: [${destinations.map((d) => d.id).join(', ')}]`);
+          return;
+        }
+
+        const queue = new SqliteQueue(db, config);
+        const headers = delivery.headers || {};
+        const payload = delivery.payload;
+
+        for (const dest of destinations) {
+          await queue.enqueue({
+            deliveryId,
+            destinationId: dest.id,
+            pipelineId: delivery.pipeline_id,
+            payload,
+            headers,
+            maxAttempts: pipeline?.retry?.maxAttempts ?? pipeline?.retry?.max_attempts ?? 3,
+          });
+        }
+
+        console.log(`Replayed delivery ${deliveryId} to ${destinations.length} destinations`);
+      } finally {
+        closeDatabase(db);
+      }
+    });
+}