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

package/dist/remote/ingestors/webhook/trello-webhook-ingestor.d.ts

@@ -17,12 +17,24 @@ import { WebhookIngestor } from './base-webhook-ingestor.js';
 import type { WebhookIngestorConfig } from '../types.js';
 export declare class TrelloWebhookIngestor extends WebhookIngestor {
     /**
-     * The callback URL used when the webhook was registered with Trello.
-     * Needed for signature verification (Trello signs `body + callbackURL`).
-     * Resolved from ${VAR} placeholders in the webhook config.
+     * Board ID filter for multi-instance support.
+     * When set, only webhooks from this specific board are accepted.
+     * Set via `_boardId` on the webhook config (injected by IngestorManager).
      */
-    private readonly callbackUrl;
-    constructor(connectionAlias: string, secrets: Record<string, string>, webhookConfig: WebhookIngestorConfig, bufferSize?: number);
+    private readonly boardId;
+    constructor(connectionAlias: string, secrets: Record<string, string>, webhookConfig: WebhookIngestorConfig, bufferSize?: number, instanceId?: string);
+    /**
+     * Return the board ID for lifecycle webhook registration.
+     * Used by the lifecycle manager to match existing webhooks by model ID
+     * and clean up stale registrations.
+     */
+    protected getModelId(): string | undefined;
+    /**
+     * Filter webhooks by board ID for multi-instance support.
+     * When boardId is set, only events from that specific board are accepted.
+     * The board ID is found in `body.model.id` of Trello webhook payloads.
+     */
+    protected shouldAcceptPayload(body: unknown): boolean;
     /**
      * Verify the Trello webhook signature (HMAC-SHA1, base64-encoded).
      *

package/dist/remote/ingestors/webhook/trello-webhook-ingestor.js

@@ -18,32 +18,38 @@ import { WebhookIngestor } from './base-webhook-ingestor.js';
 import { verifyTrelloSignature, extractTrelloActionType, extractTrelloActionId, TRELLO_SIGNATURE_HEADER, } from './trello-types.js';
 import { createLogger } from '../../../shared/logger.js';
 const log = createLogger('webhook');
-// ── Placeholder resolution ──────────────────────────────────────────────
-/**
- * Resolve ${VAR} placeholders in a string using a secrets map.
- * Returns the original string if no placeholders are found.
- */
-function resolvePlaceholder(value, secrets) {
-    return value.replace(/\$\{(\w+)\}/g, (match, name) => {
-        if (name in secrets)
-            return secrets[name];
-        return match;
-    });
-}
 // ── Trello Webhook Ingestor ─────────────────────────────────────────────
 export class TrelloWebhookIngestor extends WebhookIngestor {
     /**
-     * The callback URL used when the webhook was registered with Trello.
-     * Needed for signature verification (Trello signs `body + callbackURL`).
-     * Resolved from ${VAR} placeholders in the webhook config.
+     * Board ID filter for multi-instance support.
+     * When set, only webhooks from this specific board are accepted.
+     * Set via `_boardId` on the webhook config (injected by IngestorManager).
      */
-    callbackUrl;
-    constructor(connectionAlias, secrets, webhookConfig, bufferSize) {
-        super(connectionAlias, secrets, webhookConfig, bufferSize);
-        // Resolve callbackUrl from secrets if it contains ${VAR} placeholders
-        if (webhookConfig.callbackUrl) {
-            this.callbackUrl = resolvePlaceholder(webhookConfig.callbackUrl, secrets);
-        }
+    boardId;
+    constructor(connectionAlias, secrets, webhookConfig, bufferSize, instanceId) {
+        super(connectionAlias, secrets, webhookConfig, bufferSize, instanceId);
+        // Board ID filter for multi-instance discrimination
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any -- injected by IngestorManager for multi-instance support
+        this.boardId = webhookConfig._boardId;
+    }
+    /**
+     * Return the board ID for lifecycle webhook registration.
+     * Used by the lifecycle manager to match existing webhooks by model ID
+     * and clean up stale registrations.
+     */
+    getModelId() {
+        return this.boardId;
+    }
+    /**
+     * Filter webhooks by board ID for multi-instance support.
+     * When boardId is set, only events from that specific board are accepted.
+     * The board ID is found in `body.model.id` of Trello webhook payloads.
+     */
+    shouldAcceptPayload(body) {
+        if (!this.boardId)
+            return true;
+        const payload = body;
+        return payload.model?.id === this.boardId;
     }
     /**
      * Verify the Trello webhook signature (HMAC-SHA1, base64-encoded).
@@ -64,7 +70,7 @@ export class TrelloWebhookIngestor extends WebhookIngestor {
                 `in resolved secrets for ${this.connectionAlias}`);
             return { valid: false, reason: 'Signature secret not configured' };
         }
-        if (!this.callbackUrl) {
+        if (!this.resolvedCallbackUrl) {
             log.error(`Callback URL not configured for ${this.connectionAlias}. ` +
                 `Trello signature verification requires the callbackUrl.`);
             return { valid: false, reason: 'Callback URL not configured' };
@@ -75,7 +81,7 @@ export class TrelloWebhookIngestor extends WebhookIngestor {
         if (!signatureValue) {
             return { valid: false, reason: 'Missing signature header' };
         }
-        if (!verifyTrelloSignature(rawBody, signatureValue, secret, this.callbackUrl)) {
+        if (!verifyTrelloSignature(rawBody, signatureValue, secret, this.resolvedCallbackUrl)) {
             log.warn(`Signature verification failed for ${this.connectionAlias}`);
             return { valid: false, reason: 'Signature verification failed' };
         }
@@ -116,11 +122,11 @@ export class TrelloWebhookIngestor extends WebhookIngestor {
     }
 }
 // ── Self-registration ───────────────────────────────────────────────────
-registerIngestorFactory('webhook:trello', (connectionAlias, config, secrets, bufferSize) => {
+registerIngestorFactory('webhook:trello', (connectionAlias, config, secrets, bufferSize, instanceId) => {
     if (!config.webhook) {
         log.error(`Missing webhook config for ${connectionAlias}`);
         return null;
     }
-    return new TrelloWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize);
+    return new TrelloWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize, instanceId);
 });
 //# sourceMappingURL=trello-webhook-ingestor.js.map

package/dist/remote/ingestors/webhook/webhook-lifecycle-manager.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Webhook Lifecycle Manager.
+ *
+ * Stateless utility that executes declarative lifecycle HTTP requests to
+ * list, register, and unregister webhooks with external services.
+ *
+ * Used by webhook ingestors with a `lifecycle` config block to auto-register
+ * webhooks on start, clean up stale registrations (e.g., after tunnel URL changes),
+ * and unregister on permanent shutdown or instance deletion.
+ *
+ * All HTTP requests use native `fetch()` directly (not proxy routes) since
+ * secrets are already resolved and lifecycle URLs may not match the
+ * connection's `allowedEndpoints` patterns.
+ */
+import type { WebhookLifecycleConfig, WebhookRegistrationState } from './lifecycle-types.js';
+export declare class WebhookLifecycleManager {
+    private readonly config;
+    private readonly secrets;
+    constructor(config: WebhookLifecycleConfig, secrets: Record<string, string>);
+    /**
+     * Ensure a webhook is registered with the external service (idempotent).
+     *
+     * Flow:
+     * 1. If `list` config exists → fetch existing webhooks, find one matching
+     *    callbackUrl (+ modelId if provided) → reuse if found
+     * 2. Find stale webhooks (matching modelId but wrong callbackUrl) → unregister each
+     * 3. If no match → call `register` to create a new webhook
+     *
+     * Graceful degradation: if `list` fails, attempts direct `register`.
+     * All errors are caught and returned in the state object.
+     */
+    ensureRegistered(callbackUrl: string, modelId?: string): Promise<WebhookRegistrationState>;
+    /**
+     * Unregister a webhook by ID.
+     * Replaces `${_webhookId}` in the unregister URL with the given ID.
+     * Errors are logged but never thrown.
+     */
+    unregister(webhookId: string): Promise<void>;
+    /** Fetch the list of existing webhooks from the external service. */
+    private listWebhooks;
+    /** Register a new webhook with the external service. */
+    private register;
+    /** Resolve headers with placeholder substitution. */
+    private resolveHeaders;
+}
+//# sourceMappingURL=webhook-lifecycle-manager.d.ts.map

package/dist/remote/ingestors/webhook/webhook-lifecycle-manager.js

@@ -0,0 +1,261 @@
+/**
+ * Webhook Lifecycle Manager.
+ *
+ * Stateless utility that executes declarative lifecycle HTTP requests to
+ * list, register, and unregister webhooks with external services.
+ *
+ * Used by webhook ingestors with a `lifecycle` config block to auto-register
+ * webhooks on start, clean up stale registrations (e.g., after tunnel URL changes),
+ * and unregister on permanent shutdown or instance deletion.
+ *
+ * All HTTP requests use native `fetch()` directly (not proxy routes) since
+ * secrets are already resolved and lifecycle URLs may not match the
+ * connection's `allowedEndpoints` patterns.
+ */
+import { resolvePlaceholders } from '../../../shared/config.js';
+import { createLogger } from '../../../shared/logger.js';
+const log = createLogger('webhook-lifecycle');
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Recursively resolve `${VAR}` placeholders in an object tree.
+ * Walks objects and arrays, resolving placeholders in all string values.
+ */
+function resolveDeep(value, secrets) {
+    if (typeof value === 'string') {
+        return resolvePlaceholders(value, secrets);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => resolveDeep(item, secrets));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = resolveDeep(v, secrets);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Extract a value from a nested object using a dot-separated path.
+ * E.g., `getByPath(obj, 'data.webhooks')` → `obj.data.webhooks`.
+ */
+function getByPath(obj, path) {
+    let current = obj;
+    for (const segment of path.split('.')) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+// ── Lifecycle Manager ────────────────────────────────────────────────────
+export class WebhookLifecycleManager {
+    config;
+    secrets;
+    constructor(config, secrets) {
+        this.config = config;
+        this.secrets = secrets;
+    }
+    /**
+     * Ensure a webhook is registered with the external service (idempotent).
+     *
+     * Flow:
+     * 1. If `list` config exists → fetch existing webhooks, find one matching
+     *    callbackUrl (+ modelId if provided) → reuse if found
+     * 2. Find stale webhooks (matching modelId but wrong callbackUrl) → unregister each
+     * 3. If no match → call `register` to create a new webhook
+     *
+     * Graceful degradation: if `list` fails, attempts direct `register`.
+     * All errors are caught and returned in the state object.
+     */
+    async ensureRegistered(callbackUrl, modelId) {
+        const now = new Date().toISOString();
+        try {
+            // Try to discover existing webhooks
+            let existingWebhooks = null;
+            if (this.config.list) {
+                try {
+                    existingWebhooks = await this.listWebhooks();
+                }
+                catch (err) {
+                    log.warn('Failed to list existing webhooks, attempting direct registration:', err);
+                    // Fall through to register
+                }
+            }
+            if (existingWebhooks !== null && this.config.list) {
+                const listConfig = this.config.list;
+                // Find a webhook matching our callback URL (and model ID if applicable)
+                const matching = existingWebhooks.find((wh) => {
+                    const rawUrl = getByPath(wh, listConfig.callbackUrlField);
+                    const whCallbackUrl = typeof rawUrl === 'string' ? rawUrl : '';
+                    const urlMatch = whCallbackUrl === callbackUrl;
+                    if (!urlMatch)
+                        return false;
+                    if (modelId && listConfig.modelIdField) {
+                        const rawModelId = getByPath(wh, listConfig.modelIdField);
+                        return (typeof rawModelId === 'string' ? rawModelId : '') === modelId;
+                    }
+                    return true;
+                });
+                if (matching) {
+                    const webhookId = String(getByPath(matching, listConfig.idField));
+                    log.info(`Found existing webhook (ID: ${webhookId}), reusing`);
+                    return { registered: true, webhookId, lastAttempt: now };
+                }
+                // Clean up stale webhooks (matching model but wrong callback URL)
+                if (modelId && listConfig.modelIdField && this.config.unregister) {
+                    const stale = existingWebhooks.filter((wh) => {
+                        const rawModelId = getByPath(wh, listConfig.modelIdField);
+                        const whModelId = typeof rawModelId === 'string' ? rawModelId : '';
+                        const rawUrl = getByPath(wh, listConfig.callbackUrlField);
+                        const whCallbackUrl = typeof rawUrl === 'string' ? rawUrl : '';
+                        return whModelId === modelId && whCallbackUrl !== callbackUrl;
+                    });
+                    for (const staleWh of stale) {
+                        const staleId = String(getByPath(staleWh, listConfig.idField));
+                        log.info(`Cleaning up stale webhook (ID: ${staleId})`);
+                        try {
+                            await this.unregister(staleId);
+                        }
+                        catch (err) {
+                            log.warn(`Failed to clean up stale webhook ${staleId}:`, err);
+                        }
+                    }
+                }
+            }
+            // No existing match — register a new webhook
+            if (this.config.register) {
+                return await this.register(callbackUrl, modelId);
+            }
+            // No register config — can't auto-register
+            return { registered: false, error: 'No register config defined', lastAttempt: now };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            log.error('Webhook lifecycle error:', error);
+            return { registered: false, error, lastAttempt: now };
+        }
+    }
+    /**
+     * Unregister a webhook by ID.
+     * Replaces `${_webhookId}` in the unregister URL with the given ID.
+     * Errors are logged but never thrown.
+     */
+    async unregister(webhookId) {
+        if (!this.config.unregister) {
+            log.warn('No unregister config defined, skipping');
+            return;
+        }
+        const mergedSecrets = { ...this.secrets, _webhookId: webhookId };
+        const url = resolvePlaceholders(this.config.unregister.url, mergedSecrets);
+        const headers = this.resolveHeaders(this.config.unregister.headers, mergedSecrets);
+        try {
+            const resp = await fetch(url, {
+                method: this.config.unregister.method,
+                headers,
+            });
+            if (!resp.ok) {
+                const body = await resp.text().catch(() => '');
+                log.warn(`Webhook unregister failed (${resp.status}): ${body}`);
+            }
+            else {
+                log.info(`Webhook unregistered (ID: ${webhookId})`);
+            }
+        }
+        catch (err) {
+            log.warn(`Webhook unregister request failed for ${webhookId}:`, err);
+        }
+    }
+    // ── Private helpers ────────────────────────────────────────────────────
+    /** Fetch the list of existing webhooks from the external service. */
+    async listWebhooks() {
+        const listConfig = this.config.list;
+        const url = resolvePlaceholders(listConfig.url, this.secrets);
+        const headers = this.resolveHeaders(listConfig.headers);
+        const resp = await fetch(url, {
+            method: listConfig.method,
+            headers,
+        });
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => '');
+            throw new Error(`List webhooks failed (${resp.status}): ${body}`);
+        }
+        const json = await resp.json();
+        // Extract array from response (may be nested under a dot-path)
+        let webhooks;
+        if (listConfig.responsePath) {
+            webhooks = getByPath(json, listConfig.responsePath);
+        }
+        else {
+            webhooks = json;
+        }
+        if (!Array.isArray(webhooks)) {
+            throw new Error(`Expected array from list endpoint${listConfig.responsePath ? ` at path "${listConfig.responsePath}"` : ''}, got ${typeof webhooks}`);
+        }
+        return webhooks;
+    }
+    /** Register a new webhook with the external service. */
+    async register(callbackUrl, modelId) {
+        const now = new Date().toISOString();
+        const registerConfig = this.config.register;
+        // Merge callbackUrl and modelId into resolution context
+        const mergedSecrets = { ...this.secrets };
+        if (callbackUrl)
+            mergedSecrets.CALLBACK_URL = callbackUrl;
+        if (modelId)
+            mergedSecrets.MODEL_ID = modelId;
+        const url = resolvePlaceholders(registerConfig.url, mergedSecrets);
+        const headers = this.resolveHeaders(registerConfig.headers, mergedSecrets);
+        const fetchOptions = {
+            method: registerConfig.method,
+            headers,
+        };
+        if (registerConfig.body) {
+            const resolvedBody = resolveDeep(registerConfig.body, mergedSecrets);
+            fetchOptions.body = JSON.stringify(resolvedBody);
+            // Ensure Content-Type is set if there's a body
+            if (!headers['Content-Type'] && !headers['content-type']) {
+                headers['Content-Type'] = 'application/json';
+            }
+        }
+        const resp = await fetch(url, fetchOptions);
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => '');
+            return {
+                registered: false,
+                error: `Register failed (${resp.status}): ${body}`,
+                lastAttempt: now,
+            };
+        }
+        const json = await resp.json();
+        const rawWebhookId = json[registerConfig.idField];
+        const webhookId = typeof rawWebhookId === 'string'
+            ? rawWebhookId
+            : typeof rawWebhookId === 'number'
+                ? String(rawWebhookId)
+                : '';
+        if (!webhookId) {
+            return {
+                registered: false,
+                error: `Register response missing "${registerConfig.idField}" field`,
+                lastAttempt: now,
+            };
+        }
+        log.info(`Webhook registered (ID: ${webhookId})`);
+        return { registered: true, webhookId, lastAttempt: now };
+    }
+    /** Resolve headers with placeholder substitution. */
+    resolveHeaders(headers, secretsOverride) {
+        if (!headers)
+            return {};
+        const secrets = secretsOverride ?? this.secrets;
+        const resolved = {};
+        for (const [key, value] of Object.entries(headers)) {
+            resolved[key] = resolvePlaceholders(value, secrets);
+        }
+        return resolved;
+    }
+}
+//# sourceMappingURL=webhook-lifecycle-manager.js.map

package/dist/remote/server.d.ts

@@ -12,6 +12,7 @@
  *   - Maintains an audit log of all operations
  *   - Rate-limits requests per session
  */
+import express from 'express';
 import { type RemoteServerConfig, type ResolvedRoute } from '../shared/config.js';
 import { EncryptedChannel, type PublicKeyBundle } from '../shared/crypto/index.js';
 import { HandshakeResponder, type HandshakeInit } from '../shared/protocol/index.js';
@@ -43,13 +44,25 @@ export interface PendingHandshake {
     init: HandshakeInit;
     createdAt: number;
 }
-export declare function isEndpointAllowed(url: string, patterns: string[]): boolean;
+/** Sanitized session projection — never includes channel keys or resolved
+ *  routes (which carry decrypted secrets). Returned by getSessionsSnapshot()
+ *  for the read-only /admin API. */
+export interface SessionSnapshot {
+    /** First 12 chars of the session ID — enough to disambiguate, doesn't
+     *  expose enough material to forge or replay encrypted requests. */
+    sessionIdShort: string;
+    callerAlias: string;
+    createdAt: number;
+    lastActivity: number;
+    requestCount: number;
+    windowRequests: number;
+    windowStart: number;
+}
+/** Loopback guard — used by /sync/listen, /sync/status, /events/stream, /admin.
+ *  Hoisted to module scope so the admin router and its tests can reuse it. */
+export declare function requireLoopback(req: express.Request, res: express.Response, next: express.NextFunction): void;
 export { resolvePlaceholders } from '../shared/config.js';
-/**
- * Find the first route whose allowedEndpoints match the given URL.
- * Routes with empty allowedEndpoints match nothing.
- */
-export declare function matchRoute(url: string, routes: ResolvedRoute[]): ResolvedRoute | null;
+export { toolHandlers, executeProxyRequest, isEndpointAllowed, matchRoute, type ToolContext, type ProxyRequestInput, type ProxyRequestResult, type FileAttachment, } from './tool-dispatch.js';
 export declare function checkRateLimit(session: Pick<Session, 'windowRequests' | 'windowStart'>, limit: number): boolean;
 export declare const SESSION_TTL: number;
 export declare const HANDSHAKE_TTL: number;
@@ -57,36 +70,13 @@ export declare function cleanupSessions(sessionsMap: Map<string, Pick<Session, '
     expiredSessions: string[];
     expiredHandshakes: string[];
 };
-export interface ProxyRequestInput {
-    method: string;
-    url: string;
-    headers?: Record<string, string>;
-    body?: unknown;
-}
-export interface ProxyRequestResult {
-    status: number;
-    statusText: string;
-    headers: Record<string, string>;
-    body: unknown;
-}
 /**
- * Core proxy request execution — route matching, secret injection, and fetch.
+ * Project the active sessions into a sanitized snapshot for read-only use.
  *
- * Used by:
- * - The remote server's `http_request` tool handler (this file)
- * - callboard's `LocalProxy` class (in-process, no encryption)
- *
- * Pure in the sense that it takes routes as input rather than reading global state.
- * The only side effect is the outbound fetch().
+ * Drops `channel` (holds AES keys) and `resolvedRoutes` (carry decrypted
+ * secrets). Used by the loopback /admin API; never call res.json(session).
  */
-export declare function executeProxyRequest(input: ProxyRequestInput, routes: ResolvedRoute[]): Promise<ProxyRequestResult>;
-/** Context passed to every tool handler, providing caller identity and shared services. */
-export interface ToolContext {
-    /** The caller alias for the session making this request. */
-    callerAlias: string;
-    /** The shared ingestor manager (for poll_events / ingestor_status). */
-    ingestorManager: IngestorManager;
-}
+export declare function getSessionsSnapshot(): SessionSnapshot[];
 /** Options for creating the app — allows dependency injection for tests */
 export interface CreateAppOptions {
     /** Override config instead of loading from disk */
@@ -97,6 +87,8 @@ export interface CreateAppOptions {
     authorizedPeers?: AuthorizedPeer[];
     /** Override the ingestor manager instead of creating one from config */
     ingestorManager?: IngestorManager;
+    /** Disable per-IP rate limiting (for tests that make many requests from localhost) */
+    disableRateLimiting?: boolean;
 }
 export declare function createApp(options?: CreateAppOptions): import("express-serve-static-core").Express;
 export declare function main(): void;