@wolpertingerlabs/drawlatch 1.0.0-alpha.2 → 1.0.0-alpha.29

package/dist/remote/admin.js

@@ -0,0 +1,316 @@
+/**
+ * Read-only admin HTTP API for the merged dashboard, served at `/api/admin/*`.
+ *
+ * Trust boundary: the scrypt password gate (the admin router is mounted behind
+ * `requireAuth` in server.ts, wired in Step 2). This replaces the old
+ * loopback-only posture, so the dashboard can be exposed on a host bind
+ * (DRAWLATCH_HOST=0.0.0.0) while still being password-protected.
+ *
+ * This file is the type authority for the admin DTOs — see `admin-types.ts`.
+ *
+ * SECURITY non-negotiables (mirrored in /admin.test.ts):
+ *   - Never serializes Session.channel (AES keys) or ResolvedRoute.secrets.
+ *   - Never returns process.env values; only key names. Secret presence is
+ *     reported via `isSecretSetForCaller()` (booleans only).
+ *   - Caller `env` mappings (e.g. "GITHUB_TOKEN": "${ACME_GITHUB_TOKEN}") are
+ *     reduced to key-name lists — the value strings are NOT returned.
+ *   - No mutations: every endpoint is GET.
+ *   - No CORS.
+ */
+import express from 'express';
+import fs from 'node:fs';
+import { getCallerKeysDir, getServerKeysDir, getEnvFilePath, getRemoteConfigPath, } from '../shared/config.js';
+import { listConnectionTemplates, loadConnection } from '../shared/connections.js';
+import { isSecretSetForCaller } from '../shared/env-utils.js';
+import { callerFingerprint } from '../shared/crypto/key-manager.js';
+import { getTunnelUrl } from './tunnel-state.js';
+import { mountAdminMutations } from './admin-mutations.js';
+import path from 'node:path';
+export function createAdminRouter(deps) {
+    const router = express.Router();
+    // ── /admin/meta ────────────────────────────────────────────────────────
+    router.get('/meta', (_req, res) => {
+        const body = {
+            version: deps.version,
+            port: deps.port,
+            pid: process.pid,
+            startedAt: deps.startedAt,
+            uptimeSec: Math.floor((Date.now() - deps.startedAt) / 1000),
+            configPath: getRemoteConfigPath(),
+            callerKeysDir: getCallerKeysDir(),
+            serverKeysDir: getServerKeysDir(),
+            envFilePath: getEnvFilePath(),
+            tunnelUrl: getTunnelUrl(),
+            tunnelEnabled: deps.loadConfig().tunnel === true,
+        };
+        res.json(body);
+    });
+    // ── /admin/health ──────────────────────────────────────────────────────
+    router.get('/health', (_req, res) => {
+        const statuses = deps.ingestorManager().getAllStatuses();
+        const counts = { connected: 0, error: 0, starting: 0, stopped: 0 };
+        for (const s of statuses) {
+            if (s.state === 'connected')
+                counts.connected++;
+            else if (s.state === 'error')
+                counts.error++;
+            else if (s.state === 'starting' || s.state === 'reconnecting')
+                counts.starting++;
+            else
+                counts.stopped++;
+        }
+        const body = {
+            status: 'ok',
+            activeSessions: deps.getSessionsSnapshot().length,
+            ingestorCounts: counts,
+            uptimeSec: Math.floor((Date.now() - deps.startedAt) / 1000),
+        };
+        res.json(body);
+    });
+    // ── /admin/callers ─────────────────────────────────────────────────────
+    // Returns caller config metadata only — env values are reduced to key names.
+    router.get('/callers', (_req, res) => {
+        const config = deps.loadConfig();
+        const callersKeysDir = getCallerKeysDir();
+        const out = Object.entries(config.callers).map(([alias, caller]) => {
+            const keysDirExists = fs.existsSync(path.join(callersKeysDir, alias));
+            let fingerprint = null;
+            try {
+                fingerprint = keysDirExists ? callerFingerprint(alias) : null;
+            }
+            catch {
+                fingerprint = null;
+            }
+            return {
+                alias,
+                name: caller.name ?? null,
+                connections: caller.connections,
+                // Key names ONLY — never the mapping value strings.
+                envKeys: Object.keys(caller.env ?? {}),
+                fingerprint,
+                keysDirExists,
+            };
+        });
+        res.json(out);
+    });
+    // ── /admin/connections ─────────────────────────────────────────────────
+    // listConnectionTemplates already returns names-only — safe as-is.
+    router.get('/connections', (_req, res) => {
+        const out = listConnectionTemplates();
+        res.json(out);
+    });
+    // ── /admin/callers/:alias/connection-status ─────────────────────────────
+    // Every connection template + this caller's enabled flag + secret presence
+    // (booleans only). The Connections page renders from this single payload.
+    router.get('/callers/:alias/connection-status', (req, res) => {
+        const config = deps.loadConfig();
+        if (!(req.params.alias in config.callers)) {
+            res.status(404).json({ error: `Unknown caller: ${req.params.alias}` });
+            return;
+        }
+        const caller = config.callers[req.params.alias];
+        const enabled = new Set(caller.connections);
+        const out = listConnectionTemplates().map((t) => {
+            const requiredSecretsSet = {};
+            for (const s of t.requiredSecrets) {
+                requiredSecretsSet[s] = isSecretSetForCaller(s, req.params.alias, caller.env);
+            }
+            const optionalSecretsSet = {};
+            for (const s of t.optionalSecrets) {
+                optionalSecretsSet[s] = isSecretSetForCaller(s, req.params.alias, caller.env);
+            }
+            return {
+                ...t,
+                enabled: enabled.has(t.alias),
+                requiredSecretsSet,
+                optionalSecretsSet,
+            };
+        });
+        res.json(out);
+    });
+    // ── /admin/callers/:alias/connections ──────────────────────────────────
+    router.get('/callers/:alias/connections', (req, res) => {
+        const config = deps.loadConfig();
+        if (!(req.params.alias in config.callers)) {
+            res.status(404).json({ error: `Unknown caller: ${req.params.alias}` });
+            return;
+        }
+        const caller = config.callers[req.params.alias];
+        const templates = listConnectionTemplates();
+        const tplMap = new Map(templates.map((t) => [t.alias, t]));
+        const customMap = new Map((config.connectors ?? []).map((c) => [c.alias, c]));
+        const out = caller.connections.map((connectionAlias) => {
+            const tpl = tplMap.get(connectionAlias);
+            const customRoute = customMap.get(connectionAlias);
+            const isCustom = !tpl;
+            const requiredNames = tpl?.requiredSecrets ?? [];
+            const optionalNames = tpl?.optionalSecrets ?? [];
+            const requiredSecrets = requiredNames.map((name) => ({
+                name,
+                present: isSecretSetForCaller(name, req.params.alias, caller.env),
+            }));
+            const optionalSecrets = optionalNames.map((name) => ({
+                name,
+                present: isSecretSetForCaller(name, req.params.alias, caller.env),
+            }));
+            // Resolve listenerConfig so we can identify ListenerConfigField.type === 'secret'
+            // fields and strip them from the params projection. Without this, a future
+            // template that declares a 'secret' field would silently leak the value via
+            // the ...ov.params spread below.
+            let listenerConfig;
+            if (customRoute) {
+                listenerConfig = customRoute.listenerConfig;
+            }
+            else if (tpl) {
+                try {
+                    listenerConfig = loadConnection(connectionAlias).listenerConfig;
+                }
+                catch {
+                    listenerConfig = undefined;
+                }
+            }
+            const secretFieldKeys = new Set((listenerConfig?.fields ?? []).filter((f) => f.type === 'secret').map((f) => f.key));
+            // Multi-instance projection — drop anything that could carry secrets.
+            const instancesMap = caller.listenerInstances?.[connectionAlias] ?? {};
+            const instances = Object.entries(instancesMap).map(([instanceId, ov]) => {
+                const safeParams = ov.params !== undefined
+                    ? Object.fromEntries(Object.entries(ov.params).filter(([k]) => !secretFieldKeys.has(k)))
+                    : undefined;
+                return {
+                    instanceId,
+                    enabled: ov.disabled !== true,
+                    params: {
+                        ...(ov.intents !== undefined && { intents: ov.intents }),
+                        ...(ov.eventFilter !== undefined && { eventFilter: ov.eventFilter }),
+                        ...(ov.guildIds !== undefined && { guildIds: ov.guildIds }),
+                        ...(ov.channelIds !== undefined && { channelIds: ov.channelIds }),
+                        ...(ov.userIds !== undefined && { userIds: ov.userIds }),
+                        ...(ov.bufferSize !== undefined && { bufferSize: ov.bufferSize }),
+                        ...(ov.intervalMs !== undefined && { intervalMs: ov.intervalMs }),
+                        ...(ov.disabled !== undefined && { disabled: ov.disabled }),
+                        // Listener params (board IDs, subreddit names, etc.) are user-set
+                        // configuration, not secrets. Pass through verbatim — except for any
+                        // field whose schema marks it as type: 'secret', which is filtered above.
+                        ...(safeParams !== undefined && safeParams),
+                    },
+                };
+            });
+            // `enabled`: a connection is enabled by default; explicit disabled
+            // override (single-instance) toggles it off.
+            const overrideDisabled = caller.ingestorOverrides?.[connectionAlias]?.disabled === true;
+            return {
+                connectionAlias,
+                enabled: !overrideDisabled,
+                isCustom,
+                requiredSecrets,
+                optionalSecrets,
+                hasIngestor: tpl?.hasIngestor ?? customMap.get(connectionAlias)?.ingestor !== undefined,
+                instances,
+            };
+        });
+        res.json(out);
+    });
+    // ── /admin/ingestors ───────────────────────────────────────────────────
+    router.get('/ingestors', (_req, res) => {
+        const statuses = deps.ingestorManager().getAllStatuses();
+        // getAllStatuses already augments with callerAlias; connection and
+        // instanceId come from base IngestorStatus.
+        const out = statuses.map((s) => ({
+            callerAlias: s.callerAlias,
+            connection: s.connection,
+            ...(s.instanceId !== undefined && { instanceId: s.instanceId }),
+            type: s.type,
+            state: s.state,
+            bufferedEvents: s.bufferedEvents,
+            totalEventsReceived: s.totalEventsReceived,
+            lastEventAt: s.lastEventAt,
+            ...(s.error !== undefined && { error: s.error }),
+            ...(s.webhookRegistration !== undefined && {
+                webhookRegistration: s.webhookRegistration,
+            }),
+        }));
+        res.json(out);
+    });
+    // ── /admin/callers/:alias/ingestors ──────────────────────────────────────
+    // Per-caller ingestor statuses (the Logs viewer's status cards).
+    router.get('/callers/:alias/ingestors', (req, res) => {
+        if (!(req.params.alias in deps.loadConfig().callers)) {
+            res.status(404).json({ error: `Unknown caller: ${req.params.alias}` });
+            return;
+        }
+        const statuses = deps.ingestorManager().getStatuses(req.params.alias);
+        const out = statuses.map((s) => ({
+            callerAlias: req.params.alias,
+            connection: s.connection,
+            ...(s.instanceId !== undefined && { instanceId: s.instanceId }),
+            type: s.type,
+            state: s.state,
+            bufferedEvents: s.bufferedEvents,
+            totalEventsReceived: s.totalEventsReceived,
+            lastEventAt: s.lastEventAt,
+            ...(s.error !== undefined && { error: s.error }),
+            ...(s.webhookRegistration !== undefined && { webhookRegistration: s.webhookRegistration }),
+        }));
+        res.json(out);
+    });
+    // ── /admin/callers/:alias/events ──────────────────────────────────────────
+    // Buffered ingestor events for the Logs viewer. These are external-service
+    // payloads (Discord messages, webhooks, …), never drawlatch secrets.
+    router.get('/callers/:alias/events', (req, res) => {
+        if (!(req.params.alias in deps.loadConfig().callers)) {
+            res.status(404).json({ error: `Unknown caller: ${req.params.alias}` });
+            return;
+        }
+        const afterRaw = req.query.after_id;
+        const afterId = typeof afterRaw === 'string' ? parseInt(afterRaw, 10) : -1;
+        const events = deps
+            .ingestorManager()
+            .getAllEvents(req.params.alias, Number.isNaN(afterId) ? -1 : afterId);
+        res.json(events);
+    });
+    // ── /admin/sessions ────────────────────────────────────────────────────
+    // SessionSnapshot already strips channel + resolvedRoutes — pass it through.
+    router.get('/sessions', (_req, res) => {
+        res.json(deps.getSessionsSnapshot());
+    });
+    // ── /admin/secrets ─────────────────────────────────────────────────────
+    // Flat join of (caller × connection × secret), with `present` computed via
+    // isSecretSetForCaller() — never the actual env value.
+    router.get('/secrets', (_req, res) => {
+        const config = deps.loadConfig();
+        const tplMap = new Map(listConnectionTemplates().map((t) => [t.alias, t]));
+        const out = [];
+        for (const [callerAlias, caller] of Object.entries(config.callers)) {
+            for (const connectionAlias of caller.connections) {
+                const tpl = tplMap.get(connectionAlias);
+                if (!tpl)
+                    continue; // custom connector — no template-defined secrets to enumerate
+                for (const name of tpl.requiredSecrets) {
+                    out.push({
+                        callerAlias,
+                        connection: connectionAlias,
+                        name,
+                        required: true,
+                        present: isSecretSetForCaller(name, callerAlias, caller.env),
+                    });
+                }
+                for (const name of tpl.optionalSecrets) {
+                    out.push({
+                        callerAlias,
+                        connection: connectionAlias,
+                        name,
+                        required: false,
+                        present: isSecretSetForCaller(name, callerAlias, caller.env),
+                    });
+                }
+            }
+        }
+        res.json(out);
+    });
+    // ── Mutating endpoints (item A) ──────────────────────────────────────────
+    // Connections enable/secrets/test, caller create/delete, and listener/ingestor
+    // control. Mounted on the same router (already behind requireAuth in server.ts).
+    mountAdminMutations(router, deps);
+    return router;
+}
+//# sourceMappingURL=admin.js.map

package/dist/remote/caller-bootstrap.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Programmatic / non-interactive caller bootstrap (item E).
+ *
+ * The interactive `drawlatch sync` handshake stays the path for *remote*
+ * enrollment (a caller on another machine proving identity over the network).
+ * This module is for the zero-friction local case: a co-located client that
+ * shares drawlatch's filesystem can provision a caller — complete with a fresh
+ * keypair — without any invite-code dance.
+ *
+ * Two entry points:
+ *   - `createCallerWithKeys()` — library function (also exposed as the
+ *     password-gated `POST /api/admin/callers` admin endpoint).
+ *   - `autoEnroll()` — loopback / shared-fs path: a client proves filesystem
+ *     access by presenting the one-time token drawlatch writes into the config
+ *     dir at startup, and gets a caller provisioned with zero interaction.
+ */
+import { type RemoteServerConfig } from '../shared/config.js';
+import type { SerializedPublicKeys } from '../shared/crypto/keys.js';
+/** Valid caller alias: starts with a letter/number, then letters/numbers/-/_. */
+export declare const CALLER_ALIAS_REGEX: RegExp;
+export interface CreateCallerOptions {
+    /** Human-readable display name (defaults to the alias). */
+    name?: string;
+    /** Connection aliases to grant. When omitted, clones the `default` caller's
+     *  connections so a new caller starts with the same access (common expectation). */
+    connections?: string[];
+}
+export interface CreateCallerResult {
+    alias: string;
+    name: string;
+    fingerprint: string;
+    /** The caller's freshly-generated public keys (private keys stay on disk). */
+    publicKeys: SerializedPublicKeys;
+    /** Directory holding the caller's keypair (keys/callers/<alias>/). */
+    keysDir: string;
+    connections: string[];
+}
+/**
+ * Create a caller WITH a fresh keypair, registered in remote.config.json,
+ * without the interactive sync handshake.
+ *
+ * Throws on invalid alias, or if the caller (config entry or key dir) exists.
+ */
+export declare function createCallerWithKeys(alias: string, opts?: CreateCallerOptions): CreateCallerResult;
+/**
+ * Delete a caller: removes its config entry, prefixed env vars, and key dir.
+ * The `default` caller cannot be deleted.
+ */
+export declare function deleteCaller(alias: string): void;
+/** Path of the one-time enroll token file inside the config dir. */
+export declare function getEnrollTokenPath(): string;
+/**
+ * Write a fresh one-time enroll token into the config dir (mode 0600).
+ *
+ * Only a process with filesystem access to drawlatch's config dir can read it,
+ * which is exactly the proof-of-co-location we want for `autoEnroll()`.
+ * Called once at daemon startup; overwrites any stale token.
+ */
+export declare function writeEnrollToken(): string;
+/**
+ * Auto-enroll a co-located caller by presenting the one-time enroll token.
+ *
+ * Verifies the token proves filesystem access to the config dir, then either
+ * creates a new caller with keys (if the alias is new) or returns the existing
+ * one's metadata (idempotent). The token is single-use: it is rotated on every
+ * successful enroll so a leaked token cannot be replayed.
+ */
+export declare function autoEnroll(token: string, alias: string, opts?: CreateCallerOptions): CreateCallerResult;
+/** Re-exported for callers that want to introspect config without re-importing. */
+export type { RemoteServerConfig };
+//# sourceMappingURL=caller-bootstrap.d.ts.map

package/dist/remote/caller-bootstrap.js

@@ -0,0 +1,141 @@
+/**
+ * Programmatic / non-interactive caller bootstrap (item E).
+ *
+ * The interactive `drawlatch sync` handshake stays the path for *remote*
+ * enrollment (a caller on another machine proving identity over the network).
+ * This module is for the zero-friction local case: a co-located client that
+ * shares drawlatch's filesystem can provision a caller — complete with a fresh
+ * keypair — without any invite-code dance.
+ *
+ * Two entry points:
+ *   - `createCallerWithKeys()` — library function (also exposed as the
+ *     password-gated `POST /api/admin/callers` admin endpoint).
+ *   - `autoEnroll()` — loopback / shared-fs path: a client proves filesystem
+ *     access by presenting the one-time token drawlatch writes into the config
+ *     dir at startup, and gets a caller provisioned with zero interaction.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { loadRemoteConfig, saveRemoteConfig, getConfigDir, getCallerKeysDir, } from '../shared/config.js';
+import { createCaller, callerExists } from '../shared/crypto/key-manager.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_-]*$/;
+/**
+ * Create a caller WITH a fresh keypair, registered in remote.config.json,
+ * without the interactive sync handshake.
+ *
+ * Throws on invalid alias, or if the caller (config entry or key dir) exists.
+ */
+export function createCallerWithKeys(alias, opts = {}) {
+    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');
+    }
+    const config = loadRemoteConfig();
+    if (alias in config.callers || callerExists(alias)) {
+        throw new Error(`Caller "${alias}" already exists`);
+    }
+    // Generate the caller's keypair under keys/callers/<alias>/.
+    const { publicKeys, fingerprint } = createCaller(alias);
+    const name = opts.name ?? alias;
+    const defaultCaller = config.callers.default;
+    const connections = opts.connections ?? [...(defaultCaller?.connections ?? [])];
+    config.callers[alias] = { name, connections };
+    saveRemoteConfig(config);
+    log.info(`Created caller "${alias}" with keypair (${connections.length} connection(s), fingerprint ${fingerprint})`);
+    return {
+        alias,
+        name,
+        fingerprint,
+        publicKeys,
+        keysDir: path.join(getCallerKeysDir(), alias),
+        connections,
+    };
+}
+/**
+ * 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}"`);
+}
+// ── Loopback / shared-fs auto-enroll ───────────────────────────────────────
+/** Path of the one-time enroll token file inside the config dir. */
+export function getEnrollTokenPath() {
+    return path.join(getConfigDir(), 'enroll.token');
+}
+/**
+ * Write a fresh one-time enroll token into the config dir (mode 0600).
+ *
+ * Only a process with filesystem access to drawlatch's config dir can read it,
+ * which is exactly the proof-of-co-location we want for `autoEnroll()`.
+ * Called once at daemon startup; overwrites any stale token.
+ */
+export function writeEnrollToken() {
+    const token = randomBytes(32).toString('hex');
+    const tokenPath = getEnrollTokenPath();
+    fs.mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tokenPath, token, { mode: 0o600 });
+    return token;
+}
+/** Constant-time compare of the presented token against the on-disk token. */
+function tokenMatches(presented) {
+    const tokenPath = getEnrollTokenPath();
+    if (!fs.existsSync(tokenPath))
+        return false;
+    const onDisk = fs.readFileSync(tokenPath, 'utf8').trim();
+    const a = Buffer.from(onDisk);
+    const b = Buffer.from(presented);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * Auto-enroll a co-located caller by presenting the one-time enroll token.
+ *
+ * Verifies the token proves filesystem access to the config dir, then either
+ * creates a new caller with keys (if the alias is new) or returns the existing
+ * one's metadata (idempotent). The token is single-use: it is rotated on every
+ * successful enroll so a leaked token cannot be replayed.
+ */
+export function autoEnroll(token, alias, opts = {}) {
+    if (!tokenMatches(token)) {
+        throw new Error('Invalid or expired enroll token');
+    }
+    const result = createCallerWithKeys(alias, opts);
+    // Rotate the token so it cannot be replayed.
+    writeEnrollToken();
+    return result;
+}
+//# 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,