@cogenta/channels 0.1.0

package/dist/providers/webhook/signing.js

@@ -0,0 +1,108 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { CogentaError } from '@cogenta/core';
+/**
+ * "Les webhooks entrants sont une surface d'attaque. Vérification de
+ * signature obligatoire, fenêtre temporelle, protection contre le rejeu. Un
+ * webhook non signé est un endpoint public arbitraire." (L6, "## Pièges
+ * connus"). This module is the whole reason L6 task 11 exists as its own
+ * deliverable — three checks, all mandatory: signature authenticity,
+ * timestamp freshness, and replay rejection.
+ *
+ * Same HMAC-SHA256 + constant-time-comparison construction as
+ * `approvals/signed-link.ts` (itself mirroring `StorageDriver.signedUrl`) —
+ * signs `timestamp + '.' + rawBody` rather than the body alone, so a replayed
+ * request with an old, otherwise-valid signature still fails freshness.
+ */
+const DEFAULT_FRESHNESS_WINDOW_SECONDS = 5 * 60;
+/** The two headers an outbound signed webhook carries; a receiver names them however it configures its route. */
+export const WEBHOOK_TIMESTAMP_HEADER = 'X-Cogenta-Timestamp';
+export const WEBHOOK_SIGNATURE_HEADER = 'X-Cogenta-Signature';
+function signPayload(secret, timestampSeconds, rawBody) {
+    return createHmac('sha256', secret).update(`${timestampSeconds}.${rawBody}`).digest('hex');
+}
+/** The outbound half: what `createWebhookAdapter`'s `send()` attaches to every request. */
+export function signOutgoingWebhook(secret, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const timestamp = String(nowSeconds);
+    return { timestamp, signature: signPayload(secret, nowSeconds, rawBody) };
+}
+/**
+ * Bounded, in-memory replay guard — proportionate to the freshness window a
+ * verifier already enforces (an entry older than the window can never pass
+ * freshness anyway, so nothing needs to be remembered past it). Not a
+ * general-purpose dedup store; one instance per verifying process/secret is
+ * the expected usage, matching how a route handler would own it.
+ */
+export class WebhookReplayGuard {
+    #seenAtBySignature = new Map();
+    /** Returns `true` if `signature` was already recorded within a still-valid window. */
+    hasSeen(signature, nowSeconds, freshnessWindowSeconds) {
+        this.#purgeExpired(nowSeconds, freshnessWindowSeconds);
+        return this.#seenAtBySignature.has(signature);
+    }
+    remember(signature, nowSeconds) {
+        this.#seenAtBySignature.set(signature, nowSeconds);
+    }
+    #purgeExpired(nowSeconds, freshnessWindowSeconds) {
+        for (const [signature, seenAt] of this.#seenAtBySignature) {
+            if (nowSeconds - seenAt > freshnessWindowSeconds)
+                this.#seenAtBySignature.delete(signature);
+        }
+    }
+}
+/**
+ * Three independent checks, all mandatory, in the order that fails cheapest
+ * first: a malformed/non-numeric timestamp or a stale one is rejected before
+ * ever computing an HMAC over it, and only a request that is both fresh and
+ * authentic is checked for replay (recording a signature for a request that
+ * never even had a valid signature would let an attacker exhaust the replay
+ * guard with garbage).
+ *
+ * Unlike `linking/codes.ts`'s deliberately uniform `CHANNEL_LINK_CODE_INVALID`
+ * (chosen to deny an attacker an enumeration oracle over *which accounts
+ * exist*), this returns a *distinguishable* reason. There is no identity to
+ * enumerate here — a webhook secret is either configured correctly or it
+ * isn't, and telling an operator debugging a misconfigured integration
+ * "your signature doesn't match" versus "your timestamp is stale" versus
+ * "this exact request was already processed" is a legitimate operational
+ * need, not an attack surface: none of the three reasons reveal anything an
+ * attacker couldn't already infer from a generic 401.
+ */
+export function verifyIncomingWebhook(input) {
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const freshnessWindowSeconds = input.freshnessWindowSeconds ?? DEFAULT_FRESHNESS_WINDOW_SECONDS;
+    const timestampSeconds = Number(input.headers.timestamp);
+    if (!Number.isFinite(timestampSeconds))
+        return { ok: false, reason: 'invalid_signature' };
+    if (Math.abs(now - timestampSeconds) > freshnessWindowSeconds) {
+        return { ok: false, reason: 'expired' };
+    }
+    const expected = Buffer.from(signPayload(input.secret, timestampSeconds, input.rawBody), 'utf8');
+    const received = Buffer.from(input.headers.signature, 'utf8');
+    if (expected.length !== received.length || !timingSafeEqual(expected, received)) {
+        return { ok: false, reason: 'invalid_signature' };
+    }
+    if (input.replayGuard !== undefined) {
+        if (input.replayGuard.hasSeen(input.headers.signature, now, freshnessWindowSeconds)) {
+            return { ok: false, reason: 'replayed' };
+        }
+        input.replayGuard.remember(input.headers.signature, now);
+    }
+    return { ok: true };
+}
+const REASON_TO_ERROR_CODE = {
+    invalid_signature: 'CHANNEL_WEBHOOK_SIGNATURE_INVALID',
+    expired: 'CHANNEL_WEBHOOK_EXPIRED',
+    replayed: 'CHANNEL_WEBHOOK_REPLAY_DETECTED',
+};
+/** Throws the typed `CogentaError` matching a failed `verifyIncomingWebhook` result; a no-op on success. */
+export function assertValidIncomingWebhook(result) {
+    if (result.ok)
+        return;
+    const code = REASON_TO_ERROR_CODE[result.reason];
+    throw new CogentaError({
+        code,
+        message: `Incoming webhook rejected: ${result.reason}.`,
+        hint: 'Check the shared secret, clock skew between sender and receiver, and that this exact request has not already been delivered.',
+    });
+}
+//# sourceMappingURL=signing.js.map

package/dist/providers/webhook/signing.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ChannelAdapter } from './adapter.js';
+export interface ChannelRegistry {
+    readonly has: (name: string) => boolean;
+    readonly get: (name: string) => ChannelAdapter;
+    /** Every configured adapter, in the order given to `createChannelRegistry`. */
+    readonly list: () => readonly ChannelAdapter[];
+}
+/**
+ * A site with zero channels configured must work fine — nothing here fails
+ * to construct on an empty list, mirroring how `createProviderRegistry`
+ * (`@cogenta/agents`) treats zero LLM providers as a normal, supported
+ * state rather than an error (R2's spirit applied to channels: no channel
+ * configured means no notifications are sent, never a broken CMS).
+ */
+export declare function createChannelRegistry(adapters: readonly ChannelAdapter[]): ChannelRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IACvC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,CAAA;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,cAAc,EAAE,CAAA;CAC/C;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,eAAe,CA8B1F"}

package/dist/registry.js

@@ -0,0 +1,39 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * A site with zero channels configured must work fine — nothing here fails
+ * to construct on an empty list, mirroring how `createProviderRegistry`
+ * (`@cogenta/agents`) treats zero LLM providers as a normal, supported
+ * state rather than an error (R2's spirit applied to channels: no channel
+ * configured means no notifications are sent, never a broken CMS).
+ */
+export function createChannelRegistry(adapters) {
+    const byName = new Map();
+    for (const adapter of adapters) {
+        if (byName.has(adapter.name)) {
+            throw new CogentaError({
+                code: 'CHANNEL_DUPLICATE',
+                message: `Two channel adapters are both named "${adapter.name}".`,
+                hint: 'Every ChannelAdapter passed to createChannelRegistry must have a unique name.',
+                details: { name: adapter.name },
+            });
+        }
+        byName.set(adapter.name, adapter);
+    }
+    return {
+        has: (name) => byName.has(name),
+        get(name) {
+            const adapter = byName.get(name);
+            if (adapter === undefined) {
+                throw new CogentaError({
+                    code: 'CHANNEL_UNKNOWN',
+                    message: `No channel adapter named "${name}" is configured for this site.`,
+                    hint: 'Configure the channel, or send through one that is already configured.',
+                    details: { name },
+                });
+            }
+            return adapter;
+        },
+        list: () => [...byName.values()],
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAU5C;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAA;IAChD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,mBAAmB;gBACzB,OAAO,EAAE,wCAAwC,OAAO,CAAC,IAAI,IAAI;gBACjE,IAAI,EAAE,+EAA+E;gBACrF,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;aAChC,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACnC,CAAC;IAED,OAAO;QACL,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QAC/B,GAAG,CAAC,IAAI;YACN,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YAChC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,YAAY,CAAC;oBACrB,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EAAE,6BAA6B,IAAI,gCAAgC;oBAC1E,IAAI,EAAE,wEAAwE;oBAC9E,OAAO,EAAE,EAAE,IAAI,EAAE;iBAClB,CAAC,CAAA;YACJ,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;KACjC,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cogenta/channels",
+  "version": "0.1.0",
+  "description": "Channel adapter interface and registry — Telegram, Slack, Discord, email, webhooks.",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cogenta-cms/cogenta.git",
+    "directory": "packages/channels"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@cogenta/agents": "workspace:*",
+    "@cogenta/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}