channelkit 1.0.0

package/config.example.yaml

@@ -0,0 +1,37 @@
+channels:
+  main:
+    type: whatsapp
+    number: "+44..."
+
+  # support-bot:
+  #   type: telegram
+  #   bot_token: "123:ABC..."
+
+routes:
+  - channel: whatsapp
+    match: "*"
+    webhook: "http://localhost:3000/api/chat"
+
+  # - channel: telegram
+  #   match: "status|temperature"
+  #   webhook: "http://localhost:8080/smart-home"
+
+# Webhook URLs support placeholders that are replaced at runtime:
+#   [FROM]          – sender identifier (phone number, user ID, email)
+#   [CHANNEL]       – channel type (whatsapp, telegram, email, sms)
+#   [CHANNEL_NAME]  – channel config key (main, support-bot, etc.)
+#   [SENDER_NAME]   – sender display name
+#   [MESSAGE_TYPE]  – message type (text, image, audio, etc.)
+#   [GROUP_ID]      – group/chat ID
+#   [GROUP_NAME]    – group/chat name
+#   [TEXT]          – message text (or STT transcription for voice messages)
+#
+# Example:
+#   webhook: "http://localhost:3000/api/users/[FROM]/messages"
+
+# onboarding:
+#   method: code
+#   codes:
+#     - code: "HELLO"
+#       service: "my-service"
+#       webhook: "http://localhost:3000/api/chat"

package/dist/api/middleware/auth.d.ts

@@ -0,0 +1,14 @@
+import { Request, Response, NextFunction } from 'express';
+import { ServerContext } from '../types';
+/** Set CORS headers and handle OPTIONS preflight for MCP endpoints. */
+export declare function mcpCors(ctx: ServerContext): (req: Request, res: Response, next: NextFunction) => void;
+export declare function externalAccessGuard(ctx: ServerContext): (req: Request, res: Response, next: NextFunction) => void;
+export declare function mcpAuthCheck(ctx: ServerContext): (req: Request, res: Response, next: NextFunction) => void;
+export declare function apiSecretCheck(ctx: ServerContext): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Admin auth guard — protects all dashboard/admin API endpoints.
+ * Uses the same api_secret from config. Skips auth when api_secret is not set.
+ * Allows through: /inbound/*, /api/health, /qr, /dashboard (static), MCP paths, and /api/auth/check.
+ */
+export declare function adminAuthCheck(ctx: ServerContext): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/api/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/api/middleware/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,GAAG,EAAE,aAAa,IAChC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAaxD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,IAC5C,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAcxD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,IACrC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAYxD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,IACvC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UASxD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,IACvC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAiBxD"}

package/dist/api/middleware/auth.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpCors = mcpCors;
+exports.externalAccessGuard = externalAccessGuard;
+exports.mcpAuthCheck = mcpAuthCheck;
+exports.apiSecretCheck = apiSecretCheck;
+exports.adminAuthCheck = adminAuthCheck;
+const crypto_1 = require("crypto");
+function isMcpPath(p) {
+    return p === '/mcp' || p.startsWith('/mcp/') || p === '/sse' || p === '/messages';
+}
+/** Timing-safe string comparison to prevent timing attacks. */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(Buffer.from(a), Buffer.from(b));
+}
+/** Set CORS headers and handle OPTIONS preflight for MCP endpoints. */
+function mcpCors(ctx) {
+    return (req, res, next) => {
+        if (!isMcpPath(req.path)) {
+            next();
+            return;
+        }
+        const origin = ctx.publicUrl || req.headers.origin || '';
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, mcp-session-id');
+        res.setHeader('Access-Control-Expose-Headers', 'mcp-session-id');
+        if (req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}
+function externalAccessGuard(ctx) {
+    return (req, res, next) => {
+        if (!ctx.publicUrl || ctx.exposeDashboard) {
+            next();
+            return;
+        }
+        const isExternal = req.headers['cf-connecting-ip'] ||
+            (req.headers.host && !req.headers.host.includes('localhost') && !req.headers.host.includes('127.0.0.1'));
+        if (!isExternal) {
+            next();
+            return;
+        }
+        const p = req.path;
+        if (p.startsWith('/inbound/') || p.startsWith('/api/send/') || p === '/api/health') {
+            next();
+            return;
+        }
+        if (ctx.exposeMcp && isMcpPath(p)) {
+            next();
+            return;
+        }
+        res.status(403).send('Dashboard access is disabled for external requests.');
+    };
+}
+function mcpAuthCheck(ctx) {
+    return (req, res, next) => {
+        if (!isMcpPath(req.path)) {
+            next();
+            return;
+        }
+        if (!ctx.mcpSecret) {
+            next();
+            return;
+        }
+        // Skip auth for local connections — secret is only enforced for external/tunnel access
+        const host = req.headers.host || '';
+        if (host.includes('localhost') || host.includes('127.0.0.1')) {
+            next();
+            return;
+        }
+        const auth = req.headers.authorization;
+        if (auth && safeEqual(auth, `Bearer ${ctx.mcpSecret}`)) {
+            next();
+            return;
+        }
+        res.status(401).json({ error: 'MCP access requires Authorization: Bearer <secret>' });
+    };
+}
+function apiSecretCheck(ctx) {
+    return (req, res, next) => {
+        if (!ctx.apiSecret) {
+            next();
+            return;
+        }
+        const auth = req.headers.authorization;
+        if (!auth || !safeEqual(auth, `Bearer ${ctx.apiSecret}`)) {
+            res.status(401).json({ error: 'Invalid or missing Authorization header' });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Admin auth guard — protects all dashboard/admin API endpoints.
+ * Uses the same api_secret from config. Skips auth when api_secret is not set.
+ * Allows through: /inbound/*, /api/health, /qr, /dashboard (static), MCP paths, and /api/auth/check.
+ */
+function adminAuthCheck(ctx) {
+    return (req, res, next) => {
+        if (!ctx.apiSecret) {
+            next();
+            return;
+        }
+        const p = req.path;
+        // Allow inbound webhooks, health check, static dashboard assets, QR page, and auth check
+        if (p.startsWith('/inbound/') || p === '/api/health' || p === '/api/auth/check'
+            || p === '/qr' || p === '/dashboard' || p.startsWith('/dashboard/')) {
+            next();
+            return;
+        }
+        // MCP paths have their own auth
+        if (isMcpPath(p)) {
+            next();
+            return;
+        }
+        const auth = req.headers.authorization;
+        if (!auth || !safeEqual(auth, `Bearer ${ctx.apiSecret}`)) {
+            res.status(401).json({ error: 'Invalid or missing Authorization header' });
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/api/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/api/middleware/auth.ts"],"names":[],"mappings":"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"}

package/dist/api/routes/config.d.ts

@@ -0,0 +1,4 @@
+import { Express } from 'express';
+import { ServerContext } from '../types';
+export declare function registerConfigRoutes(app: Express, ctx: ServerContext): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/api/routes/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/api/routes/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAmCzC,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAopB3E"}