claudecode-omc 4.5.7 → 4.8.0

package/dist/notifications/slack-socket.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Slack Socket Mode Client
+ *
+ * Minimal implementation of Slack Socket Mode for receiving messages.
+ * Uses Node.js built-in WebSocket (available in Node 20+) to avoid
+ * adding heavy SDK dependencies.
+ *
+ * Protocol:
+ * 1. POST apps.connections.open with app-level token to get WSS URL
+ * 2. Connect via WebSocket
+ * 3. Receive envelope events, send acknowledgements
+ * 4. Handle reconnection with exponential backoff
+ *
+ * Security:
+ * - App-level token (xapp-...) only used for Socket Mode WebSocket
+ * - Bot token (xoxb-...) only used for Web API calls
+ * - Channel filtering ensures messages from other channels are ignored
+ * - HMAC-SHA256 signing secret verification (Slack v0 signatures)
+ * - Timestamp-based replay attack prevention (5-minute window)
+ * - Message envelope structure validation
+ * - Connection state tracking (reject messages during reconnection windows)
+ *
+ * References:
+ * - https://api.slack.com/authentication/verifying-requests-from-slack
+ * - https://api.slack.com/apis/socket-mode
+ */
+/** Connection states for Slack Socket Mode */
+export type SlackConnectionState = 'disconnected' | 'connecting' | 'authenticated' | 'reconnecting';
+/** Result of message validation */
+export interface SlackValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/** Slack Socket Mode message envelope */
+export interface SlackSocketEnvelope {
+    envelope_id: string;
+    type: string;
+    payload?: Record<string, unknown>;
+    accepts_response_payload?: boolean;
+    retry_attempt?: number;
+    retry_reason?: string;
+}
+/**
+ * Verify Slack request signature using HMAC-SHA256.
+ *
+ * Implements Slack's v0 signing verification:
+ *   sig_basestring = 'v0:' + timestamp + ':' + body
+ *   signature = 'v0=' + HMAC-SHA256(signing_secret, sig_basestring)
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Includes replay protection via timestamp validation.
+ */
+export declare function verifySlackSignature(signingSecret: string, signature: string, timestamp: string, body: string): boolean;
+/**
+ * Check if a request timestamp is within the acceptable window.
+ *
+ * Rejects timestamps older than maxAgeSeconds (default: 5 minutes)
+ * to prevent replay attacks.
+ */
+export declare function isTimestampValid(timestamp: string, maxAgeSeconds?: number): boolean;
+/**
+ * Validate Slack Socket Mode message envelope structure.
+ *
+ * Ensures the message has required fields and a valid type
+ * before it can be processed for session injection.
+ */
+export declare function validateSlackEnvelope(data: unknown): SlackValidationResult;
+/**
+ * Connection state tracker for Slack Socket Mode.
+ *
+ * Tracks authentication status across the connection lifecycle:
+ * - disconnected: No WebSocket connection
+ * - connecting: WebSocket opening, not yet authenticated
+ * - authenticated: Hello message received, ready to process
+ * - reconnecting: Connection lost, attempting to re-establish
+ *
+ * Messages are ONLY processed in the 'authenticated' state.
+ * This prevents injection during reconnection windows where
+ * authentication has not been re-established.
+ */
+export declare class SlackConnectionStateTracker {
+    private state;
+    private authenticatedAt;
+    private reconnectCount;
+    private readonly maxReconnectAttempts;
+    private messageQueue;
+    private readonly maxQueueSize;
+    constructor(options?: {
+        maxReconnectAttempts?: number;
+        maxQueueSize?: number;
+    });
+    getState(): SlackConnectionState;
+    getReconnectCount(): number;
+    getAuthenticatedAt(): number | null;
+    /** Transition to connecting state. */
+    onConnecting(): void;
+    /**
+     * Transition to authenticated state (received 'hello' message).
+     * Resets reconnect counter on successful authentication.
+     */
+    onAuthenticated(): void;
+    /**
+     * Transition to reconnecting state.
+     * Increments reconnect counter and clears authentication timestamp.
+     */
+    onReconnecting(): void;
+    /**
+     * Transition to disconnected state.
+     * Clears message queue to prevent processing stale messages.
+     */
+    onDisconnected(): void;
+    /** Check if maximum reconnection attempts have been exceeded. */
+    hasExceededMaxReconnects(): boolean;
+    /**
+     * Check if messages can be safely processed in the current state.
+     * Only allows processing when the connection is authenticated.
+     */
+    canProcessMessages(): boolean;
+    /**
+     * Queue a message for processing after reconnection.
+     * Drops oldest messages when queue exceeds maxQueueSize to
+     * prevent unbounded memory growth.
+     *
+     * Returns true if queued, false if queue is at capacity (oldest was dropped).
+     */
+    queueMessage(envelope: SlackSocketEnvelope): boolean;
+    /**
+     * Drain the message queue (called after re-authentication).
+     * Returns queued messages and clears the queue.
+     */
+    drainQueue(): SlackSocketEnvelope[];
+    /** Get current queue size. */
+    getQueueSize(): number;
+}
+/**
+ * Validate a Slack WebSocket message before session injection.
+ *
+ * Performs all validation checks in order:
+ * 1. Connection state verification (must be authenticated)
+ * 2. JSON parsing
+ * 3. Message envelope structure validation
+ * 4. Signing secret verification (when signing material is provided)
+ *
+ * Returns validation result with reason on failure.
+ */
+export declare function validateSlackMessage(rawMessage: string, connectionState: SlackConnectionStateTracker, signingSecret?: string, signature?: string, timestamp?: string): SlackValidationResult;
+/** Slack message event payload */
+export interface SlackMessageEvent {
+    type: string;
+    channel: string;
+    user: string;
+    text: string;
+    ts: string;
+    thread_ts?: string;
+}
+/** Socket Mode configuration */
+export interface SlackSocketConfig {
+    appToken: string;
+    botToken: string;
+    channelId: string;
+    /** Optional signing secret for additional message verification */
+    signingSecret?: string;
+}
+type MessageHandler = (event: SlackMessageEvent) => void | Promise<void>;
+type LogFn = (message: string) => void;
+/**
+ * Minimal Slack Socket Mode client.
+ *
+ * Establishes a WebSocket connection to Slack's Socket Mode endpoint,
+ * receives events, acknowledges them, and dispatches message events
+ * to the registered handler.
+ */
+export declare class SlackSocketClient {
+    private readonly config;
+    private readonly onMessage;
+    private ws;
+    private reconnectAttempts;
+    private readonly maxReconnectAttempts;
+    private readonly baseReconnectDelayMs;
+    private readonly maxReconnectDelayMs;
+    private isShuttingDown;
+    private reconnectTimer;
+    private readonly connectionState;
+    private onWsOpen;
+    private onWsMessage;
+    private onWsClose;
+    private onWsError;
+    private readonly log;
+    constructor(config: SlackSocketConfig, onMessage: MessageHandler, log: LogFn);
+    /** Get the connection state tracker for external inspection. */
+    getConnectionState(): SlackConnectionStateTracker;
+    /**
+     * Start the Socket Mode connection.
+     * Obtains a WebSocket URL from Slack and connects.
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully shut down the connection.
+     */
+    stop(): void;
+    /**
+     * Remove all event listeners from the current WebSocket, close it,
+     * and null the reference. Safe to call multiple times.
+     */
+    private cleanupWs;
+    /**
+     * Establish WebSocket connection to Slack Socket Mode.
+     */
+    private connect;
+    /**
+     * Process a Socket Mode envelope.
+     *
+     * Envelope types:
+     * - hello: connection established
+     * - disconnect: server requesting reconnect
+     * - events_api: contains event payloads (messages, etc.)
+     */
+    private handleEnvelope;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+}
+/**
+ * Send a message via Slack Web API chat.postMessage.
+ * Returns the message timestamp (ts) which serves as Slack's message ID.
+ */
+export declare function postSlackBotMessage(botToken: string, channel: string, text: string): Promise<{
+    ok: boolean;
+    ts?: string;
+    error?: string;
+}>;
+/**
+ * Add a reaction to a Slack message (for injection confirmation).
+ */
+export declare function addSlackReaction(botToken: string, channel: string, timestamp: string, emoji?: string): Promise<void>;
+/**
+ * Send a threaded reply in Slack (for injection confirmation).
+ */
+export declare function replySlackThread(botToken: string, channel: string, threadTs: string, text: string): Promise<void>;
+export {};
+//# sourceMappingURL=slack-socket.d.ts.map

package/dist/notifications/slack-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-socket.d.ts","sourceRoot":"","sources":["../../src/notifications/slack-socket.ts"],"names":[],"mappings":"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"}