@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-channels/examples/channel-sources/replay-buffer.md

@@ -2,18 +2,23 @@
 name: replay-buffer
 reference: channel-sources
 level: advanced
-description: Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline
-tags: [replay, buffer, persistence, offline, reconnect]
+description: Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline.
+tags:
+  - replay
+  - buffer
+  - persistence
+  - offline
+  - reconnect
 features:
-  - Replay configuration with maxEvents cap
+  - Replay configuration with `maxEvents` cap
   - In-memory ring buffer for event storage
-  - Replay on session connect
-  - Persistent store pattern with onConnect
+  - Where `replayBufferedEvents` actually lives (on `ChannelInstance`, not on `ChannelContext`)
+  - Persistent store pattern with `onConnect` and a user-defined Redis provider
 ---
 
 # Replay Buffer Pattern
 
-Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline
+Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline.
 
 ## Basic Replay (In-Memory)
 
@@ -38,42 +43,107 @@ class CIAlertChannel extends ChannelContext {
 }
 ```
 
-Events are automatically buffered. When a Claude Code session connects, call `replayBufferedEvents(sessionId)` to send all buffered events. Replayed events have `replayed: "true"` in their meta.
+The SDK keeps a per-channel ring buffer of the last `maxEvents` notifications. Replay is delivered via `ChannelInstance.replayBufferedEvents(sessionId)` (defined in `libs/sdk/src/channel/channel.instance.ts:223`). That method lives on the **channel instance**, not on `ChannelContext`, so you cannot call `this.replayBufferedEvents(...)` from within `onEvent`/`onConnect`.
 
-## Persistent Store Pattern (Redis/DB)
+Replay is **not** triggered automatically when a new session subscribes — there is no caller of `replayBufferedEvents` inside the SDK today. To deliver buffered events, expose a tool that resolves the channel from the registry and triggers replay explicitly (Claude Code can call this on demand, or your application can call it from a custom hook):
 
-For events that survive server restarts, load from an external store in `onConnect()`:
+```typescript
+// src/apps/alerts/tools/replay-ci-alerts.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+import type ChannelRegistry from '@frontmcp/sdk/channel/channel.registry';
+
+@Tool({
+  name: 'replay-ci-alerts',
+  description: 'Replay buffered CI alerts to the current session.',
+  inputSchema: {
+    channel_name: z.string().default('ci-alerts'),
+  },
+})
+export class ReplayCIAlertsTool extends ToolContext {
+  async execute(input) {
+    // Resolve the channel registry off scope (same cast pattern as ChannelReplyTool)
+    const scope = this.scope as unknown as { channels?: ChannelRegistry };
+    const registry = scope.channels;
+    if (!registry) {
+      return { content: [{ type: 'text', text: 'Channels are not enabled on this server.' }], isError: true };
+    }
+
+    const channel = registry.findByName(input.channel_name);
+    if (!channel) {
+      return { content: [{ type: 'text', text: `Channel "${input.channel_name}" not found.` }], isError: true };
+    }
+
+    const sessionId = this.context.sessionId;
+    const replayed = channel.replayBufferedEvents(sessionId);
+    return { content: [{ type: 'text', text: `Replayed ${replayed} buffered event(s).` }] };
+  }
+}
+```
+
+Replayed events arrive at Claude Code with `replayed: "true"` in their meta so the model can distinguish them from live events.
+
+## Persistent Store Pattern (Redis)
+
+The in-memory ring buffer does not survive process restarts. To persist events across restarts, push events into Redis and rehydrate on `onConnect()`. Inject a Redis-backed provider the same way the demo apps do (`apps/demo/src/apps/employee-time/providers/redis.provider.ts`):
 
 ```typescript
+// src/apps/alerts/providers/alerts-redis.provider.ts
+import Redis, { Redis as RedisClient } from 'ioredis';
+
+import { AsyncProvider, ProviderScope } from '@frontmcp/sdk';
+
+export default class AlertsRedisProvider {
+  readonly client: RedisClient;
+
+  constructor() {
+    this.client = new Redis({ host: 'localhost', port: 6379 });
+  }
+}
+
+export const createAlertsRedisProvider = AsyncProvider({
+  provide: AlertsRedisProvider,
+  name: 'AlertsRedisProvider',
+  scope: ProviderScope.GLOBAL,
+  inject: () => [] as const,
+  useFactory: async () => new AlertsRedisProvider(),
+});
+```
+
+Resolve the provider inside the channel via `this.get(AlertsRedisProvider)` and use it to load + record events:
+
+```typescript
+// src/apps/alerts/channels/persistent-alert.channel.ts
+import { Channel, ChannelContext, type ChannelNotification } from '@frontmcp/sdk';
+
+import AlertsRedisProvider from '../providers/alerts-redis.provider';
+
 @Channel({
   name: 'alerts',
   description: 'Persistent alerts with Redis-backed replay',
   source: { type: 'service', service: 'alert-store' },
   replay: { enabled: true, maxEvents: 500 },
 })
-class PersistentAlertChannel extends ChannelContext {
+export class PersistentAlertChannel extends ChannelContext {
   async onConnect(): Promise<void> {
-    // Load missed events from Redis on startup
-    const redis = this.get(RedisClientToken);
-    const stored = await redis.lrange('channel:alerts:buffer', 0, -1);
+    const redis = this.get(AlertsRedisProvider).client;
 
+    // Replay history from Redis into the channel pipeline
+    const stored = await redis.lrange('channel:alerts:buffer', 0, -1);
     for (const raw of stored) {
       const event = JSON.parse(raw);
       this.pushIncoming(event);
     }
 
-    // Subscribe to new events via Redis pub/sub
+    // Subscribe to new events and persist them as they arrive
     const subscriber = redis.duplicate();
-    await subscriber.subscribe('channel:alerts', (message) => {
-      const event = JSON.parse(message);
-      // Store for future replays
-      redis.rpush('channel:alerts:buffer', message);
-      redis.ltrim('channel:alerts:buffer', -500, -1);
-      // Push to connected Claude sessions
-      this.pushIncoming(event);
+    await subscriber.subscribe('channel:alerts');
+    subscriber.on('message', async (_channel, message) => {
+      await redis.rpush('channel:alerts:buffer', message);
+      await redis.ltrim('channel:alerts:buffer', -500, -1);
+      this.pushIncoming(JSON.parse(message));
     });
 
-    this.logger.info('Alert store connected, loaded history');
+    this.logger.info('Alert store connected, history loaded');
   }
 
   async onEvent(payload: unknown): Promise<ChannelNotification> {
@@ -86,20 +156,31 @@ class PersistentAlertChannel extends ChannelContext {
 }
 ```
 
+Register the provider on the app so DI can resolve it:
+
+```typescript
+@App({
+  name: 'Alerts',
+  channels: [PersistentAlertChannel],
+  providers: [createAlertsRedisProvider],
+})
+class AlertsApp {}
+```
+
 ## How Replay Works
 
-1. Events arrive via any source → `onEvent()` transforms them → notification pushed
-2. If `replay.enabled`, the notification is also stored in a ring buffer (FIFO, capped at `maxEvents`)
-3. When a new Claude Code session connects, the server can call `channel.replayBufferedEvents(sessionId)`
-4. All buffered events are sent to the new session with `replayed: "true"` in meta
-5. Claude can distinguish live events from replayed ones via the meta field
+1. Events arrive via any source -> `onEvent()` transforms them -> notification pushed to live sessions.
+2. If `replay.enabled`, each pushed notification is also stored in the channel's ring buffer (FIFO, capped at `maxEvents`).
+3. Replay is **user-triggered**: call `ChannelInstance.replayBufferedEvents(sessionId)` yourself — typically from a tool (see `ReplayCIAlertsTool` above) or from a custom session lifecycle hook in your app.
+4. Each buffered notification is sent to the target session with `replayed: "true"` injected into its meta.
+5. The persistent-store pattern shown above is independent of the in-memory buffer: you replay from Redis on `onConnect()` (which fires once when the channel boots), while the in-memory ring buffer is what `replayBufferedEvents` reads from when invoked.
 
 ## What This Demonstrates
 
-- Replay configuration with maxEvents cap
+- Replay configuration with `maxEvents` cap
 - In-memory ring buffer for event storage
-- Replay on session connect
-- Persistent store pattern with onConnect
+- Where `replayBufferedEvents` actually lives (on `ChannelInstance`, not on `ChannelContext`)
+- Persistent store pattern with `onConnect` and a user-defined Redis provider
 
 ## Related
 

package/catalog/frontmcp-channels/examples/channel-two-way/whatsapp-bridge.md

@@ -20,9 +20,30 @@ Full WhatsApp Business API bridge allowing users to chat with Claude Code via Wh
 ```typescript
 // src/apps/messaging/channels/whatsapp.channel.ts
 import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
+import { hmacSha256 } from '@frontmcp/utils';
 
 const ALLOWED_SENDERS = new Set((process.env['WHATSAPP_ALLOWED_SENDERS'] ?? '').split(',').filter(Boolean));
 
+/**
+ * Verify the X-Hub-Signature-256 header WhatsApp Cloud API attaches to every
+ * webhook delivery. The header is `sha256=<hex>` where the digest is HMAC-SHA256
+ * of the raw request body keyed by the app secret. Uses @frontmcp/utils so the
+ * same code runs in Node and Edge runtimes.
+ */
+function verifyWhatsAppSignature(rawBody: string, header: string | undefined, appSecret: string): boolean {
+  if (!header?.startsWith('sha256=')) return false;
+  const expected = header.slice('sha256='.length);
+
+  const digest = hmacSha256(new TextEncoder().encode(appSecret), new TextEncoder().encode(rawBody));
+  const actual = Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+
+  // Constant-time compare to avoid timing leaks
+  if (actual.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) diff |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  return diff === 0;
+}
+
 @Channel({
   name: 'whatsapp',
   description: 'WhatsApp chat bridge - verified users can message Claude Code',
@@ -32,7 +53,27 @@ const ALLOWED_SENDERS = new Set((process.env['WHATSAPP_ALLOWED_SENDERS'] ?? '').
 })
 export class WhatsAppChannel extends ChannelContext {
   async onEvent(payload: unknown): Promise<ChannelNotification> {
-    const { body } = payload as { body: Record<string, unknown> };
+    const { body, headers } = payload as {
+      body: Record<string, unknown>;
+      headers: Record<string, string | string[] | undefined>;
+    };
+
+    // 1. Verify webhook signature before trusting anything in the payload.
+    //
+    // NOTE: Meta's X-Hub-Signature-256 is computed over the EXACT raw HTTP body bytes.
+    // FrontMCP's `WebhookPayload.body` is the parsed JSON, so re-serializing here is
+    // approximate — re-stringification can mismatch when Meta's payload contains
+    // characters Meta encoded as `\uXXXX` escapes. For production, capture the raw
+    // body with a transport-level middleware (e.g. an Express `verify` hook on
+    // `express.json()`) and pass that string into `verifyWhatsAppSignature` instead.
+    const sigHeader = headers['x-hub-signature-256'];
+    const sig = Array.isArray(sigHeader) ? sigHeader[0] : sigHeader;
+    const appSecret = process.env['WHATSAPP_APP_SECRET'];
+    if (!appSecret || !verifyWhatsAppSignature(JSON.stringify(body), sig, appSecret)) {
+      this.logger.warn('WhatsApp: signature mismatch, dropping payload');
+      return { content: '', meta: { verified: 'false', reason: 'bad_signature' } };
+    }
+
     const entry = (body as any).entry?.[0];
     const change = entry?.changes?.[0];
     const message = change?.value?.messages?.[0];
@@ -96,7 +137,8 @@ export class WhatsAppChannel extends ChannelContext {
 
 ```typescript
 // src/main.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
+
 import { WhatsAppChannel } from './apps/messaging/channels/whatsapp.channel';
 
 @App({
@@ -116,7 +158,7 @@ export default class Server {}
 ## Setup
 
 1. Create a WhatsApp Business App at [developers.facebook.com](https://developers.facebook.com)
-2. Set environment variables: `WHATSAPP_TOKEN`, `WHATSAPP_PHONE_ID`, `WHATSAPP_ALLOWED_SENDERS`
+2. Set environment variables: `WHATSAPP_TOKEN`, `WHATSAPP_PHONE_ID`, `WHATSAPP_APP_SECRET`, `WHATSAPP_ALLOWED_SENDERS`
 3. Configure webhook URL to `https://your-server/hooks/whatsapp`
 4. Subscribe to `messages` webhook field
 

package/catalog/frontmcp-channels/references/channel-sources.md

@@ -12,6 +12,14 @@ Every channel has a source that determines how events flow into it. FrontMCP sup
 Registers an HTTP POST endpoint. External services (GitHub, CI/CD, monitoring) send payloads to this endpoint.
 
 ```typescript
+// Webhook payloads have a known shape: { body, headers, method, query? }.
+// Define the slice you need locally rather than importing an internal type.
+interface CIWebhookBody {
+  pipeline: string;
+  status: string;
+  url: string;
+}
+
 @Channel({
   name: 'ci-alerts',
   description: 'CI/CD pipeline notifications',
@@ -19,8 +27,8 @@ Registers an HTTP POST endpoint. External services (GitHub, CI/CD, monitoring) s
 })
 class CIAlertChannel extends ChannelContext {
   async onEvent(payload: unknown): Promise<ChannelNotification> {
-    const { body } = payload as WebhookPayload;
-    const data = body as { pipeline: string; status: string; url: string };
+    const { body } = payload as { body: unknown };
+    const data = body as CIWebhookBody;
     return {
       content: `CI pipeline "${data.pipeline}" ${data.status}.\nDetails: ${data.url}`,
       meta: { pipeline: data.pipeline, status: data.status },
@@ -209,6 +217,6 @@ Buffered events are replayed when a new session connects, with `replayed: "true"
 | [`job-completion`](../examples/channel-sources/job-completion.md)       | Intermediate | Notify Claude Code when background jobs and workflows complete                                                                   |
 | [`service-connector`](../examples/channel-sources/service-connector.md) | Advanced     | Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API |
 | [`file-watcher`](../examples/channel-sources/file-watcher.md)           | Intermediate | Watch files for changes and notify Claude Code in real-time                                                                      |
-| [`replay-buffer`](../examples/channel-sources/replay-buffer.md)         | Advanced     | Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline                       |
+| [`replay-buffer`](../examples/channel-sources/replay-buffer.md)         | Advanced     | Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline.                      |
 
 > See all examples in [`examples/channel-sources/`](../examples/channel-sources/)

package/catalog/frontmcp-channels/references/channel-two-way.md

@@ -15,129 +15,63 @@ Two-way channels let external users communicate with Claude Code through messagi
 4. **Reply**: Claude calls `channel-reply` tool with response text
 5. **Forward**: `onReply()` sends the reply back to the external platform
 
-## WhatsApp Business API Bridge
+## API Surface
 
-```typescript
-import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
-
-// Store verified senders for security
-const allowedSenders = new Set<string>();
+A two-way channel sets `twoWay: true` and implements two hooks on top of the regular `ChannelContext` interface:
 
+```typescript
 @Channel({
   name: 'whatsapp',
-  description: 'WhatsApp Business API bridge for Claude Code',
   source: { type: 'webhook', path: '/hooks/whatsapp' },
   twoWay: true,
   meta: { platform: 'whatsapp' },
 })
 export class WhatsAppChannel extends ChannelContext {
+  // Inbound: shape the external payload into a notification for Claude
   async onEvent(payload: unknown): Promise<ChannelNotification> {
-    const { body } = payload as { body: Record<string, unknown> };
-
-    // WhatsApp Cloud API webhook payload structure
-    const entry = (body as any).entry?.[0];
-    const change = entry?.changes?.[0];
-    const message = change?.value?.messages?.[0];
-    const contact = change?.value?.contacts?.[0];
-
-    if (!message || !contact) {
-      return { content: 'WhatsApp: received non-message webhook (status update)' };
-    }
-
-    const sender = contact.wa_id;
-    const senderName = contact.profile?.name ?? sender;
-
-    // Security: only allow verified senders
-    if (!allowedSenders.has(sender)) {
-      this.logger.warn(`WhatsApp: rejecting message from unverified sender ${sender}`);
-      return {
-        content: `WhatsApp: message from unverified sender ${senderName} (${sender}). Add to allowlist to process.`,
-        meta: { sender, sender_name: senderName, verified: 'false' },
-      };
-    }
-
-    const text = message.text?.body ?? '[non-text message]';
-
-    return {
-      content: `${senderName}: ${text}`,
-      meta: {
-        sender,
-        sender_name: senderName,
-        message_id: message.id,
-        chat_id: sender,
-      },
-    };
+    /* see whatsapp-bridge example */
   }
 
+  // Outbound: forward Claude's reply back to the platform.
+  // `meta` carries the keys you returned from onEvent (chat_id, sender, ...).
   async onReply(reply: string, meta?: Record<string, string>): Promise<void> {
-    const chatId = meta?.chat_id;
-    if (!chatId) {
-      this.logger.warn('WhatsApp reply: no chat_id in meta');
-      return;
-    }
-
-    // Send via WhatsApp Cloud API
-    const token = process.env['WHATSAPP_TOKEN'];
-    const phoneNumberId = process.env['WHATSAPP_PHONE_ID'];
-
-    await fetch(`https://graph.facebook.com/v18.0/${phoneNumberId}/messages`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        messaging_product: 'whatsapp',
-        to: chatId,
-        text: { body: reply },
-      }),
-    });
+    /* call platform send-message API */
   }
 }
 ```
 
+The full WhatsApp implementation, including sender allowlisting and the WhatsApp Cloud API call, lives in [`examples/channel-two-way/whatsapp-bridge.md`](../examples/channel-two-way/whatsapp-bridge.md).
+
 ## Telegram Bot Bridge
 
+Telegram works the same way — different webhook path, different reply API:
+
 ```typescript
 @Channel({
   name: 'telegram',
-  description: 'Telegram bot bridge for Claude Code',
   source: { type: 'webhook', path: '/hooks/telegram' },
   twoWay: true,
   meta: { platform: 'telegram' },
 })
 export class TelegramChannel extends ChannelContext {
   async onEvent(payload: unknown): Promise<ChannelNotification> {
-    const { body } = payload as { body: Record<string, unknown> };
-    const update = body as {
-      message?: {
-        chat: { id: number };
-        from: { username?: string; first_name: string; id: number };
-        text?: string;
+    const { body } = payload as {
+      body: {
+        message?: { chat: { id: number }; from: { username?: string; first_name: string; id: number }; text?: string };
       };
     };
-
-    const msg = update.message;
-    if (!msg?.text) {
-      return { content: 'Telegram: non-text update received' };
-    }
-
+    const msg = body.message;
+    if (!msg?.text) return { content: 'Telegram: non-text update' };
     const sender = msg.from.username ?? msg.from.first_name;
-
     return {
       content: `${sender}: ${msg.text}`,
-      meta: {
-        chat_id: String(msg.chat.id),
-        sender: String(msg.from.id),
-        sender_name: sender,
-      },
+      meta: { chat_id: String(msg.chat.id), sender: String(msg.from.id), sender_name: sender },
     };
   }
 
   async onReply(reply: string, meta?: Record<string, string>): Promise<void> {
     const chatId = meta?.chat_id;
     if (!chatId) return;
-
     const token = process.env['TELEGRAM_BOT_TOKEN'];
     await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
       method: 'POST',
@@ -166,16 +100,53 @@ if (isGroupMember(chatId)) {
 }
 ```
 
-### Webhook Verification
+### Webhook Signature Verification
 
-Validate webhook signatures for each platform:
+Webhook handlers must verify the request actually came from the platform. Use the HMAC helper from `@frontmcp/utils` so the same code runs in Node and Edge runtimes:
 
 ```typescript
-// WhatsApp: verify X-Hub-Signature-256 header
-// Telegram: verify secret_token parameter
-// Slack: verify X-Slack-Signature header
+import { hmacSha256 } from '@frontmcp/utils';
+
+function verifyWhatsAppSignature(rawBody: string, header: string | undefined, appSecret: string): boolean {
+  if (!header?.startsWith('sha256=')) return false;
+  const expected = header.slice('sha256='.length);
+
+  const key = new TextEncoder().encode(appSecret);
+  const data = new TextEncoder().encode(rawBody);
+  const digest = hmacSha256(key, data);
+
+  // Constant-time hex compare
+  const actual = Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+  if (actual.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) diff |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  return diff === 0;
+}
+
+// In onEvent:
+//
+// NOTE: WebhookPayload.body is the parsed JSON. For maximum signature fidelity
+// (Meta computes X-Hub-Signature-256 over the exact raw bytes), capture the raw
+// body in a transport-level middleware (e.g. express.json `verify` hook) and
+// pass that string to `verifyWhatsAppSignature` instead of `JSON.stringify(body)`.
+const { body, headers } = payload as { body: unknown; headers: Record<string, string | string[] | undefined> };
+const sig = headers['x-hub-signature-256'];
+if (
+  !verifyWhatsAppSignature(JSON.stringify(body), Array.isArray(sig) ? sig[0] : sig, process.env['WHATSAPP_APP_SECRET']!)
+) {
+  this.logger.warn('WhatsApp: signature mismatch, dropping');
+  return { content: '', meta: { verified: 'false' } };
+}
 ```
 
+Per-platform header names:
+
+| Platform | Header / mechanism                                              |
+| -------- | --------------------------------------------------------------- |
+| WhatsApp | `X-Hub-Signature-256` (HMAC-SHA256 of raw body with app secret) |
+| Telegram | `secret_token` query parameter (compare with the value you set) |
+| Slack    | `X-Slack-Signature` + `X-Slack-Request-Timestamp` (HMAC-SHA256) |
+
 ### Pairing Codes
 
 For bootstrapping trust, use pairing codes: