@wolpertingerlabs/drawlatch 1.0.0-alpha.3 → 1.0.0-alpha.35

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

@@ -18,11 +18,20 @@ export declare abstract class BaseIngestor extends EventEmitter {
     protected readonly ingestorType: 'websocket' | 'webhook' | 'poll';
     /** Resolved secrets for the parent connection. */
     protected readonly secrets: Record<string, string>;
+    /** Optional instance identifier for multi-instance support.
+     *  When set, this ingestor is one of N instances for the same connection
+     *  (e.g., watching different Trello boards or Reddit subreddits). */
+    protected readonly instanceId?: string | undefined;
     protected state: IngestorState;
     protected buffer: RingBuffer<IngestedEvent>;
     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(
@@ -33,11 +42,18 @@ export declare abstract class BaseIngestor extends EventEmitter {
     /** Resolved secrets for the parent connection. */
     secrets: Record<string, string>, 
     /** Buffer capacity (defaults to DEFAULT_BUFFER_SIZE). */
-    bufferSize?: number);
+    bufferSize?: number, 
+    /** Optional instance identifier for multi-instance support.
+     *  When set, this ingestor is one of N instances for the same connection
+     *  (e.g., watching different Trello boards or Reddit subreddits). */
+    instanceId?: string | undefined);
     /** Start the ingestor (connect WebSocket, begin polling, etc.). */
     abstract start(): Promise<void>;
-    /** Stop the ingestor cleanly (close connections, clear timers). */
-    abstract stop(): Promise<void>;
+    /** Stop the ingestor cleanly (close connections, clear timers).
+     *  @param permanent  When true, indicates a permanent shutdown (server exit
+     *                    or instance deletion). Webhook ingestors use this to
+     *                    unregister webhooks from the external service. */
+    abstract stop(permanent?: boolean): Promise<void>;
     /**
      * Push a new event into the ring buffer.
      * Called by subclasses when they receive data from an external service.

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

@@ -18,25 +18,35 @@ 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;
     ingestorType;
     secrets;
+    instanceId;
     state = 'stopped';
     buffer;
     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(
@@ -47,12 +57,20 @@ export class BaseIngestor extends EventEmitter {
     /** Resolved secrets for the parent connection. */
     secrets, 
     /** Buffer capacity (defaults to DEFAULT_BUFFER_SIZE). */
-    bufferSize = DEFAULT_BUFFER_SIZE) {
+    bufferSize = DEFAULT_BUFFER_SIZE, 
+    /** Optional instance identifier for multi-instance support.
+     *  When set, this ingestor is one of N instances for the same connection
+     *  (e.g., watching different Trello boards or Reddit subreddits). */
+    instanceId) {
         super();
         this.connectionAlias = connectionAlias;
         this.ingestorType = ingestorType;
         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.
@@ -71,14 +89,16 @@ 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,
             data,
         };
@@ -90,7 +110,7 @@ export class BaseIngestor extends EventEmitter {
             this.pruneSeenKeys();
         }
         log.info(`${this.connectionAlias} event #${event.id}: ${eventType}`);
-        log.debug(`${this.connectionAlias} event #${event.id} payload:`, JSON.stringify(data, null, 2));
+        log.debug(`${this.connectionAlias} event #${event.id} payload size:`, JSON.stringify(data).length);
         this.emit('event', event);
     }
     /**
@@ -120,6 +140,7 @@ export class BaseIngestor extends EventEmitter {
     getStatus() {
         return {
             connection: this.connectionAlias,
+            ...(this.instanceId !== undefined && { instanceId: this.instanceId }),
             type: this.ingestorType,
             state: this.state,
             bufferedEvents: this.buffer.size,

package/dist/remote/ingestors/discord/discord-gateway.d.ts

@@ -37,9 +37,9 @@ export declare class DiscordGatewayIngestor extends BaseIngestor {
     private readonly guildIds;
     private readonly channelIds;
     private readonly userIds;
-    constructor(connectionAlias: string, secrets: Record<string, string>, wsConfig: WebSocketIngestorConfig, bufferSize?: number);
+    constructor(connectionAlias: string, secrets: Record<string, string>, wsConfig: WebSocketIngestorConfig, bufferSize?: number, instanceId?: string);
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(_permanent?: boolean): Promise<void>;
     private connect;
     private handlePayload;
     private handleHello;

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

@@ -41,8 +41,8 @@ export class DiscordGatewayIngestor extends BaseIngestor {
     guildIds;
     channelIds;
     userIds;
-    constructor(connectionAlias, secrets, wsConfig, bufferSize) {
-        super(connectionAlias, 'websocket', secrets, bufferSize);
+    constructor(connectionAlias, secrets, wsConfig, bufferSize, instanceId) {
+        super(connectionAlias, 'websocket', secrets, bufferSize, instanceId);
         this.wsConfig = wsConfig;
         this.gatewayUrl = wsConfig.gatewayUrl;
         this.intents = wsConfig.intents ?? DEFAULT_INTENTS;
@@ -56,12 +56,35 @@ export class DiscordGatewayIngestor extends BaseIngestor {
         this.connect(this.gatewayUrl);
         return Promise.resolve();
     }
-    stop() {
+    stop(_permanent) {
         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();
     }
@@ -331,11 +354,11 @@ export class DiscordGatewayIngestor extends BaseIngestor {
     }
 }
 // ── Self-registration ────────────────────────────────────────────────────
-registerIngestorFactory('websocket:discord', (connectionAlias, config, secrets, bufferSize) => {
+registerIngestorFactory('websocket:discord', (connectionAlias, config, secrets, bufferSize, instanceId) => {
     if (!config.websocket) {
         log.error(`Missing websocket config for ${connectionAlias}`);
         return null;
     }
-    return new DiscordGatewayIngestor(connectionAlias, secrets, config.websocket, bufferSize);
+    return new DiscordGatewayIngestor(connectionAlias, secrets, config.websocket, bufferSize, instanceId);
 });
 //# sourceMappingURL=discord-gateway.js.map

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