aegis-bridge 0.1.0

package/dist/auth.js

@@ -0,0 +1,276 @@
+/**
+ * auth.ts — API key management and authentication middleware.
+ *
+ * Issue #39: Multi-key auth with rate limiting.
+ * Keys are hashed with SHA-256 (no bcrypt dependency needed).
+ * Backward compatible with single authToken from config.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { authStoreSchema } from './validation.js';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { secureFilePermissions } from './file-utils.js';
+/** Default SSE token lifetime: 60 seconds. */
+const SSE_TOKEN_TTL_MS = 60_000;
+/** Max SSE tokens per bearer token to prevent abuse. */
+const SSE_TOKEN_MAX_PER_KEY = 5;
+/** #583: Minimum interval between batch creation requests per key (5 seconds). */
+const BATCH_COOLDOWN_MS = 5_000;
+/** Route-level auth policy for bearer tokens. */
+export function classifyBearerTokenForRoute(token, isSSERoute) {
+    if (!isSSERoute)
+        return 'bearer';
+    return token.startsWith('sse_') ? 'sse' : 'reject';
+}
+export class AuthManager {
+    keysFile;
+    store = { keys: [] };
+    rateLimits = new Map();
+    masterToken;
+    /** #297: Short-lived SSE tokens. Keyed by token string for O(1) lookup. */
+    sseTokens = new Map();
+    /** Track how many SSE tokens each bearer key has outstanding. */
+    sseTokenCounts = new Map();
+    /** #414: Mutex to prevent concurrent SSE token generation from exceeding per-key limits. */
+    sseMutex = Promise.resolve();
+    /** #583: Last batch creation timestamp per key ID. */
+    batchRateLimits = new Map();
+    constructor(keysFile, masterToken = '') {
+        this.keysFile = keysFile;
+        this.masterToken = masterToken;
+    }
+    /** Load keys from disk. */
+    async load() {
+        if (existsSync(this.keysFile)) {
+            try {
+                const raw = await readFile(this.keysFile, 'utf-8');
+                const parsed = authStoreSchema.safeParse(JSON.parse(raw));
+                if (parsed.success) {
+                    this.store = parsed.data;
+                }
+            }
+            catch { /* corrupted or unreadable keys file — start fresh */
+                this.store = { keys: [] };
+            }
+        }
+    }
+    /** Save keys to disk. */
+    async save() {
+        const dir = dirname(this.keysFile);
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+        await writeFile(this.keysFile, JSON.stringify(this.store, null, 2), { mode: 0o600 });
+        await secureFilePermissions(this.keysFile);
+    }
+    /** Create a new API key. Returns the plaintext key (only shown once). */
+    async createKey(name, rateLimit = 100) {
+        const id = randomBytes(8).toString('hex');
+        const key = `aegis_${randomBytes(32).toString('hex')}`;
+        const hash = AuthManager.hashKey(key);
+        const apiKey = {
+            id,
+            name,
+            hash,
+            createdAt: Date.now(),
+            lastUsedAt: 0,
+            rateLimit,
+        };
+        this.store.keys.push(apiKey);
+        await this.save();
+        return { id, key, name };
+    }
+    /** List keys (without hashes). */
+    listKeys() {
+        return this.store.keys.map(({ hash: _, ...rest }) => rest);
+    }
+    /** Revoke a key by ID. */
+    async revokeKey(id) {
+        const idx = this.store.keys.findIndex(k => k.id === id);
+        if (idx === -1)
+            return false;
+        this.store.keys.splice(idx, 1);
+        this.rateLimits.delete(id);
+        await this.save();
+        return true;
+    }
+    /**
+     * Validate a bearer token.
+     * Returns { valid, keyId, rateLimited } or null if no auth configured.
+     */
+    validate(token) {
+        // No auth configured and no keys → allow all
+        if (!this.masterToken && this.store.keys.length === 0) {
+            return { valid: true, keyId: null, rateLimited: false };
+        }
+        // Check master token (backward compat) — timing-safe comparison (#402)
+        if (this.masterToken && AuthManager.timingSafeStringEqual(token, this.masterToken)) {
+            return { valid: true, keyId: 'master', rateLimited: false };
+        }
+        // Check API keys
+        const hash = AuthManager.hashKey(token);
+        const key = this.store.keys.find(k => k.hash === hash);
+        if (!key) {
+            return { valid: false, keyId: null, rateLimited: false };
+        }
+        // Rate limiting
+        const bucket = this.rateLimits.get(key.id) || { count: 0, windowStart: Date.now() };
+        const now = Date.now();
+        const windowMs = 60_000; // 1 minute
+        if (now - bucket.windowStart > windowMs) {
+            // New window
+            bucket.count = 1;
+            bucket.windowStart = now;
+        }
+        else {
+            bucket.count++;
+        }
+        this.rateLimits.set(key.id, bucket);
+        if (bucket.count > key.rateLimit) {
+            return { valid: true, keyId: key.id, rateLimited: true };
+        }
+        // Issue #841: Only update lastUsedAt for accepted requests, not rate-limited ones
+        key.lastUsedAt = Date.now();
+        return { valid: true, keyId: key.id, rateLimited: false };
+    }
+    /** Hash a key with SHA-256. */
+    static hashKey(key) {
+        return createHash('sha256').update(key).digest('hex');
+    }
+    /** Constant-time equality check for secret strings. */
+    static timingSafeStringEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+    }
+    /** #583: Check and update batch rate limit for a key. Returns true if rate-limited. */
+    checkBatchRateLimit(keyId) {
+        const id = keyId ?? 'anonymous';
+        const now = Date.now();
+        const lastBatch = this.batchRateLimits.get(id);
+        if (lastBatch !== undefined && now - lastBatch < BATCH_COOLDOWN_MS) {
+            return true;
+        }
+        this.batchRateLimits.set(id, now);
+        return false;
+    }
+    /** #398: Sweep stale rate limit buckets. Prune entries with expired windows. */
+    sweepStaleRateLimits() {
+        const now = Date.now();
+        const windowMs = 60_000; // 1 minute
+        for (const [keyId, bucket] of this.rateLimits) {
+            if (now - bucket.windowStart > windowMs) {
+                this.rateLimits.delete(keyId);
+            }
+        }
+        // #583: Prune expired batch rate limit entries
+        for (const [keyId, ts] of this.batchRateLimits) {
+            if (now - ts > BATCH_COOLDOWN_MS) {
+                this.batchRateLimits.delete(keyId);
+            }
+        }
+    }
+    /** Check if auth is enabled (master token or any keys). */
+    get authEnabled() {
+        return !!this.masterToken || this.store.keys.length > 0;
+    }
+    // ── SSE Token Management (Issue #297) ────────────────────────
+    /**
+     * Generate a short-lived, single-use SSE token.
+     * The caller must already be authenticated (validated via bearer token).
+     * Returns the token string and its expiry timestamp.
+     * #414: Async with mutex to prevent concurrent calls from exceeding per-key limits.
+     */
+    async generateSSEToken(keyId) {
+        // Acquire mutex — chain onto the previous operation
+        let release = () => { };
+        const lock = new Promise((resolve) => { release = resolve; });
+        const previous = this.sseMutex;
+        this.sseMutex = lock;
+        // #509: await + try/finally together so release() fires even if previous rejects
+        // #573: catch prior rejection so it doesn't propagate and block subsequent callers
+        try {
+            await previous.catch(() => { });
+            // Cleanup expired tokens first
+            this.cleanExpiredSSETokens();
+            // Enforce per-key limit
+            const current = this.sseTokenCounts.get(keyId) ?? 0;
+            if (current >= SSE_TOKEN_MAX_PER_KEY) {
+                throw new Error(`SSE token limit reached (${SSE_TOKEN_MAX_PER_KEY} outstanding)`);
+            }
+            const token = `sse_${randomBytes(32).toString('hex')}`;
+            const expiresAt = Date.now() + SSE_TOKEN_TTL_MS;
+            this.sseTokens.set(token, { token, expiresAt, used: false, keyId });
+            this.sseTokenCounts.set(keyId, current + 1);
+            return { token, expiresAt };
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Validate and consume a short-lived SSE token.
+     * Returns true if valid (and marks it as used), false otherwise.
+     * #826: Async with mutex to prevent concurrent validation/generation from
+     * racing on shared state (sseTokens, sseTokenCounts).
+     */
+    async validateSSEToken(token) {
+        // Acquire mutex — chain onto the previous operation
+        let release = () => { };
+        const lock = new Promise((resolve) => { release = resolve; });
+        const previous = this.sseMutex;
+        this.sseMutex = lock;
+        // #573: catch prior rejection so it doesn't propagate and block subsequent callers
+        try {
+            await previous.catch(() => { });
+            const entry = this.sseTokens.get(token);
+            if (!entry)
+                return false;
+            // Already used
+            if (entry.used) {
+                this.sseTokens.delete(token);
+                return false;
+            }
+            // Expired
+            if (Date.now() > entry.expiresAt) {
+                this.sseTokens.delete(token);
+                return false;
+            }
+            // Valid — consume it
+            entry.used = true;
+            const keyId = entry.keyId;
+            this.sseTokens.delete(token);
+            // #357: Decrement outstanding count so generateSSEToken doesn't over-limit
+            const count = this.sseTokenCounts.get(keyId);
+            if (count !== undefined) {
+                if (count <= 1) {
+                    this.sseTokenCounts.delete(keyId);
+                }
+                else {
+                    this.sseTokenCounts.set(keyId, count - 1);
+                }
+            }
+            return true;
+        }
+        finally {
+            release();
+        }
+    }
+    /** Remove expired SSE tokens and recount per-key outstanding. */
+    cleanExpiredSSETokens() {
+        const now = Date.now();
+        // Remove expired
+        for (const [key, entry] of this.sseTokens) {
+            if (now > entry.expiresAt) {
+                this.sseTokens.delete(key);
+            }
+        }
+        // Rebuild counts from surviving tokens
+        this.sseTokenCounts.clear();
+        for (const entry of this.sseTokens.values()) {
+            const count = this.sseTokenCounts.get(entry.keyId) ?? 0;
+            this.sseTokenCounts.set(entry.keyId, count + 1);
+        }
+    }
+}

package/dist/channels/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * channels/index.ts — Re-exports for the channel plugin system.
+ */
+export type { Channel, SessionEvent, SessionEventPayload, InboundCommand, InboundHandler, } from './types.js';
+export { ChannelManager } from './manager.js';
+export { TelegramChannel, type TelegramChannelConfig } from './telegram.js';
+export { WebhookChannel, type WebhookChannelConfig, type WebhookEndpoint, type DeadLetterEntry } from './webhook.js';
+export { quickUpdate, quickUpdateCode, taskComplete, alert, yesNo, decision, progress, esc, bold, code, italic, statusEmoji, type StyledMessage, type InlineButton, type StatusEmoji, type TaskCompleteData, type AlertData, type AlertButtons, type DecisionOption, type ProgressStep, } from './telegram-style.js';

package/dist/channels/index.js

@@ -0,0 +1,8 @@
+/**
+ * channels/index.ts — Re-exports for the channel plugin system.
+ */
+export { ChannelManager } from './manager.js';
+export { TelegramChannel } from './telegram.js';
+export { WebhookChannel } from './webhook.js';
+// Telegram Style Guide — 6 standard message types
+export { quickUpdate, quickUpdateCode, taskComplete, alert, yesNo, decision, progress, esc, bold, code, italic, statusEmoji, } from './telegram-style.js';

package/dist/channels/manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * channels/manager.ts — Routes events to all registered channels.
+ *
+ * The bridge calls ChannelManager methods. The manager fans out
+ * to every registered channel, swallowing per-channel errors so
+ * one broken channel never kills the bridge.
+ */
+import type { Channel, SessionEventPayload, InboundHandler } from './types.js';
+/**
+ * Thrown for retriable failures (5xx server errors, network timeouts).
+ * Only these increment the circuit breaker failure count.
+ * 4xx client errors are thrown as plain Error and do NOT trip the breaker.
+ */
+export declare class RetriableError extends Error {
+    constructor(message: string);
+}
+export declare class ChannelManager {
+    private channels;
+    private inboundHandler;
+    private health;
+    /** Consecutive failures before disabling a channel. */
+    static readonly FAILURE_THRESHOLD = 5;
+    /** Cooldown period in ms when a channel is disabled (5 min). */
+    static readonly COOLDOWN_MS: number;
+    /** Register a channel. Must be called before init(). */
+    register(channel: Channel): void;
+    /** Initialize all channels. Pass the inbound handler for bidirectional channels. */
+    init(onInbound: InboundHandler): Promise<void>;
+    /** Shut down all channels. */
+    destroy(): Promise<void>;
+    /** Fan out a session-created event. */
+    sessionCreated(payload: SessionEventPayload): Promise<void>;
+    /** Fan out a session-ended event. */
+    sessionEnded(payload: SessionEventPayload): Promise<void>;
+    /** Fan out a message event. */
+    message(payload: SessionEventPayload): Promise<void>;
+    /** Fan out a status change event. */
+    statusChange(payload: SessionEventPayload): Promise<void>;
+    /** Fan out a swarm teammate event. */
+    swarmEvent(payload: SessionEventPayload): Promise<void>;
+    /** How many channels are registered. */
+    get count(): number;
+    /** Get all registered channels (for wiring optional dependencies). */
+    getChannels(): readonly Channel[];
+    /** Fan out to channels, respecting filters, swallowing errors. */
+    private fanOut;
+}

package/dist/channels/manager.js

@@ -0,0 +1,115 @@
+/**
+ * channels/manager.ts — Routes events to all registered channels.
+ *
+ * The bridge calls ChannelManager methods. The manager fans out
+ * to every registered channel, swallowing per-channel errors so
+ * one broken channel never kills the bridge.
+ */
+/**
+ * Thrown for retriable failures (5xx server errors, network timeouts).
+ * Only these increment the circuit breaker failure count.
+ * 4xx client errors are thrown as plain Error and do NOT trip the breaker.
+ */
+export class RetriableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RetriableError';
+    }
+}
+export class ChannelManager {
+    channels = [];
+    inboundHandler = null;
+    health = new Map();
+    /** Consecutive failures before disabling a channel. */
+    static FAILURE_THRESHOLD = 5;
+    /** Cooldown period in ms when a channel is disabled (5 min). */
+    static COOLDOWN_MS = 5 * 60 * 1000;
+    /** Register a channel. Must be called before init(). */
+    register(channel) {
+        this.channels.push(channel);
+    }
+    /** Initialize all channels. Pass the inbound handler for bidirectional channels. */
+    async init(onInbound) {
+        this.inboundHandler = onInbound;
+        for (const ch of this.channels) {
+            try {
+                await ch.init?.(onInbound);
+                console.log(`Channel initialized: ${ch.name}`);
+            }
+            catch (e) {
+                console.error(`Channel ${ch.name} failed to init:`, e);
+            }
+        }
+    }
+    /** Shut down all channels. */
+    async destroy() {
+        for (const ch of this.channels) {
+            try {
+                await ch.destroy?.();
+            }
+            catch (e) {
+                console.error(`Channel ${ch.name} failed to destroy:`, e);
+            }
+        }
+    }
+    /** Fan out a session-created event. */
+    async sessionCreated(payload) {
+        await this.fanOut(payload, ch => ch.onSessionCreated?.(payload));
+    }
+    /** Fan out a session-ended event. */
+    async sessionEnded(payload) {
+        await this.fanOut(payload, ch => ch.onSessionEnded?.(payload));
+    }
+    /** Fan out a message event. */
+    async message(payload) {
+        await this.fanOut(payload, ch => ch.onMessage?.(payload));
+    }
+    /** Fan out a status change event. */
+    async statusChange(payload) {
+        await this.fanOut(payload, ch => ch.onStatusChange?.(payload));
+    }
+    /** Fan out a swarm teammate event. */
+    async swarmEvent(payload) {
+        await this.fanOut(payload, ch => ch.onStatusChange?.(payload));
+    }
+    /** How many channels are registered. */
+    get count() {
+        return this.channels.length;
+    }
+    /** Get all registered channels (for wiring optional dependencies). */
+    getChannels() {
+        return this.channels;
+    }
+    /** Fan out to channels, respecting filters, swallowing errors. */
+    async fanOut(payload, call) {
+        const promises = this.channels.map(async (ch) => {
+            // Circuit breaker: skip disabled channels during cooldown
+            const health = this.health.get(ch.name);
+            if (health && Date.now() < health.disabledUntil)
+                return;
+            try {
+                // Check filter
+                if (ch.filter && !ch.filter(payload.event))
+                    return;
+                await call(ch);
+                // Success — reset failure count (channel may have been in cooldown)
+                this.health.set(ch.name, { failCount: 0, disabledUntil: 0 });
+            }
+            catch (e) {
+                console.error(`Channel ${ch.name} error on ${payload.event}:`, e);
+                // Only count retriable errors (5xx, network) toward circuit breaker.
+                // 4xx client errors are non-retriable — the server is healthy.
+                if (!(e instanceof RetriableError))
+                    return;
+                const h = this.health.get(ch.name) ?? { failCount: 0, disabledUntil: 0 };
+                h.failCount++;
+                if (h.failCount >= ChannelManager.FAILURE_THRESHOLD) {
+                    h.disabledUntil = Date.now() + ChannelManager.COOLDOWN_MS;
+                    console.warn(`Channel ${ch.name} disabled after ${h.failCount} consecutive failures, cooldown until ${new Date(h.disabledUntil).toISOString()}`);
+                }
+                this.health.set(ch.name, h);
+            }
+        });
+        await Promise.allSettled(promises);
+    }
+}

package/dist/channels/telegram-style.d.ts

@@ -0,0 +1,118 @@
+/**
+ * channels/telegram-style.ts — Telegram Message Style Guide
+ *
+ * 6 standard message types for clean, consistent Telegram UX.
+ * Rule: readable in 2 seconds. Max 2 button rows. Always an escape hatch.
+ *
+ * Types:
+ *   ① quickUpdate  — one-liner (70% of messages)
+ *   ② taskComplete — post-merge quality gate card
+ *   ③ alert        — error/crash requiring action
+ *   ④ yesNo        — binary question
+ *   ⑤ decision     — technical choice with context + escape hatch
+ *   ⑥ progress     — pipeline/deploy with ASCII progress bar
+ */
+export declare function esc(text: string): string;
+export declare function bold(text: string): string;
+export declare function code(text: string): string;
+export declare function italic(text: string): string;
+/** Telegram inline keyboard button. */
+export interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+/** Styled message ready to send via Telegram API. */
+export interface StyledMessage {
+    text: string;
+    parse_mode: 'HTML';
+    reply_markup?: {
+        inline_keyboard: InlineButton[][];
+    };
+}
+export type StatusEmoji = '🟢' | '✅' | '⚠️' | '🔴' | '❌' | '🔄' | '🔨' | '🚀';
+export declare function statusEmoji(status: string): StatusEmoji;
+/**
+ * One-liner status update. 70% of all messages.
+ * No buttons, no separators. Emoji + text + optional data.
+ */
+export declare function quickUpdate(emoji: StatusEmoji | string, message: string): StyledMessage;
+/**
+ * Quick update with inline code for technical data.
+ * e.g. quickUpdateCode('🟢', 'CI verde su', 'main', '— 150/150 test ✅')
+ */
+export declare function quickUpdateCode(emoji: StatusEmoji | string, prefix: string, codeText: string, suffix?: string): StyledMessage;
+export interface TaskCompleteData {
+    /** Issue/task reference, e.g. "issue-7" */
+    taskRef: string;
+    /** Short description */
+    title: string;
+    /** Duration string, e.g. "28 min" */
+    duration: string;
+    /** Branch name */
+    branch: string;
+    /** Quality gate results: [label, passed][] */
+    checks: Array<[string, boolean]>;
+    /** Optional PR URL */
+    prUrl?: string;
+}
+/**
+ * Post-merge/completion card with quality gate.
+ * 3 lines max + 1 row of buttons.
+ */
+export declare function taskComplete(data: TaskCompleteData, buttons?: {
+    merge?: string;
+    review?: string;
+    close?: string;
+}): StyledMessage;
+export interface AlertData {
+    /** Short title, e.g. "Session crash" */
+    title: string;
+    /** Session/resource id, e.g. "sess-4a7b" */
+    resourceId: string;
+    /** Technical details (max 3 lines, shown in monospace) */
+    details: string;
+}
+export interface AlertButtons {
+    restart?: string;
+    log?: string;
+    ignore?: string;
+}
+/**
+ * Error/crash alert requiring action.
+ * Monospace block for technical details + 1 row of buttons.
+ */
+export declare function alert(data: AlertData, buttons?: AlertButtons): StyledMessage;
+/**
+ * Binary question. 2 buttons, zero ambiguity.
+ * The "no" label should describe what happens if declined.
+ */
+export declare function yesNo(question: string, yesLabel: string, noLabel: string, yesCallback: string, noCallback: string): StyledMessage;
+export interface DecisionOption {
+    emoji: string;
+    label: string;
+    description: string;
+    callback: string;
+}
+/**
+ * Technical decision with context + escape hatch.
+ * The ONLY type allowed 2 rows of buttons.
+ * Max 3 options + always "Decidi tu" / "Parliamone".
+ */
+export declare function decision(question: string, options: DecisionOption[], escapeCallbacks?: {
+    decideTu?: string;
+    parliamone?: string;
+}): StyledMessage;
+export interface ProgressStep {
+    label: string;
+    /** Duration string if done, e.g. "2.1s" */
+    duration?: string;
+    done: boolean;
+}
+/**
+ * Progress/pipeline card with ASCII bar.
+ * Updates via editMessageText — never send a new message for refresh.
+ */
+export declare function progress(title: string, steps: ProgressStep[], percent: number, buttons?: {
+    pause?: string;
+    cancel?: string;
+}): StyledMessage;