@wolpertingerlabs/drawlatch 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/remote/caller-bootstrap.js

@@ -0,0 +1,270 @@
+/**
+ * Caller provisioning — drawlatch is the sole issuer of caller key material.
+ *
+ * One primitive, two delivery modes (see plans/caller-credential-issuance.md):
+ *   - `issueCallerBundle()` — mint a keypair IN MEMORY, persist only the public
+ *     half, and return the credential bundle (download via the admin API, or the
+ *     `drawlatch issue-caller` CLI). The caller PRIVATE key never touches
+ *     drawlatch disk; it lives only inside the returned bundle.
+ *   - `issueLocalCaller()` — same primitive, but write the UNPACKED key files
+ *     straight into a co-located callboard's keys dir over the shared filesystem.
+ *     The same-host write IS the trust proof (replaces the old enroll-token dance).
+ *
+ * `createCallerWithKeys()` (priv+pub on drawlatch disk) is retained for the
+ * password-gated `POST /api/admin/callers` create endpoint and tests.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRemoteConfig, saveRemoteConfig, getCallerKeysDir, } from '../shared/config.js';
+import { createCaller, exportServerPublicKeys, serverFingerprint, saveCallerPublicKeys, } from '../shared/crypto/key-manager.js';
+import { generateKeyBundle, serializeKeyBundle, extractPublicKeys, serializePublicKeys, fingerprint, } from '../shared/crypto/keys.js';
+import { generateBundleSalt, deriveBundleKey, encryptBundleField, DEFAULT_SCRYPT_PARAMS, } from '../shared/protocol/caller-bundle-crypto.js';
+import { setEnvVars } from '../shared/env-utils.js';
+import { createLogger } from '../shared/logger.js';
+const log = createLogger('caller-bootstrap');
+/** Valid caller alias: starts with a letter/number, then letters/numbers/-/_. */
+export const CALLER_ALIAS_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+function assertValidAlias(alias) {
+    if (!CALLER_ALIAS_REGEX.test(alias)) {
+        throw new Error('Invalid alias: must start with a letter or number and contain only ' +
+            'letters, numbers, hyphens, and underscores');
+    }
+}
+/** Clone the `default` caller's connections (the new-caller default access). */
+function defaultConnections(config) {
+    const defaultCaller = config.callers.default;
+    return [...(defaultCaller?.connections ?? [])];
+}
+/**
+ * Create a caller WITH a fresh keypair on drawlatch disk (priv+pub), registered
+ * in remote.config.json. Used by the dashboard "New caller" action.
+ *
+ * Throws on invalid alias, or if the caller (config entry or key dir) exists.
+ */
+export function createCallerWithKeys(alias, opts = {}) {
+    assertValidAlias(alias);
+    const config = loadRemoteConfig();
+    if (alias in config.callers || callerKeyDirExists(alias)) {
+        throw new Error(`Caller "${alias}" already exists`);
+    }
+    // Generate the caller's keypair under keys/callers/<alias>/.
+    const { publicKeys, fingerprint: fp } = createCaller(alias);
+    const name = opts.name ?? alias;
+    const connections = opts.connections ?? defaultConnections(config);
+    config.callers[alias] = { name, connections };
+    saveRemoteConfig(config);
+    log.info(`Created caller "${alias}" with keypair (${connections.length} connection(s), fingerprint ${fp})`);
+    return {
+        alias,
+        name,
+        fingerprint: fp,
+        publicKeys,
+        keysDir: path.join(getCallerKeysDir(), alias),
+        connections,
+    };
+}
+/** Whether a caller key directory already holds key material. */
+function callerKeyDirExists(alias) {
+    const dir = path.join(getCallerKeysDir(), alias);
+    return (fs.existsSync(path.join(dir, 'signing.pub.pem')) ||
+        fs.existsSync(path.join(dir, 'signing.key.pem')));
+}
+/**
+ * Issue (or re-issue / rotate) a caller credential bundle.
+ *
+ *   1. Generate the Ed25519 + X25519 keypair IN MEMORY.
+ *   2. Register/update the caller in remote.config.json (connections, name,
+ *      source='bundle-issued').
+ *   3. Persist ONLY the public keys to keys/callers/<alias>/ (the private key
+ *      never touches drawlatch disk).
+ *   4. Assemble the v1 bundle (caller priv+pub, server pub-only, endpoint,
+ *      fingerprints, connections), optionally passphrase-wrapping the two
+ *      private PEMs.
+ *   5. Zero the derived key material from memory and return the bundle.
+ *
+ * Re-issuing an existing caller mints a FRESH keypair and overwrites the stored
+ * public key — invalidating the prior credential (the old private key can no
+ * longer authenticate). The bundle is returned once; drawlatch keeps no copy of
+ * the private material, so it is unrecoverable afterward.
+ */
+export function issueCallerBundle(opts) {
+    const { alias, endpointUrl, passphrase } = opts;
+    assertValidAlias(alias);
+    if (typeof endpointUrl !== 'string' || endpointUrl.trim() === '') {
+        throw new Error('endpointUrl is required');
+    }
+    const config = loadRemoteConfig();
+    const existing = config.callers[alias];
+    // Mint the keypair in memory and serialize before any disk writes.
+    const bundleKeys = generateKeyBundle();
+    const serialized = serializeKeyBundle(bundleKeys);
+    const publicKeys = serializePublicKeys(extractPublicKeys(bundleKeys));
+    const callerFp = fingerprint(extractPublicKeys(bundleKeys));
+    // Resolve name + connections (preserve existing values on re-issue).
+    const name = opts.name ?? existing?.name ?? alias;
+    const connections = opts.connections ?? existing?.connections ?? defaultConnections(config);
+    // Register/update the caller, preserving any unrelated fields (env, overrides…).
+    config.callers[alias] = {
+        ...(existing ?? {}),
+        name,
+        connections,
+        source: 'bundle-issued',
+    };
+    saveRemoteConfig(config);
+    // Persist ONLY the public keys (drops any stale private files from a prior mint).
+    saveCallerPublicKeys(alias, publicKeys);
+    const serverPub = exportServerPublicKeys();
+    const serverFp = serverFingerprint();
+    // Optionally passphrase-wrap the two private PEMs. The derived key is zeroed
+    // immediately after use; the plaintext PEMs are only referenced transiently.
+    let encryption = null;
+    let callerSigningPriv = serialized.signing.privateKey;
+    let callerExchangePriv = serialized.exchange.privateKey;
+    if (passphrase !== undefined && passphrase !== '') {
+        encryption = { kdf: 'scrypt', salt: generateBundleSalt(), ...DEFAULT_SCRYPT_PARAMS, alg: 'aes-256-gcm' };
+        const key = deriveBundleKey(passphrase, encryption);
+        callerSigningPriv = encryptBundleField(serialized.signing.privateKey, key);
+        callerExchangePriv = encryptBundleField(serialized.exchange.privateKey, key);
+        key.fill(0);
+    }
+    const bundle = {
+        version: 1,
+        callerAlias: alias,
+        fingerprint: callerFp,
+        createdAt: opts.createdAt ?? new Date().toISOString(),
+        expiresAt: null,
+        endpointUrl,
+        serverKeyFingerprint: serverFp,
+        connections,
+        caller: {
+            signing: { priv: callerSigningPriv, pub: serialized.signing.publicKey },
+            exchange: { priv: callerExchangePriv, pub: serialized.exchange.publicKey },
+        },
+        server: {
+            signing: { pub: serverPub.signing },
+            exchange: { pub: serverPub.exchange },
+        },
+        encryption,
+    };
+    // Best-effort: drop our references to the in-memory private material. (JS
+    // strings can't be explicitly zeroed; the guarantee that matters — the private
+    // key is never written to drawlatch disk — is enforced above.)
+    callerSigningPriv = '';
+    callerExchangePriv = '';
+    log.info(`Issued caller "${alias}" (${connections.length} connection(s), fingerprint ${callerFp}` +
+        `${encryption ? ', passphrase-wrapped' : ''}${existing ? ', re-issue' : ''})`);
+    return bundle;
+}
+/**
+ * Issue a caller and write the UNPACKED key files straight into a co-located
+ * callboard's keys dir over the shared filesystem (same-host write is the trust
+ * proof). drawlatch keeps only the public key; callboard gets the private key on
+ * its own disk — bit-for-bit the steady state of the old pairing flow, with no
+ * token dance.
+ *
+ * Writes, under `<keysDir>`:
+ *   - callers/<alias>/{signing,exchange}.{key,pub}.pem  (0600 / 0644)
+ *   - server/{signing,exchange}.pub.pem                 (0644)
+ */
+export function issueLocalCaller(opts) {
+    const alias = opts.alias ?? 'callboard-local';
+    assertValidAlias(alias);
+    const config = loadRemoteConfig();
+    const existing = config.callers[alias];
+    const bundleKeys = generateKeyBundle();
+    const serialized = serializeKeyBundle(bundleKeys);
+    const publicKeys = serializePublicKeys(extractPublicKeys(bundleKeys));
+    const callerFp = fingerprint(extractPublicKeys(bundleKeys));
+    const connections = opts.connections ?? existing?.connections ?? defaultConnections(config);
+    const name = opts.name ?? existing?.name ?? alias;
+    config.callers[alias] = {
+        ...(existing ?? {}),
+        name,
+        connections,
+        source: 'local-auto',
+    };
+    saveRemoteConfig(config);
+    // drawlatch keeps only the public half.
+    saveCallerPublicKeys(alias, publicKeys);
+    // Write the unpacked key files into callboard's keys dir.
+    const callerKeysDir = path.join(opts.keysDir, 'callers', alias);
+    fs.mkdirSync(callerKeysDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(callerKeysDir, 'signing.pub.pem'), serialized.signing.publicKey, { mode: 0o644 });
+    fs.writeFileSync(path.join(callerKeysDir, 'exchange.pub.pem'), serialized.exchange.publicKey, { mode: 0o644 });
+    fs.writeFileSync(path.join(callerKeysDir, 'signing.key.pem'), serialized.signing.privateKey, { mode: 0o600 });
+    fs.writeFileSync(path.join(callerKeysDir, 'exchange.key.pem'), serialized.exchange.privateKey, { mode: 0o600 });
+    // And the server's public keys so callboard can pin the server identity.
+    const serverPub = exportServerPublicKeys();
+    const serverDir = path.join(opts.keysDir, 'server');
+    fs.mkdirSync(serverDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(serverDir, 'signing.pub.pem'), serverPub.signing, { mode: 0o644 });
+    fs.writeFileSync(path.join(serverDir, 'exchange.pub.pem'), serverPub.exchange, { mode: 0o644 });
+    log.info(`Auto-shared local caller "${alias}" to ${callerKeysDir} ` +
+        `(${connections.length} connection(s), fingerprint ${callerFp})`);
+    return { alias, fingerprint: callerFp, callerKeysDir, connections };
+}
+/**
+ * First-boot hook: when drawlatch is supervised by a co-located callboard (which
+ * sets DRAWLATCH_LOCAL_CALLER_KEYS_DIR to its own keys dir), auto-share a default
+ * caller into that dir — but only once (skipped if the caller already exists).
+ *
+ * Replaces the retired enroll-token / `/sync/auto-enroll` path.
+ */
+export function maybeIssueLocalCaller() {
+    const keysDir = process.env.DRAWLATCH_LOCAL_CALLER_KEYS_DIR;
+    if (!keysDir)
+        return null;
+    const alias = process.env.DRAWLATCH_LOCAL_CALLER_ALIAS ?? 'callboard-local';
+    const config = loadRemoteConfig();
+    if (alias in config.callers && callerKeyDirExists(alias)) {
+        // Already provisioned on a prior boot — nothing to do.
+        return null;
+    }
+    const connectionsEnv = process.env.DRAWLATCH_LOCAL_CALLER_CONNECTIONS;
+    const connections = connectionsEnv
+        ? connectionsEnv.split(',').map((c) => c.trim()).filter(Boolean)
+        : undefined;
+    try {
+        return issueLocalCaller({ alias, keysDir, ...(connections && { connections }) });
+    }
+    catch (err) {
+        log.error(`Could not auto-share local caller "${alias}":`, err);
+        return null;
+    }
+}
+// ── Delete ──────────────────────────────────────────────────────────────────
+/**
+ * Delete a caller: removes its config entry, prefixed env vars, and key dir.
+ * The `default` caller cannot be deleted.
+ */
+export function deleteCaller(alias) {
+    if (alias === 'default') {
+        throw new Error('Cannot delete the "default" caller');
+    }
+    const config = loadRemoteConfig();
+    if (!(alias in config.callers)) {
+        throw new Error(`Caller "${alias}" not found`);
+    }
+    // Clean up prefixed env vars referenced by this caller's env mapping.
+    const caller = config.callers[alias];
+    if (caller.env) {
+        const envUpdates = {};
+        for (const mapping of Object.values(caller.env)) {
+            const envMatch = /^\$\{(.+)\}$/.exec(mapping);
+            if (envMatch)
+                envUpdates[envMatch[1]] = ''; // empty string = delete
+        }
+        if (Object.keys(envUpdates).length > 0)
+            setEnvVars(envUpdates);
+    }
+    const { [alias]: _removed, ...remainingCallers } = config.callers;
+    config.callers = remainingCallers;
+    saveRemoteConfig(config);
+    // Remove the caller's key directory.
+    const keysDir = path.join(getCallerKeysDir(), alias);
+    if (fs.existsSync(keysDir)) {
+        fs.rmSync(keysDir, { recursive: true, force: true });
+    }
+    log.info(`Deleted caller "${alias}"`);
+}
+//# sourceMappingURL=caller-bootstrap.js.map

package/dist/remote/ingestors/base-ingestor.d.ts

@@ -27,6 +27,11 @@ export declare abstract class BaseIngestor extends EventEmitter {
     protected counter: number;
     protected lastEventAt: string | null;
     protected errorMessage?: string;
+    /** Caller alias that owns this ingestor. Set by IngestorManager after creation. */
+    callerAlias: string;
+    /** Per-instance epoch for event ID generation.
+     *  Each instance claims a unique epoch so IDs never collide across restarts. */
+    private readonly bootEpoch;
     /** Recently seen idempotency keys for deduplication. */
     private readonly seenKeys;
     constructor(

package/dist/remote/ingestors/base-ingestor.js

@@ -18,15 +18,19 @@ const log = createLogger('ingestor');
  *  When exceeded, the oldest half is pruned. */
 const MAX_SEEN_KEYS = 2000;
 /**
- * Epoch-based event IDs that are monotonically increasing across server reboots.
+ * Epoch-based event IDs that are monotonically increasing across restarts.
  * Format: `bootEpochSeconds * 1_000_000 + counter`.
  *
  * Uses seconds (not milliseconds) so the product stays within Number.MAX_SAFE_INTEGER.
  * This prevents clients with a stale `after_id` cursor from missing events
  * after a reboot — new IDs will always be higher than pre-reboot IDs
- * (assuming <1M events per boot and >1s between boots).
+ * (assuming <1M events per instance and >1s between restarts).
+ *
+ * Uses a monotonically increasing module-level epoch so that in-process restarts
+ * (e.g., LocalProxy.reinitialize()) also produce strictly increasing IDs.
+ * Each new BaseIngestor instance claims the next available epoch.
  */
-const BOOT_EPOCH = Math.floor(Date.now() / 1000);
+let nextEpoch = Math.floor(Date.now() / 1000);
 const ID_MULTIPLIER = 1_000_000;
 export class BaseIngestor extends EventEmitter {
     connectionAlias;
@@ -38,6 +42,11 @@ export class BaseIngestor extends EventEmitter {
     counter = 0;
     lastEventAt = null;
     errorMessage;
+    /** Caller alias that owns this ingestor. Set by IngestorManager after creation. */
+    callerAlias = 'unknown';
+    /** Per-instance epoch for event ID generation.
+     *  Each instance claims a unique epoch so IDs never collide across restarts. */
+    bootEpoch;
     /** Recently seen idempotency keys for deduplication. */
     seenKeys = new Set();
     constructor(
@@ -59,6 +68,9 @@ export class BaseIngestor extends EventEmitter {
         this.secrets = secrets;
         this.instanceId = instanceId;
         this.buffer = new RingBuffer(bufferSize);
+        // Claim a unique epoch for this instance — ensures event IDs are strictly
+        // increasing even when ingestors are restarted in-process.
+        this.bootEpoch = nextEpoch++;
     }
     /**
      * Push a new event into the ring buffer.
@@ -77,13 +89,14 @@ export class BaseIngestor extends EventEmitter {
             return;
         }
         const now = new Date();
-        const id = BOOT_EPOCH * ID_MULTIPLIER + this.counter++;
+        const id = this.bootEpoch * ID_MULTIPLIER + this.counter++;
         const key = idempotencyKey ?? `${this.connectionAlias}:${crypto.randomUUID()}`;
         const event = {
             id,
             idempotencyKey: key,
             receivedAt: now.toISOString(),
             receivedAtMs: now.getTime(),
+            callerAlias: this.callerAlias,
             source: this.connectionAlias,
             ...(this.instanceId !== undefined && { instanceId: this.instanceId }),
             eventType,

package/dist/remote/ingestors/discord/discord-gateway.js

@@ -60,8 +60,31 @@ export class DiscordGatewayIngestor extends BaseIngestor {
         this.state = 'stopped';
         this.clearAllTimers();
         if (this.ws) {
-            this.ws.close(1000, 'Shutting down');
+            const ws = this.ws;
             this.ws = null;
+            // Wait for the WebSocket to fully close before resolving.
+            // This prevents a race where the old connection is still alive when a new
+            // ingestor starts. For Discord, this avoids the old gateway session
+            // lingering while a new IDENTIFY is sent (which Discord may reject
+            // if it sees two sessions for the same bot token).
+            return new Promise((resolve) => {
+                const onClose = () => {
+                    ws.removeEventListener('close', onClose);
+                    resolve();
+                };
+                if (ws.readyState === WebSocket.CLOSED) {
+                    resolve();
+                }
+                else {
+                    ws.addEventListener('close', onClose);
+                    ws.close(1000, 'Shutting down');
+                    // Safety timeout — don't block forever if close event never fires
+                    setTimeout(() => {
+                        ws.removeEventListener('close', onClose);
+                        resolve();
+                    }, 5000);
+                }
+            });
         }
         return Promise.resolve();
     }

package/dist/remote/ingestors/e2e/setup.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared E2E test setup for connection ingestor tests.
+ *
+ * Provides helpers to:
+ *   - Load .env.e2e environment variables
+ *   - Build a RemoteServerConfig with in-memory keys and requested connections
+ *   - Boot an Express server on a random port
+ *   - Generate valid webhook signatures (GitHub, Trello)
+ *   - Wait for ingestor state transitions and event arrival
+ */
+import type { Server } from 'node:http';
+import { IngestorManager } from '../manager.js';
+import type { RemoteServerConfig } from '../../../shared/config.js';
+import type { IngestedEvent, IngestorState } from '../types.js';
+export declare function loadE2EEnv(): void;
+/**
+ * Check that all required env vars are set.
+ * Returns the missing var names (empty array = all present).
+ */
+export declare function checkEnvVars(vars: string[]): string[];
+/**
+ * Build a RemoteServerConfig for E2E tests.
+ *
+ * Creates a single caller ("e2e-client") with the requested connections.
+ * Env vars are injected into caller.env so secret resolution works against
+ * process.env (already loaded by loadE2EEnv).
+ */
+export declare function buildE2EConfig(connections: string[], opts?: {
+    env?: Record<string, string>;
+    ingestorOverrides?: Record<string, Record<string, unknown>>;
+}): RemoteServerConfig;
+export interface E2EServer {
+    server: Server;
+    baseUrl: string;
+    ingestorManager: IngestorManager;
+    /** Gracefully shut down server and stop all ingestors. */
+    teardown: () => Promise<void>;
+}
+/**
+ * Boot an Express server with the given config on a random port.
+ * Starts all ingestors and returns handles for testing.
+ */
+export declare function bootServer(config: RemoteServerConfig): Promise<E2EServer>;
+/** Generate a valid GitHub HMAC-SHA256 signature for a raw body. */
+export declare function signGitHubPayload(rawBody: string | Buffer, secret: string): string;
+/** Generate a valid Trello HMAC-SHA1 base64 signature for body + callbackUrl. */
+export declare function signTrelloPayload(rawBody: string | Buffer, callbackUrl: string, secret: string): string;
+/**
+ * Wait for an ingestor to reach a specific state.
+ * Polls every 250ms until the timeout is reached.
+ */
+export declare function waitForIngestorState(manager: IngestorManager, callerAlias: string, connection: string, targetState: IngestorState, timeoutMs?: number): Promise<void>;
+/**
+ * Poll until at least one event appears for a connection.
+ * Returns the events array once non-empty.
+ */
+export declare function pollUntilEvent(manager: IngestorManager, callerAlias: string, connection: string, timeoutMs?: number): Promise<IngestedEvent[]>;
+/** Common shape every IngestedEvent must satisfy (for use with toMatchObject). */
+export declare const INGESTED_EVENT_SHAPE: {
+    id: any;
+    idempotencyKey: any;
+    receivedAt: any;
+    receivedAtMs: any;
+    callerAlias: string;
+    source: any;
+    eventType: any;
+    data: any;
+};
+//# sourceMappingURL=setup.d.ts.map

package/dist/remote/ingestors/e2e/setup.js

@@ -0,0 +1,147 @@
+/**
+ * Shared E2E test setup for connection ingestor tests.
+ *
+ * Provides helpers to:
+ *   - Load .env.e2e environment variables
+ *   - Build a RemoteServerConfig with in-memory keys and requested connections
+ *   - Boot an Express server on a random port
+ *   - Generate valid webhook signatures (GitHub, Trello)
+ *   - Wait for ingestor state transitions and event arrival
+ */
+import crypto from 'node:crypto';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { expect } from 'vitest';
+import { createApp } from '../../server.js';
+import { generateKeyBundle, extractPublicKeys } from '../../../shared/crypto/index.js';
+import { IngestorManager } from '../manager.js';
+// ── Env loading ─────────────────────────────────────────────────────────
+/** Load .env.e2e from the project root (idempotent). */
+let envLoaded = false;
+export function loadE2EEnv() {
+    if (envLoaded)
+        return;
+    dotenv.config({ path: path.resolve(import.meta.dirname, '../../../../.env.e2e') });
+    envLoaded = true;
+}
+/**
+ * Check that all required env vars are set.
+ * Returns the missing var names (empty array = all present).
+ */
+export function checkEnvVars(vars) {
+    loadE2EEnv();
+    return vars.filter((v) => !process.env[v]);
+}
+// ── Config builder ──────────────────────────────────────────────────────
+/**
+ * Build a RemoteServerConfig for E2E tests.
+ *
+ * Creates a single caller ("e2e-client") with the requested connections.
+ * Env vars are injected into caller.env so secret resolution works against
+ * process.env (already loaded by loadE2EEnv).
+ */
+export function buildE2EConfig(connections, opts) {
+    return {
+        host: '127.0.0.1',
+        port: 0,
+        callers: {
+            'e2e-client': {
+                connections,
+                env: opts?.env,
+                ingestorOverrides: opts?.ingestorOverrides,
+            },
+        },
+        rateLimitPerMinute: 600,
+    };
+}
+/**
+ * Boot an Express server with the given config on a random port.
+ * Starts all ingestors and returns handles for testing.
+ */
+export async function bootServer(config) {
+    const serverKeys = generateKeyBundle();
+    const clientKeys = generateKeyBundle();
+    const clientPub = extractPublicKeys(clientKeys);
+    const ingestorManager = new IngestorManager(config);
+    const app = createApp({
+        config,
+        ownKeys: serverKeys,
+        authorizedPeers: [{ alias: 'e2e-client', keys: clientPub }],
+        ingestorManager,
+        disableRateLimiting: true,
+    });
+    // Start ingestors
+    await ingestorManager.startAll();
+    // Listen on random port
+    const server = await new Promise((resolve) => {
+        const s = app.listen(0, '127.0.0.1', () => resolve(s));
+    });
+    const addr = server.address();
+    const baseUrl = `http://127.0.0.1:${addr.port}`;
+    return {
+        server,
+        baseUrl,
+        ingestorManager,
+        teardown: async () => {
+            await ingestorManager.stopAll();
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+// ── Signature helpers ───────────────────────────────────────────────────
+/** Generate a valid GitHub HMAC-SHA256 signature for a raw body. */
+export function signGitHubPayload(rawBody, secret) {
+    const buf = typeof rawBody === 'string' ? Buffer.from(rawBody) : rawBody;
+    const sig = crypto.createHmac('sha256', secret).update(buf).digest('hex');
+    return `sha256=${sig}`;
+}
+/** Generate a valid Trello HMAC-SHA1 base64 signature for body + callbackUrl. */
+export function signTrelloPayload(rawBody, callbackUrl, secret) {
+    const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf-8');
+    return crypto.createHmac('sha1', secret).update(bodyStr + callbackUrl).digest('base64');
+}
+// ── Polling helpers ─────────────────────────────────────────────────────
+/**
+ * Wait for an ingestor to reach a specific state.
+ * Polls every 250ms until the timeout is reached.
+ */
+export async function waitForIngestorState(manager, callerAlias, connection, targetState, timeoutMs = 15_000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const statuses = manager.getStatuses(callerAlias);
+        const status = statuses.find((s) => s.connection === connection);
+        if (status?.state === targetState)
+            return;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`Timed out waiting for ${connection} to reach state "${targetState}" (${timeoutMs}ms)`);
+}
+/**
+ * Poll until at least one event appears for a connection.
+ * Returns the events array once non-empty.
+ */
+export async function pollUntilEvent(manager, callerAlias, connection, timeoutMs = 10_000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const events = manager.getEvents(callerAlias, connection);
+        if (events.length > 0)
+            return events;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`Timed out waiting for events from ${connection} (${timeoutMs}ms)`);
+}
+// ── Shared assertions ───────────────────────────────────────────────────
+/** Common shape every IngestedEvent must satisfy (for use with toMatchObject). */
+export const INGESTED_EVENT_SHAPE = {
+    id: expect.any(Number),
+    idempotencyKey: expect.any(String),
+    receivedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+    receivedAtMs: expect.any(Number),
+    callerAlias: 'e2e-client',
+    source: expect.any(String),
+    eventType: expect.any(String),
+    data: expect.anything(),
+};
+//# sourceMappingURL=setup.js.map

package/dist/remote/ingestors/manager.d.ts

@@ -43,7 +43,18 @@ export declare class IngestorManager {
     private readonly config;
     /** Active ingestor instances, keyed by `callerAlias:connectionAlias:instanceId`. */
     private ingestors;
-    constructor(config: RemoteServerConfig);
+    /** Trigger rule engines per caller. Created during startAll() for callers with triggerRules. */
+    private triggerEngines;
+    /** Global event listeners (e.g. SSE streams). Called for every event from every ingestor. */
+    private eventListeners;
+    /**
+     * Optional config loader for hot-reload support. When provided, `startOne()`
+     * uses it to get fresh config from disk instead of the constructor snapshot.
+     */
+    private configLoader;
+    constructor(config: RemoteServerConfig, configLoader?: () => RemoteServerConfig);
+    /** Return fresh config if a loader is available, otherwise the constructor snapshot. */
+    private getConfig;
     /**
      * Start ingestors for all callers whose connections have an `ingestor` config.
      * Called once when the remote server starts listening.
@@ -56,6 +67,12 @@ export declare class IngestorManager {
      * Internal: create, register, and start a single ingestor instance.
      */
     private startIngestor;
+    /**
+     * Initialize trigger rule engines for callers with triggerRules config.
+     * Subscribes to 'event' emissions from matching ingestors and dispatches
+     * to Claude Code remote triggers.
+     */
+    private initTriggerEngines;
     /**
      * Stop all running ingestors. Called during graceful shutdown.
      */
@@ -75,6 +92,23 @@ export declare class IngestorManager {
      * Get status of all ingestors for a caller.
      */
     getStatuses(callerAlias: string): IngestorStatus[];
+    /**
+     * Get status of every ingestor across all callers, augmented with the
+     * owning caller alias. Used by the read-only /admin API to render a global
+     * dashboard view without iterating per-caller.
+     */
+    getAllStatuses(): (IngestorStatus & {
+        callerAlias: string;
+    })[];
+    /**
+     * Subscribe to all events from all ingestors (current and future).
+     * Used by the SSE /events/stream endpoint to fan out events to CLI watchers.
+     */
+    onEvent(listener: (event: IngestedEvent) => void): void;
+    /** Unsubscribe a global event listener. */
+    offEvent(listener: (event: IngestedEvent) => void): void;
+    /** Forward an ingestor event to all global listeners. */
+    private notifyEventListeners;
     /**
      * Find all webhook ingestor instances that match a given webhook path.
      * Returns all matching instances across all callers (for fan-out dispatch).